มาโครเดิม

มาโครเดิมคือฟังก์ชันที่ไม่มีโครงสร้างซึ่งเรียกจากไฟล์ 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()) สามารถสร้างได้ จากโมดูล ดั้งเดิม:

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,
  )

เมื่อเปิดใช้แฟล็ก --incompatible_eagerly_resolve_select_keys ระบบจะแก้ปัญหาคีย์ทั้งหมด ที่เป็นสตริงป้ายกำกับเป็นออบเจ็กต์ Label แบบสัมพันธ์กับแพ็กเกจของไฟล์ที่มีการเรียก select โดยอัตโนมัติ หากไม่เลือกตัวเลือกนี้ ให้ห่อหุ้มสตริงป้ายกำกับด้วย native.package_relative_label()

การแก้ไขข้อบกพร่อง

• bazel query --output=build //my/path:all จะแสดงลักษณะของไฟล์ BUILD หลังจากประเมิน มาโครเดิม, glob และลูปทั้งหมดจะขยาย ข้อจำกัดที่ทราบ: ระบบจะไม่แสดงนิพจน์ 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 ของมาโครต้องเป็นอาร์กิวเมนต์คีย์เวิร์ด (ไม่ใช่ positional argument)

• แอตทริบิวต์ name ของกฎที่สร้างโดยมาโครควรมีอาร์กิวเมนต์ name เป็นคำนำหน้า ตัวอย่างเช่น macro(name = "foo") สามารถสร้าง cc_library foo และ genrule foo_gen

• ในกรณีส่วนใหญ่ พารามิเตอร์ที่ไม่บังคับควรมีค่าเริ่มต้นเป็น None คุณสามารถส่ง None ไปยังกฎดั้งเดิมได้โดยตรง ซึ่งจะถือว่าเหมือนกับว่าคุณไม่ได้ส่งอาร์กิวเมนต์ใดๆ ดังนั้นจึงไม่จำเป็นต้องแทนที่ด้วย 0, False หรือ [] เพื่อจุดประสงค์นี้ แต่มาโครควรเลื่อนการดำเนินการไปยังกฎที่สร้างขึ้น เนื่องจากค่าเริ่มต้นของกฎอาจซับซ้อนหรืออาจเปลี่ยนแปลงไปตามเวลา นอกจากนี้ พารามิเตอร์ที่ตั้งค่าเป็นค่าเริ่มต้นอย่างชัดเจนจะมีลักษณะแตกต่างจากพารามิเตอร์ที่ไม่เคยตั้งค่า (หรือตั้งค่าเป็น None) เมื่อเข้าถึงผ่านภาษาการค้นหาหรือส่วนภายในของระบบบิลด์

• มาโครควรมีอาร์กิวเมนต์ visibility ที่ไม่บังคับ