มาโคร

รายงานปัญหา ดูแหล่งที่มา

หน้านี้ครอบคลุมพื้นฐานของการใช้มาโครและมีกรณีการใช้งานทั่วไป การแก้ไขข้อบกพร่อง และแบบแผน

มาโครเป็นฟังก์ชันที่เรียกใช้จากไฟล์ 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 (ไม่บังคับ)