หน้านี้ครอบคลุมพื้นฐานของการใช้มาโครและมีกรณีการใช้งานทั่วไป การแก้ไขข้อบกพร่อง และแบบแผน
มาโครเป็นฟังก์ชันที่เรียกใช้จากไฟล์ BUILD
ซึ่งสามารถสร้างอินสแตนซ์ของกฎได้
โดยหลักแล้วมาโครจะใช้สำหรับการห่อหุ้มและนำโค้ดกลับมาใช้ซ้ำของกฎที่มีอยู่และมาโครอื่นๆ เมื่อถึงช่วงท้ายของระยะการโหลด มาโครจะไม่มีอีกต่อไปแล้ว และบาเซิลเห็นเพียงชุดกฎเริ่มต้นอย่างเป็นรูปธรรม
การใช้งาน
กรณีการใช้งานทั่วไปของมาโครคือเมื่อคุณต้องการใช้กฎซ้ำ
ตัวอย่างเช่น genrule ในไฟล์ BUILD
จะสร้างไฟล์โดยใช้ //:generator
ที่มีฮาร์ดโค้ดอาร์กิวเมนต์ some_arg
ในคำสั่ง ดังนี้
genrule(
name = "file",
outs = ["file.txt"],
cmd = "$(location //:generator) some_arg > $@",
tools = ["//:generator"],
)
หากต้องการสร้างไฟล์เพิ่มเติมที่มีอาร์กิวเมนต์ต่างกัน คุณอาจต้องแยกโค้ดนี้ออกมาเป็นฟังก์ชันมาโคร เราจะเรียกมาโคร file_generator
ซึ่งมีพารามิเตอร์ name
และ arg
แทนที่ Genrule ด้วยข้อมูลต่อไปนี้
load("//path:generator.bzl", "file_generator")
file_generator(
name = "file",
arg = "some_arg",
)
file_generator(
name = "file-two",
arg = "some_arg_two",
)
file_generator(
name = "file-three",
arg = "some_arg_three",
)
ในขั้นตอนนี้ ให้คุณโหลดสัญลักษณ์ file_generator
จากไฟล์ .bzl
ที่อยู่ในแพ็กเกจ //path
การวางคําจํากัดความของฟังก์ชันมาโครในไฟล์ .bzl
แยกต่างหากช่วยให้ไฟล์ BUILD
ของคุณมีความชัดเจนและประกาศได้ชัดเจน และโหลดไฟล์ .bzl
ได้จากแพ็กเกจใดก็ได้ในพื้นที่ทำงาน
สุดท้าย ใน path/generator.bzl
ให้เขียนคำจำกัดความของมาโครเพื่อห่อหุ้มและกำหนดพารามิเตอร์คำจำกัดความดั้งเดิมของมาโคร ดังนี้
def file_generator(name, arg, visibility=None):
native.genrule(
name = name,
outs = [name + ".txt"],
cmd = "$(location //:generator) %s > $@" % arg,
tools = ["//:generator"],
visibility = visibility,
)
คุณยังใช้มาโครเพื่อเชื่อมโยงกฎต่างๆ เข้าด้วยกันได้ด้วย ตัวอย่างนี้แสดงกฎ GenRule แบบเชน โดยที่ Genrule จะใช้เอาต์พุตของ Genrule ก่อนหน้าเป็นอินพุต
def chained_genrules(name, visibility=None):
native.genrule(
name = name + "-one",
outs = [name + ".one"],
cmd = "$(location :tool-one) $@",
tools = [":tool-one"],
visibility = ["//visibility:private"],
)
native.genrule(
name = name + "-two",
srcs = [name + ".one"],
outs = [name + ".two"],
cmd = "$(location :tool-two) $< $@",
tools = [":tool-two"],
visibility = visibility,
)
ตัวอย่างจะกําหนดค่าระดับการเข้าถึงให้กับรุ่นที่ 2 เท่านั้น ซึ่งช่วยให้ผู้เขียนมาโครซ่อนผลลัพธ์ของกฎกลางจากการที่เป้าหมายอื่นๆ ในพื้นที่ทำงานกำหนดได้
มาโครการขยาย
เมื่อต้องการตรวจสอบการทำงานของมาโคร ให้ใช้คำสั่ง query
กับ --output=build
เพื่อดูแบบฟอร์มแบบขยายดังนี้
$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
name = "file",
tools = ["//:generator"],
outs = ["//test:file.txt"],
cmd = "$(location //:generator) some_arg > $@",
)
การสร้างอินสแตนซ์กฎเนทีฟ
กฎเนทีฟ (กฎที่ไม่ต้องใช้คำสั่ง load()
) จะสร้างขึ้นจากโมดูลเนทีฟได้ ดังนี้
def my_macro(name, visibility=None):
native.cc_library(
name = name,
srcs = ["main.cc"],
visibility = visibility,
)
หากต้องการทราบชื่อแพ็กเกจ (เช่น ไฟล์ BUILD
ที่เรียกมาโคร) ให้ใช้ฟังก์ชัน native.package_name()
โปรดทราบว่า native
ใช้ได้ในไฟล์ .bzl
เท่านั้น และจะใช้ในไฟล์ BUILD
ไม่ได้
ความละเอียดป้ายกำกับในมาโคร
เนื่องจากมาโครจะได้รับการประเมินในระยะการโหลด สตริงป้ายกำกับ เช่น "//foo:bar"
ที่เกิดขึ้นในมาโครจะได้รับการตีความที่เกี่ยวข้องกับไฟล์ BUILD
ที่ใช้มาโครแทนที่จะสัมพันธ์กับไฟล์ .bzl
ที่กําหนดไว้ โดยทั่วไปลักษณะการทำงานนี้ไม่พึงปรารถนาสำหรับมาโครที่มีไว้ใช้ในที่เก็บอื่นๆ เช่น เนื่องจากเป็นส่วนหนึ่งของชุดกฎ Starlark ที่เผยแพร่แล้ว
หากต้องการใช้ลักษณะการทำงานเดียวกันกับกฎ Starlark ให้รวมสตริงป้ายกำกับด้วยตัวสร้าง Label
ดังนี้
# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
native.cc_library(
name = name,
deps = deps + select({
# Due to the use of Label, this label is resolved within @my_ruleset,
# regardless of its site of use.
Label("//config:needs_foo"): [
# Due to the use of Label, this label will resolve to the correct target
# even if the canonical name of @dep_of_my_ruleset should be different
# in the main repo, such as due to repo mappings.
Label("@dep_of_my_ruleset//tools:foo"),
],
"//conditions:default": [],
}),
**kwargs,
)
การแก้ไขข้อบกพร่อง
bazel query --output=build //my/path:all
จะแสดงหน้าตาของไฟล์BUILD
หลังการประเมิน ระบบจะขยายมาโคร กลอบ ลูปทั้งหมด ข้อจำกัดที่ทราบ: ขณะนี้นิพจน์select
รายการจะไม่แสดงในเอาต์พุตคุณอาจกรองผลลัพธ์ตาม
generator_function
(ฟังก์ชันที่สร้างกฎ) หรือgenerator_name
(แอตทริบิวต์ชื่อของมาโคร) ดังนี้bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
หากต้องการดูว่ากฎ
foo
สร้างขึ้นที่ใดในไฟล์BUILD
ลองทำตามเคล็ดลับต่อไปนี้ แทรกบรรทัดนี้ใกล้กับด้านบนของไฟล์BUILD
:cc_library(name = "foo")
เรียกใช้ Bazel คุณจะได้รับข้อยกเว้นเมื่อมีการสร้างกฎfoo
(เนื่องจากชื่อขัดแย้งกัน) ซึ่งจะแสดงสแต็กเทรซทั้งสแต็กนอกจากนี้คุณยังใช้ print เพื่อแก้ไขข้อบกพร่องได้ด้วย โดยจะแสดงข้อความเป็นบรรทัดในบันทึก
DEBUG
ระหว่างระยะการโหลด ยกเว้นในกรณีที่เกิดขึ้นไม่บ่อยนัก ให้นำการเรียกprint
ออกหรือทำให้มีเงื่อนไขภายใต้พารามิเตอร์debugging
ที่มีค่าเริ่มต้นเป็นFalse
ก่อนที่จะส่งโค้ดไปยัง Depot
ข้อผิดพลาด
หากต้องการให้แสดงข้อผิดพลาด ให้ใช้ฟังก์ชัน fail
อธิบายให้ผู้ใช้ทราบอย่างชัดเจนถึงข้อผิดพลาดและวิธีแก้ไขไฟล์ BUILD
ไม่พบข้อผิดพลาด
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
การประชุม
ฟังก์ชันสาธารณะทั้งหมด (ฟังก์ชันที่ไม่ได้ขึ้นต้นด้วยขีดล่าง) ที่กฎพื้นฐานต้องมีอาร์กิวเมนต์
name
อาร์กิวเมนต์นี้ไม่ควรไม่บังคับ (อย่าใช้ค่าเริ่มต้น)ฟังก์ชันสาธารณะควรใช้สตริงเอกสารตามแบบแผนของ Python
ในไฟล์
BUILD
อาร์กิวเมนต์name
ของมาโครต้องเป็นอาร์กิวเมนต์คีย์เวิร์ด (ไม่ใช่อาร์กิวเมนต์ตำแหน่ง)แอตทริบิวต์
name
ของกฎที่มาโครสร้างขึ้นควรมีอาร์กิวเมนต์ชื่อเป็นคำนำหน้า เช่นmacro(name = "foo")
สามารถสร้างfoo
cc_library
และกฎfoo_gen
ได้ในกรณีส่วนใหญ่ พารามิเตอร์ที่ไม่บังคับควรมีค่าเริ่มต้นเป็น
None
สามารถส่งNone
ไปยังกฎเนทีฟโดยตรง ซึ่งจะถือว่าไม่มีการส่งผ่านในอาร์กิวเมนต์ใดๆ ดังนั้น คุณจึงไม่จำเป็นต้องแทนที่ค่าด้วย0
,False
หรือ[]
สำหรับวัตถุประสงค์นี้ มาโครควรจะยึดตามกฎที่มาโครสร้างขึ้น เนื่องจากค่าเริ่มต้นอาจซับซ้อนหรืออาจเปลี่ยนแปลงเมื่อเวลาผ่านไป นอกจากนี้ พารามิเตอร์ที่ตั้งค่าเป็นค่าเริ่มต้นไว้อย่างชัดแจ้งจะแตกต่างจากพารามิเตอร์ที่ไม่เคยตั้งค่าไว้ (หรือตั้งค่าเป็นNone
) เมื่อเข้าถึงผ่านภาษาในการค้นหาหรือภายในของระบบบิลด์มาโครควรมีอาร์กิวเมนต์
visibility
(ไม่บังคับ)