หน้านี้อธิบายพื้นฐานของการใช้มาโคร รวมถึงกรณีการใช้งานทั่วไป การแก้ไขข้อบกพร่อง และแบบแผน
มาโครคือฟังก์ชันที่เรียกจากไฟล์ BUILD
ซึ่งสามารถสร้างอินสแตนซ์ของกฎได้
มาโครใช้เป็นหลักในการรวมและนําโค้ดของกฎที่มีอยู่และมาโครอื่นๆ มาใช้ซ้ำ เมื่อสิ้นสุดระยะการโหลด มาโครจะไม่อยู่อีกต่อไปและ Bazel จะเห็นเฉพาะชุดกฎที่จำลองขึ้นมาอย่างเป็นรูปธรรมเท่านั้น
การใช้งาน
กรณีการใช้งานทั่วไปของมาโครคือเมื่อคุณต้องการใช้กฎซ้ำ
ตัวอย่างเช่น 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
ให้เขียนคําจํากัดความของมาโครเพื่อรวมและกำหนดพารามิเตอร์ให้กับคําจํากัดความ genrule เดิม
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,
)
ตัวอย่างนี้กําหนดค่าการแสดงผลให้กับ genrule ที่ 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()
) สามารถสร้างจากโมดูล native ดังนี้
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
ก่อนส่งโค้ดไปยังที่เก็บ
ข้อผิดพลาด
หากต้องการแสดงข้อผิดพลาด ให้ใช้ฟังก์ชัน fail
อธิบายให้ผู้ใช้ทราบอย่างชัดเจนว่าเกิดข้อผิดพลาดอะไรขึ้นและวิธีแก้ไขไฟล์ BUILD
ไม่สามารถจับข้อผิดพลาดได้
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
การประชุม
ฟังก์ชันสาธารณะทั้งหมด (ฟังก์ชันที่ไม่ได้ขึ้นต้นด้วยขีดล่าง) ที่กฎสรุปต้องมีอาร์กิวเมนต์
name
อาร์กิวเมนต์นี้ไม่ควรเป็นตัวเลือก (อย่าระบุค่าเริ่มต้น)ฟังก์ชันสาธารณะควรใช้ docstring ตามแบบแผน Python
ในไฟล์
BUILD
อาร์กิวเมนต์name
ของมาโครต้องเป็นอาร์กิวเมนต์คีย์เวิร์ด (ไม่ใช่อาร์กิวเมนต์ตำแหน่ง)แอตทริบิวต์
name
ของกฎที่มาโครสร้างขึ้นควรมีอาร์กิวเมนต์ชื่อเป็นคำนำหน้า เช่นmacro(name = "foo")
สามารถสร้างcc_library
foo
และ genrulefoo_gen
ในกรณีส่วนใหญ่ พารามิเตอร์ที่ไม่บังคับควรมีค่าเริ่มต้นเป็น
None
ระบบอาจส่งNone
ไปยังกฎแบบเนทีฟโดยตรง ซึ่งจะปฏิบัติเช่นเดียวกับคุณไม่ได้ส่งผ่านในอาร์กิวเมนต์ใดๆ ดังนั้นจึงไม่จำเป็นต้องแทนที่ด้วย0
,False
หรือ[]
มาโครควรยึดตามกฎที่สร้างขึ้นแทน เนื่องจากค่าเริ่มต้นของมาโครอาจมีความซับซ้อนหรือเปลี่ยนแปลงเมื่อเวลาผ่านไป นอกจากนี้ พารามิเตอร์ที่ตั้งไว้เป็นค่าเริ่มต้นอย่างชัดเจนจะแตกต่างจากพารามิเตอร์ที่ไม่เคยตั้งค่า (หรือตั้งค่าเป็นNone
) เมื่อเข้าถึงผ่านภาษาการค้นหาหรือภายในของระบบบิลด์มาโครควรมีอาร์กิวเมนต์
visibility
ที่ไม่บังคับ