กฎทั่วไป

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

กฎ

• ชื่อแทน
• config_setting
• กลุ่มไฟล์
• genquery
• การสร้างกฎเกณฑ์
• starlark_doc_extract
• test_suite

ชื่อแทน

ดูแหล่งที่มาของกฎ

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

กฎ alias จะสร้างชื่ออื่นที่อาจเรียกว่ากฎ

ส่วนชื่อแทนจะใช้ได้กับเป้าหมาย "ปกติ" เท่านั้น โดยเฉพาะอย่างยิ่ง ชื่อแทน package_group และ test_suite ไม่ได้

ชื่อแทนอาจมีประโยชน์ในที่เก็บขนาดใหญ่ที่การเปลี่ยนชื่อเป้าหมายทำให้ต้องมีการเปลี่ยนแปลงไฟล์จำนวนมาก นอกจากนี้ยังใช้กฎชื่อแทนเพื่อจัดเก็บการเรียกใช้ฟังก์ชัน select ได้ด้วยหากต้องการใช้ตรรกะดังกล่าวซ้ำกับหลายเป้าหมาย

กฎของชื่อแทนมีการประกาศระดับการเข้าถึงของตัวเอง ในด้านอื่นๆ ทั้งหมด กฎจะทำงานเหมือนกับกฎที่อ้างอิง (เช่น ระบบจะไม่สนใจ testonly ในชื่อแทน และจะใช้เพียงการทดสอบเท่านั้นของกฎที่อ้างอิงแทน) โดยมีข้อยกเว้นเล็กน้อยดังต่อไปนี้

• การทดสอบจะไม่ทำงานหากมีการพูดถึงชื่อแทนในบรรทัดคำสั่ง หากต้องการกำหนดชื่อแทนที่เรียกใช้การทดสอบที่อ้างอิง ให้ใช้กฎ test_suite ที่มีเป้าหมายเดียวในแอตทริบิวต์ tests
• เมื่อกำหนดกลุ่มสภาพแวดล้อม ระบบจะไม่รองรับชื่อแทนของกฎ environment ซึ่งใช้ไม่ได้กับตัวเลือกบรรทัดคำสั่ง --target_environment เช่นกัน

ตัวอย่าง

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
actual	ป้ายกำกับ ต้องระบุ เป้าหมายที่ชื่อแทนนี้อ้างอิง ซึ่งไม่จำเป็นต้องเป็นกฎ และสามารถเป็นไฟล์อินพุตได้ด้วย

config_setting

ดูแหล่งที่มาของกฎ

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

จับคู่สถานะการกำหนดค่าที่คาดหวัง (แสดงเป็นแฟล็กบิลด์หรือข้อจำกัดแพลตฟอร์ม) เพื่อ ทริกเกอร์แอตทริบิวต์ที่กำหนดค่าได้ ดูวิธีใช้กฎนี้และ แอตทริบิวต์ที่กำหนดค่าได้ในส่วนเลือกเพื่อดูภาพรวมของฟีเจอร์ทั่วไป

ตัวอย่าง

รายการต่อไปนี้ตรงกับบิลด์ทั้งหมดที่ตั้งค่า --compilation_mode=opt หรือ -c opt (โดยชัดแจ้งที่บรรทัดคำสั่งหรือโดยปริยายจากไฟล์ .bazelrc)

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

รายการต่อไปนี้ตรงกับบิลด์ใดก็ตามที่กำหนดเป้าหมายเป็น ARM และใช้ FOO=bar คำจำกัดความที่กำหนดเอง (เช่น bazel build --cpu=arm --define FOO=bar ...)

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

รายการต่อไปนี้ตรงกับบิลด์ใดๆ ที่ตั้งค่าแฟล็กที่ผู้ใช้กำหนด --//custom_flags:foo=1 (โดยชัดแจ้งที่บรรทัดคำสั่งหรือโดยนัยจากไฟล์ .bazelrc)

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

รายการต่อไปนี้ตรงกับบิลด์ทั้งหมดที่กำหนดเป้าหมายแพลตฟอร์มด้วยสถาปัตยกรรม x86_64 และ glibc เวอร์ชัน 2.25 โดยสมมติว่ามี constraint_value ที่มีป้ายกำกับ //example:glibc_2_25 อยู่ โปรดทราบว่าแพลตฟอร์มจะยังคงตรงกันหากกำหนดค่าข้อจำกัดเพิ่มเติมที่นอกเหนือจาก 2 ค่านี้

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

ในทุกกรณีเหล่านี้ การกำหนดค่าจะเปลี่ยนแปลงภายในบิลด์ได้ เช่น ในกรณีที่ต้องสร้างเป้าหมายสำหรับแพลตฟอร์มอื่นที่ไม่ตรงกับระดับของแพลตฟอร์ม ซึ่งหมายความว่าแม้ว่า config_setting จะไม่ตรงกับแฟล็กบรรทัดคำสั่งระดับบนสุด แต่ก็อาจยังคงตรงกับเป้าหมายบิลด์บางรายการ

Notes

• ดู select สำหรับสิ่งที่จะเกิดขึ้นเมื่อ config_setting หลายรายการตรงกับสถานะการกำหนดค่าปัจจุบัน
• สำหรับแฟล็กที่รองรับรูปแบบชวเลข (เช่น --compilation_mode กับ -c) คำจำกัดความของ values ต้องใช้แบบฟอร์มแบบเต็ม ซึ่งจะจับคู่คำขอโดยอัตโนมัติโดยใช้แบบฟอร์มใดรูปแบบหนึ่ง
• หากแฟล็กมีค่าหลายค่า (เช่น --copt=-Da --copt=-Db หรือ แฟล็ก Starlark ที่เป็นประเภทรายการ) values = { "flag": "a" } จะจับคู่หาก "a" ปรากฏที่ใดก็ตามในรายการจริง

  values = { "myflag": "a,b" } ทำงานในลักษณะเดียวกัน: จะจับคู่กับ --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b และ --myflag=c,b,a ความหมายที่แน่นอนจะแตกต่างกันไปในแต่ละแฟล็ก เช่น --copt ไม่รองรับหลายค่าในอินสแตนซ์เดียวกัน นั่นคือ --copt=a,b จะสร้าง ["a,b"] ในขณะที่ --copt=a --copt=b จะสร้าง ["a", "b"] (เพื่อให้ values = { "copt": "a,b" } จับคู่กับค่าแรกแต่ไม่จับคู่กับค่าหลัง) แต่ --ios_multi_cpus (สำหรับกฎของ Apple) จะ: -ios_multi_cpus=a,b และ ios_multi_cpus=a --ios_multi_cpus=b ทั้ง 2 อย่างจะให้ผลลัพธ์ ["a", "b"] ตรวจสอบคำจำกัดความของแฟล็กและทดสอบเงื่อนไขอย่างรอบคอบเพื่อยืนยันความคาดหวังที่แน่นอน

• หากต้องการกำหนดเงื่อนไขที่ไม่ได้สร้างโมเดลโดยแฟล็กบิลด์ในตัว ให้ใช้ แฟล็กที่ Starlark กำหนด นอกจากนี้คุณยังใช้ --define ได้ด้วย แต่วิธีนี้ทำให้การสนับสนุนไม่ดีนักและไม่แนะนำให้ใช้ ดูการสนทนาเพิ่มเติมที่นี่
• หลีกเลี่ยงการใช้คำจำกัดความ config_setting ที่ซ้ำกันในแพ็กเกจที่ต่างกัน แต่ให้อ้างอิง config_setting ทั่วไปที่กำหนดไว้ในแพ็กเกจ Canonical แทน
• คุณใช้ values, define_values และ constraint_values ร่วมกับชุดค่าผสมใดก็ได้ใน config_setting เดียวกัน แต่ต้องมีการตั้งค่าอย่างน้อย 1 รายการสำหรับ config_setting ใดๆ ที่กำหนด

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
constraint_values	รายการป้ายกำกับ ไม่สามารถกำหนดค่าได้ ค่าเริ่มต้นคือ [] ชุด constraint_values ขั้นต่ำที่แพลตฟอร์มเป้าหมายต้องระบุเพื่อให้ตรงกับ config_setting นี้ (แพลตฟอร์มการดำเนินการจะไม่พิจารณาที่นี่) และจะไม่สนใจค่าข้อจำกัดเพิ่มเติมใดๆ ที่แพลตฟอร์มไม่สนใจ ดูรายละเอียดได้ที่ แอตทริบิวต์บิลด์ที่กำหนดค่าได้ ในกรณีที่ 2 config_settingทั้งสองตรงกันใน select เหมือนกัน แอตทริบิวต์นี้จะไม่ได้รับการพิจารณาเพื่อ พิจารณาว่าหนึ่งในconfig_settingเป็นความเชี่ยวชาญพิเศษของอีกคนหนึ่งหรือไม่ กล่าวคือ config_setting รายการหนึ่งจะตรงกับแพลตฟอร์มมากกว่าอีกแพลตฟอร์มหนึ่งไม่ได้
define_values	พจนานุกรม: สตริง -> สตริง; nonconfigurable ค่าเริ่มต้นคือ {} เหมือนกับ values แต่สำหรับแฟล็ก --define โดยเฉพาะ --define มีความพิเศษเนื่องจากไวยากรณ์ (--define KEY=VAL) หมายความว่า KEY=VAL เป็นค่าจากมุมมองของแฟล็ก Bazel ซึ่งหมายความว่า config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) ไม่ทำงานเนื่องจากคีย์เดียวกัน (define) ปรากฏ 2 ครั้งในพจนานุกรม แอตทริบิวต์นี้ช่วยแก้ปัญหาดังกล่าวได้ config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) ตรงกับ bazel build //foo --define a=1 --define b=2 อย่างถูกต้อง --define ยังคงปรากฏใน values โดยใช้ไวยากรณ์แฟล็กปกติ และผสมกับแอตทริบิวต์นี้ได้อย่างอิสระตราบใดที่คีย์พจนานุกรมยังคงแตกต่างกัน
flag_values	พจนานุกรม: label -> สตริง; nonconfigurable ค่าเริ่มต้นคือ {} เหมือนกับ values แต่ใช้กับ แฟล็กบิลด์ที่กำหนดโดยผู้ใช้ นี่คือแอตทริบิวต์ที่แตกต่างกัน เนื่องจากมีการอ้างอิงแฟล็กที่ผู้ใช้กำหนดเป็นป้ายกำกับ ขณะที่การแฟล็กในตัวจะอ้างอิงเป็นสตริงที่กำหนดเอง
values	พจนานุกรม: สตริง -> สตริง; nonconfigurable ค่าเริ่มต้นคือ {} ชุดของค่าของการกำหนดค่าที่ตรงกับกฎนี้ (แสดงเป็นแฟล็กบิวด์) กฎนี้รับค่าจากเป้าหมายที่กำหนดค่าซึ่งอ้างอิงเป้าหมายในคำสั่ง select ระบบจะถือว่า "จับคู่" การเรียก Bazel หากการกำหนดค่าตรงกับค่าที่คาดไว้ของรายการทั้งหมดในพจนานุกรม เช่น values = {"compilation_mode": "opt"} ตรงกับคำขอ bazel build --compilation_mode=opt ... และ bazel build -c opt ... ในกฎที่กำหนดเป้าหมาย เพื่อความสะดวก ค่าของการกำหนดค่าจะระบุเป็นแฟล็กบิลด์ (โดยไม่มี "--" ก่อนหน้า) แต่โปรดทราบว่าทั้ง 2 ค่านั้นไม่เหมือนกัน เนื่องจากเป้าหมายสร้างได้จากการกำหนดค่าหลายรายการภายในบิลด์เดียวกัน ตัวอย่างเช่น "cpu" ของการกำหนดค่า exec ตรงกับค่าของ --host_cpu ไม่ใช่ --cpu ดังนั้นอินสแตนซ์ที่ต่างกันของ config_setting เดียวกันอาจตรงกับการเรียกใช้เดียวกันในรูปแบบที่แตกต่างกัน ทั้งนี้ขึ้นอยู่กับการกำหนดค่าของกฎที่ใช้อินสแตนซ์เหล่านั้น หากไม่ได้กำหนดแฟล็กอย่างชัดแจ้งในบรรทัดคำสั่ง ระบบจะใช้ค่าเริ่มต้น หากคีย์ปรากฏขึ้นหลายครั้งในพจนานุกรม ระบบจะใช้เฉพาะอินสแตนซ์สุดท้ายเท่านั้น หากคีย์อ้างอิงแฟล็กที่ตั้งค่าได้หลายครั้งในบรรทัดคำสั่ง (เช่น bazel build --copt=foo --copt=bar --copt=baz ...) การจับคู่จะเกิดขึ้นหากการตั้งค่าใดๆ เหล่านั้นตรงกัน

กลุ่มไฟล์

ดูแหล่งที่มาของกฎ

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

ใช้ filegroup เพื่อตั้งชื่อที่สะดวกสำหรับชุดเป้าหมาย จากนั้นจะอ้างอิงจากกฎอื่นๆ ได้

เราขอแนะนำให้ใช้ filegroup แทนการอ้างอิงไดเรกทอรีโดยตรง เวอร์ชันหลังไม่มีเสียงเนื่องจากระบบบิลด์ไม่มีความรู้ที่สมบูรณ์เกี่ยวกับไฟล์ทั้งหมดที่อยู่ใต้ไดเรกทอรี ระบบจึงสร้างใหม่ไม่ได้เมื่อไฟล์เหล่านี้มีการเปลี่ยนแปลง เมื่อใช้ร่วมกับ glob filegroup จะทำให้ระบบของบิลด์รู้จักไฟล์ทั้งหมดได้อย่างชัดเจน

ตัวอย่าง

หากต้องการสร้าง filegroup ที่ประกอบด้วยไฟล์ต้นฉบับ 2 ไฟล์ ให้ทำ

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

หรือใช้ glob เพื่อค้นหาไดเรกทอรี testdata:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

หากต้องการใช้คําจํากัดความเหล่านี้ ให้อ้างอิง filegroup ที่มีป้ายกํากับจากกฎใดๆ ต่อไปนี้

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
srcs	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการเป้าหมายที่เป็นสมาชิกของกลุ่มไฟล์ เป็นเรื่องปกติที่จะใช้ผลลัพธ์ของนิพจน์ glob สำหรับค่าของแอตทริบิวต์ srcs
data	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการไฟล์ที่กฎนี้ต้องการในระหว่างรันไทม์ ระบบจะเพิ่มเป้าหมายที่มีชื่อในแอตทริบิวต์ data ลงใน runfiles ของกฎ filegroup นี้ เมื่อมีการอ้างอิง filegroup ในแอตทริบิวต์ data ของกฎอื่น ระบบจะเพิ่ม runfiles ลงใน runfiles ของกฎโดยขึ้นอยู่กับกฎนั้นๆ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการอ้างอิงและใช้ไฟล์ข้อมูลได้ในส่วนการอ้างอิงข้อมูลและเอกสารทั่วไปของ data
output_group	สตริง ค่าเริ่มต้นคือ "" กลุ่มเอาต์พุตที่จะรวบรวมอาร์ติแฟกต์จากแหล่งที่มา หากระบุแอตทริบิวต์นี้ ระบบจะส่งออกอาร์ติแฟกต์จากกลุ่มเอาต์พุตที่ระบุของทรัพยากร Dependency แทนกลุ่มเอาต์พุตเริ่มต้น "กลุ่มเอาต์พุต" คือหมวดหมู่อาร์ติแฟกต์เอาต์พุตของเป้าหมายที่ระบุไว้ในการใช้งานกฎดังกล่าว

Genquery

ดูแหล่งที่มาของกฎ

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() เรียกใช้การค้นหาที่ระบุในภาษาของการค้นหา Blaze และดัมพ์ผลลัพธ์ลงในไฟล์

ระบบจะอนุญาตให้การค้นหาเข้าชมการปิดเป้าหมายที่ระบุในแอตทริบิวต์ scope เท่านั้นเพื่อให้บิลด์สอดคล้องกัน การค้นหาที่ละเมิดกฎนี้จะดำเนินการไม่สำเร็จหากไม่ได้ระบุ strict หรือเป็นจริง (หาก strict เป็นเท็จ ระบบจะข้ามเป้าหมายที่อยู่นอกขอบเขตพร้อมแสดงคำเตือน) วิธีที่ง่ายที่สุดที่จะป้องกันปัญหานี้คือการพูดถึงป้ายกำกับเดียวกันในขอบเขตในนิพจน์การค้นหา

ความแตกต่างเพียงอย่างเดียวระหว่างการค้นหาที่อนุญาตที่นี่และในบรรทัดคำสั่งคือคำค้นหาที่มีข้อกำหนดเฉพาะเป้าหมายไวลด์การ์ด (เช่น //pkg:* หรือ //pkg:all) ไม่ได้รับอนุญาตที่นี่ เหตุผลของการค้นหานี้มี 2 แบบ ดังนี้ เนื่องจาก genquery ต้องระบุขอบเขตเพื่อป้องกันไม่ให้เป้าหมายที่อยู่นอกการปิดแบบทรานซิทีฟของการค้นหามีผลต่อผลลัพธ์ และข้อที่ 2 คือเนื่องจากไฟล์ BUILD ไม่รองรับการอ้างอิงไวลด์การ์ด (เช่น ไม่อนุญาต deps=["//a/..."])

เอาต์พุตของ genquery จะเรียงลำดับแบบพจนานุกรมเพื่อบังคับใช้เอาต์พุตเชิงกำหนด ยกเว้น --output=graph|minrank|maxrank หรือเมื่อมีการใช้ somepath เป็นฟังก์ชันระดับบนสุด

ชื่อของไฟล์เอาต์พุตคือชื่อของกฎ

ตัวอย่าง

ตัวอย่างนี้เขียนรายการป้ายกำกับในการปิดทางอ้อมของเป้าหมายที่ระบุไปยังไฟล์

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
compressed_output	บูลีน ค่าเริ่มต้นคือ False หากเป็น True ระบบจะเขียนเอาต์พุตการค้นหาในรูปแบบไฟล์ GZIP คุณสามารถใช้การตั้งค่านี้เพื่อหลีกเลี่ยงการใช้หน่วยความจำของ Bazel อย่างฉับพลันเมื่อคาดว่าจะมีเอาต์พุตการค้นหาสูง Bazel ได้บีบอัดเอาต์พุตการค้นหาที่มีขนาดใหญ่เกิน 2^20 ไบต์ภายในอยู่แล้วโดยไม่คำนึงถึงค่าของการตั้งค่านี้ ดังนั้นการตั้งค่านี้เป็น True จึงอาจไม่ลดฮีปที่เก็บรักษาไว้ แต่จะช่วยให้ Bazel ข้ามการขยายการบีบอัดขณะเขียนไฟล์เอาต์พุตซึ่งอาจใช้หน่วยความจำมาก
expression	ต้องระบุสตริง การค้นหาที่จะดำเนินการ ป้ายกำกับที่นี่จะได้รับการแก้ไขโดยสัมพันธ์กับไดเรกทอรีรูทของพื้นที่ทำงาน ซึ่งแตกต่างจากบรรทัดคำสั่งและตำแหน่งอื่นๆ ในไฟล์ BUILD เช่น ป้ายกำกับ :b ในแอตทริบิวต์นี้ในไฟล์ a/BUILD จะอ้างถึง //:b เป้าหมาย
opts	รายการสตริง ค่าเริ่มต้นคือ [] ตัวเลือกที่ส่งไปยังเครื่องมือการค้นหา ซึ่งสอดคล้องกับตัวเลือกบรรทัดคำสั่งที่ส่งไปยัง bazel query ได้ ไม่อนุญาตให้ใช้ตัวเลือกการค้นหาบางอย่างที่นี่: --keep_going, --query_file, --universe_scope, --order_results และ --order_output ตัวเลือกที่ไม่ได้ระบุไว้ที่นี่จะมีค่าเริ่มต้นเหมือนกับบรรทัดคำสั่งของ bazel query
scope	รายการป้ายกำกับ ต้องระบุ ขอบเขตของการค้นหา ไม่อนุญาตให้ข้อความค้นหาแตะเป้าหมายที่อยู่นอกการปิดชั่วคราวของเป้าหมายเหล่านี้
strict	บูลีน ค่าเริ่มต้นคือ True หากเป็นจริง เป้าหมายที่การค้นหาเป็นอักขระหลีกการปิดขอบเขตแบบชั่วคราวจะสร้างไม่สำเร็จ หากเป็น "เท็จ" Bazel จะพิมพ์คำเตือนและข้ามเส้นทางการค้นหาที่ทำให้เกิดอยู่นอกขอบเขต และตอบคำถามที่เหลือให้เสร็จสิ้น

Genrule

ดูแหล่งที่มาของกฎ

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule จะสร้างไฟล์อย่างน้อย 1 ไฟล์โดยใช้คำสั่ง Bash ที่ผู้ใช้กำหนด

กฎเกณฑ์เป็นกฎการสร้างโดยทั่วไปที่คุณสามารถใช้ได้หากไม่มีกฎเฉพาะสำหรับงาน ตัวอย่างเช่น คุณเรียกใช้ Bash 1 บรรทัด อย่างไรก็ตาม หากจำเป็นต้องคอมไพล์ไฟล์ C++ ให้ยึดตามกฎ cc_* ที่มีอยู่ เพราะการดำเนินการที่ยุ่งยากทั้งหมดได้ดำเนินไปให้คุณแล้ว

โปรดทราบว่า Genrule ต้องใช้ Shell เพื่อตีความอาร์กิวเมนต์คำสั่ง นอกจากนี้ ยังอ้างอิงโปรแกรมที่กำหนดเองที่พร้อมใช้งานบน PATH ได้ง่ายๆ แต่วิธีนี้ทำให้คำสั่งไม่เป็นแบบผลัดกันทำงานและอาจทำซ้ำไม่ได้ หากต้องการเรียกใช้เพียงเครื่องมือเดียว ให้พิจารณาใช้ run_binary แทน

อย่าใช้ Genrule เพื่อทำการทดสอบ จะมีการชดเชยพิเศษสำหรับการทดสอบและผลการทดสอบ รวมถึงนโยบายการแคชและตัวแปรสภาพแวดล้อม โดยทั่วไปคุณจะต้องดำเนินการทดสอบหลังจากที่บิลด์เสร็จสมบูรณ์และใช้ในสถาปัตยกรรมเป้าหมาย ในขณะที่ Genrules จะดำเนินการระหว่างการสร้างและในสถาปัตยกรรม exec (ทั้ง 2 กฎอาจแตกต่างกัน) หากต้องการกฎการทดสอบวัตถุประสงค์ทั่วไป ให้ใช้ sh_test

ข้อควรพิจารณาเกี่ยวกับการคอมไพล์ข้าม

ดูข้อมูลเพิ่มเติมเกี่ยวกับการคอมไพล์ข้ามได้ในคู่มือผู้ใช้

ขณะที่ Genrules ทำงานระหว่างบิลด์ เอาต์พุตของมักจะใช้หลังจากบิลด์ สำหรับการทำให้ใช้งานได้หรือการทดสอบ ลองดูตัวอย่างการคอมไพล์โค้ด C สำหรับไมโครคอนโทรลเลอร์ คอมไพเลอร์จะยอมรับไฟล์ต้นฉบับ C และสร้างโค้ดที่ทำงานบนไมโครคอนโทรลเลอร์ แน่นอนว่าโค้ดที่สร้างขึ้นไม่สามารถทำงานบน CPU ที่ใช้ในการสร้างโค้ดได้ แต่ตัวคอมไพเลอร์ C (หากคอมไพล์จากแหล่งที่มา) เองจำเป็นต้องใช้

ระบบบิลด์ใช้การกำหนดค่า exec เพื่ออธิบายเครื่องที่บิลด์ทำงานและการกำหนดค่าเป้าหมายเพื่ออธิบายเครื่องที่ควรเรียกใช้เอาต์พุตของบิลด์ โดยมีตัวเลือกในการกำหนดค่ารายการเหล่านี้และแยกไฟล์ที่เกี่ยวข้องออกเป็นไดเรกทอรีแยกต่างหากเพื่อหลีกเลี่ยงข้อขัดแย้ง

สำหรับ Genrules ระบบบิลด์จะตรวจสอบว่าทรัพยากร Dependency สร้างขึ้นอย่างเหมาะสม โดย srcs จะสร้างขึ้น (หากจำเป็น) สำหรับการกำหนดค่าเป้าหมาย, tools สร้างขึ้นสำหรับการกำหนดค่า exec และจะถือว่าเอาต์พุตเป็นของการกำหนดค่าเป้าหมาย และยังมี ตัวแปร "สร้าง" ที่คำสั่ง Genrule สามารถส่งผ่านไปยังเครื่องมือที่เกี่ยวข้องได้

โปรดทราบว่า Genrule ไม่ได้ระบุแอตทริบิวต์ deps โดยกฎอื่นๆ ที่มีไว้ให้อยู่แล้วจะใช้ข้อมูลเมตาที่ขึ้นอยู่กับภาษาที่ส่งผ่านระหว่างกฎเพื่อกำหนดวิธีจัดการกฎที่ไม่เชื่อมโยงโดยอัตโนมัติ แต่ระบบอัตโนมัติระดับนี้ไม่สามารถทำได้สำหรับ Genrules การสร้างกฎจะทำงานที่ระดับไฟล์และ Runfiles เท่านั้น

กรณีพิเศษ

การคอมไพล์ Exec-exec: ในบางกรณี ระบบบิลด์จะต้องเรียกใช้ Genrules เพื่อให้สามารถดำเนินการเอาต์พุตในระหว่างบิลด์ได้ด้วย เช่น หาก Genrule สร้างคอมไพเลอร์ที่กำหนดเองซึ่งมีอีกเพศหนึ่งนำไปใช้ในภายหลัง กฎแรกจะต้องสร้างเอาต์พุตสำหรับการกำหนดค่าปฏิบัติการ เนื่องจากเป็นที่ที่คอมไพเลอร์จะทำงานในอีกรุ่นหนึ่ง ในกรณีนี้ ระบบบิลด์จะทำสิ่งที่ถูกต้องโดยอัตโนมัติ โดยจะสร้าง srcs และ outs ของ GenRule แรกสำหรับการกำหนดค่าปฏิบัติการแทนการกำหนดค่าเป้าหมาย ดูข้อมูลเพิ่มเติมได้ที่คู่มือผู้ใช้

เครื่องมือ JDK และ C++: หากต้องการใช้เครื่องมือจาก JDK หรือชุดคอมไพเลอร์ C++ ระบบบิลด์จะมีชุดตัวแปรที่จะใช้ ดูรายละเอียดได้ที่ตัวแปร"ผู้ผลิต"

สภาพแวดล้อมการสร้างกฎ

คำสั่ง genrule จะทำงานโดย Bash Shell ที่กำหนดค่าล้มเหลวเมื่อคำสั่งหรือไปป์ไลน์ล้มเหลวโดยใช้ set -e -o pipefail

เครื่องมือบิลด์จะเรียกใช้คำสั่ง Bash ในสภาพแวดล้อมกระบวนการที่ปลอดภัยที่กำหนดเฉพาะตัวแปรหลัก เช่น PATH, PWD, TMPDIR และอื่นๆ ระบบจะไม่ส่งตัวแปรส่วนใหญ่ที่กำหนดไว้ในสภาพแวดล้อม Shell ของผู้ใช้ไปยังคำสั่งของ genrule เพื่อให้มั่นใจว่าบิลด์จะทำซ้ำได้ แต่ Bazel (แต่ไม่ใช่ Blaze) จะส่งผ่านค่าตัวแปรสภาพแวดล้อม PATH ของผู้ใช้ การเปลี่ยนแปลงค่าของ PATH จะทำให้ Bazel เรียกใช้คำสั่งอีกครั้งในบิลด์ถัดไป

คำสั่ง genrule ไม่ควรเข้าถึงเครือข่าย ยกเว้นเพื่อเชื่อมต่อกระบวนการที่เป็นรายการย่อยของคำสั่งเอง แม้ว่าจะยังไม่ได้บังคับใช้ก็ตาม

ระบบบิลด์จะลบไฟล์เอาต์พุตที่มีอยู่โดยอัตโนมัติ แต่จะสร้างไดเรกทอรีระดับบนสุดที่จำเป็นก่อนที่จะเรียกใช้ Genrule และยังนำไฟล์เอาต์พุตออกในกรณีที่เกิดข้อผิดพลาดอีกด้วย

คำแนะนำทั่วไป

• โปรดตรวจสอบว่าเครื่องมือที่เรียกใช้โดยกฎเกณฑ์มีหลักการและมีความครบถ้วนสมบูรณ์ เครื่องมือดังกล่าวไม่ควรเขียนการประทับเวลาลงในเอาต์พุต และควรใช้การจัดลำดับที่เสถียรสำหรับชุดและแผนที่ รวมถึงเขียนเฉพาะเส้นทางไฟล์แบบสัมพัทธ์ไปยังเอาต์พุต ไม่ใช่เส้นทางที่แน่นอน การไม่ปฏิบัติตามกฎนี้จะทำให้เกิดลักษณะการทำงานที่ไม่คาดคิด (Bazel ไม่ได้สร้างกฎเกณฑ์ตามที่คุณคิดไว้ใหม่) และทำให้ประสิทธิภาพของแคชลดลง
• ใช้ $(location) อย่างครอบคลุมสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากการแยกไฟล์เอาต์พุตสำหรับการกำหนดค่าที่ต่างกัน ทำให้ Genrules ไม่สามารถพึ่งพาเส้นทางแบบฮาร์ดโค้ดและ/หรือเส้นทางแบบสัมบูรณ์
• ควรเขียนมาโคร Starlark ทั่วไปในกรณีที่มีการใช้กฎ Gen เดียวกันหรือคล้ายกันมากในหลายๆ ที่ หาก Genrule มีความซับซ้อน ให้พิจารณาติดตั้งใช้งานในสคริปต์หรือใช้เป็นกฎ Starlark การทำเช่นนี้จะช่วยปรับปรุงให้อ่านง่ายและช่วยในการทดสอบ
• ตรวจสอบว่ารหัสการออกนั้นบ่งบอกถึงความสำเร็จหรือความล้มเหลวของเจนกฎ
• อย่าเขียนข้อความแจ้งข้อมูลไปยัง stdout หรือ stderr แม้ว่านี่จะเป็นประโยชน์ต่อการแก้ไขข้อบกพร่อง แต่ก็สามารถกลายเป็นสิ่งรบกวนได้โดยง่าย ส่วนการกำหนดเพศที่ประสบความสำเร็จควรปิดเสียงไว้ ในทางกลับกัน การกำหนดเงื่อนไขที่ล้มเหลวควรส่งข้อความแสดงข้อผิดพลาดที่ดี
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• หลีกเลี่ยงการสร้างลิงก์สัญลักษณ์และไดเรกทอรี Bazel จะไม่คัดลอกโครงสร้างไดเรกทอรี/ลิงก์สัญลักษณ์ที่สร้างโดย genrules และการตรวจสอบการอ้างอิงของไดเรกทอรีจะไม่เกิดขึ้น
• เมื่ออ้างอิง Genrule ในกฎอื่นๆ คุณจะใช้ป้ายกำกับของกฎเกณฑ์หรือป้ายกำกับของไฟล์เอาต์พุตแต่ละไฟล์ก็ได้ ในบางครั้งวิธีหนึ่งอาจอ่านได้ง่ายกว่า แต่บางวิธี เช่น การอ้างอิงเอาต์พุตตามชื่อใน srcs ของกฎการใช้จะหลีกเลี่ยงการเลือกเอาต์พุตอื่นๆ ของ GenRule โดยไม่ได้ตั้งใจ แต่อาจเป็นเรื่องน่าเบื่อหาก Genrule สร้างเอาต์พุตจำนวนมาก

ตัวอย่าง

ตัวอย่างนี้สร้าง foo.h ไม่มีแหล่งที่มา เนื่องจากคำสั่งไม่ได้ป้อนข้อมูลใดๆ "ไบนารี" ที่เรียกใช้โดยคำสั่งเป็นสคริปต์ Perl ในแพ็กเกจเดียวกับ Genrule

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

ตัวอย่างต่อไปนี้แสดงวิธีใช้ filegroup และเอาต์พุตของ genrule อีกรายการ โปรดทราบว่าการใช้ $(SRCS) แทนคำสั่ง $(location) อย่างชัดแจ้งก็จริงได้เช่นกัน ตัวอย่างนี้ใช้หลังนี้เพื่อการสาธิต

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้ คุณอาจดูกฎนี้ได้ในส่วน srcs หรือ deps ของกฎ BUILD อื่นๆ หากกฎสร้างไฟล์ต้นฉบับ คุณควรใช้แอตทริบิวต์ srcs
srcs	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการอินพุตสำหรับกฎนี้ เช่น ไฟล์ต้นฉบับที่จะประมวลผล แอตทริบิวต์นี้ไม่เหมาะกับรายชื่อเครื่องมือที่เรียกใช้โดย cmd ให้ใช้แอตทริบิวต์ tools แทน ระบบบิลด์จะตรวจสอบว่าข้อกำหนดเบื้องต้นเหล่านี้สร้างขึ้นก่อนเรียกใช้คำสั่ง Genrule โดยจะมีการสร้างโดยใช้การกำหนดค่าเดียวกันกับคำขอบิลด์เดิม ชื่อไฟล์ของข้อกำหนดเบื้องต้นเหล่านี้จะพร้อมใช้งานสำหรับคำสั่งเป็นรายการที่คั่นด้วยช่องว่างใน $(SRCS) หรือเลือกเส้นทางของแต่ละเป้าหมาย srcs //x:y ได้โดยใช้ $(location //x:y) หรือใช้ $< หากเป็นรายการเดียวใน srcs
outs	รายการชื่อไฟล์ ไม่ได้กำหนดค่าได้ ต้องระบุ รายการไฟล์ที่กฎนี้สร้างขึ้น ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะตีความชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ หากตั้งค่าแฟล็ก executable ไว้ outs ต้องมีป้ายกำกับเพียงรายการเดียว คาดว่าคำสั่ง genrule จะสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า ตำแหน่งจะพร้อมใช้งานใน cmd โดยใช้ตัวแปร "สร้าง" ที่เจาะจงตามแต่ละเวอร์ชัน ($@, $(OUTS), $(@D) หรือ $(RULEDIR)) หรือใช้การแทนที่ $(location)
cmd	สตริง ค่าเริ่มต้นคือ "" คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับการแทนที่ $(location) และตัวแปร"ผู้ผลิต" มีการใช้การแทนที่ $(location) ครั้งแรก โดยแทนที่รายการ $(location label) และ $(locations label) ทั้งหมด (และโครงสร้างที่คล้ายกันโดยใช้ตัวแปร execpath, execpaths, rootpath และ rootpaths ที่เกี่ยวข้อง) จากนั้น ตัวแปร"ผู้ผลิต" จะขยายออก โปรดทราบว่าตัวแปร $(JAVA), $(JAVAC) และ $(JAVABASE) ที่กำหนดไว้ล่วงหน้าจะขยายภายใต้การกำหนดค่า exec ดังนั้นการเรียกใช้ Java ที่ทำงานเป็นส่วนหนึ่งของขั้นตอนของบิลด์จะโหลดไลบรารีที่ใช้ร่วมกันและการอ้างอิงอื่นๆ ได้อย่างถูกต้อง ขั้นสุดท้าย คำสั่งที่ได้จะถูกดำเนินการโดยใช้ Bash Shell หากโค้ดการออกไม่ใช่ 0 จะถือว่าคำสั่งล้มเหลว นี่คือโฆษณาสำรองของ cmd_bash, cmd_ps และ cmd_bat หากไม่เกี่ยวข้อง หากบรรทัดคำสั่งยาวเกินขีดจำกัดของแพลตฟอร์ม (64, 000 บน Linux/macOS, 8K ใน Windows) Genrule จะเขียนคำสั่งลงในสคริปต์และเรียกใช้สคริปต์นั้นเพื่อแก้ปัญหา ค่านี้มีผลกับแอตทริบิวต์ cmd ทั้งหมด (cmd, cmd_bash, cmd_ps, cmd_bat)
cmd_bash	สตริง ค่าเริ่มต้นคือ "" คำสั่ง Bash ที่จะเรียกใช้ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า cmd ระบบจะขยายคำสั่งและทำงานในลักษณะเดียวกับแอตทริบิวต์ cmd
cmd_bat	สตริง ค่าเริ่มต้นคือ "" คำสั่งแบบกลุ่มที่จะเรียกใช้ใน Windows แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า cmd และ cmd_bash คำสั่งจะทำงานในลักษณะเดียวกันกับแอตทริบิวต์ cmd โดยมีความแตกต่างดังต่อไปนี้ แอตทริบิวต์นี้มีผลเฉพาะกับ Windows เท่านั้น คำสั่งจะทำงานร่วมกับ cmd.exe /c ที่มีอาร์กิวเมนต์เริ่มต้นดังต่อไปนี้ /S - ตัดเครื่องหมายอัญประกาศแรกและสุดท้ายออก แล้วเรียกใช้ทุกอย่างตามที่เป็นอยู่ /E:ON - เปิดใช้ชุดคำสั่งแบบขยาย /V:ON - เปิดใช้การขยายตัวแปรแบบหน่วงเวลา /D - ไม่ต้องสนใจรายการรีจิสทรีของ AutoRun หลังจากการแทนที่ $(location) และตัวแปร"Make" ระบบจะขยายเส้นทางเป็นเส้นทางสไตล์ Windows (โดยมีแบ็กสแลช)
cmd_ps	สตริง ค่าเริ่มต้นคือ "" คำสั่ง Powershell ที่จะเรียกใช้ใน Windows แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า cmd, cmd_bash และ cmd_bat คำสั่งจะทำงานในลักษณะเดียวกับแอตทริบิวต์ cmd โดยมีความแตกต่างดังต่อไปนี้ แอตทริบิวต์นี้มีผลเฉพาะกับ Windows เท่านั้น คําสั่งจะทํางานด้วย powershell.exe /c เราเรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่าสภาพแวดล้อมก่อนเรียกใช้คำสั่ง Powershell ใน Genrule เพื่อให้ใช้งาน Powershell ได้ง่ายขึ้นและเกิดข้อผิดพลาดน้อยลง Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - อนุญาตให้เรียกใช้สคริปต์ที่ไม่มีการลงชื่อ $errorActionPreference='Stop' - ในกรณีที่มีคำสั่งหลายรายการที่คั่นด้วย ; การดำเนินการจะสิ้นสุดลงทันทีหาก Powershell CmdLet ล้มเหลว แต่จะทำงานไม่ใช้กับคำสั่งภายนอกได้ $PSDefaultParameterValues['*:Encoding'] = 'utf8' - เปลี่ยนการเข้ารหัสเริ่มต้นจาก utf-16 เป็น utf-8
executable	บูลีน nonconfigurable ค่าเริ่มต้นคือ False ประกาศเอาต์พุตให้เป็นไฟล์ปฏิบัติการ การตั้งค่าแฟล็กนี้เป็น "จริง" หมายความว่าเอาต์พุตจะเป็นไฟล์ปฏิบัติการและเรียกใช้ได้โดยใช้คำสั่ง run ในกรณีนี้ กฎ Genrule ต้องสร้างเอาต์พุตเพียง 1 รายการเท่านั้น หากตั้งค่าแอตทริบิวต์นี้ run จะพยายามเรียกใช้ไฟล์โดยไม่คำนึงถึงเนื้อหา ไม่รองรับการประกาศทรัพยากร Dependency สำหรับไฟล์สั่งการที่สร้างขึ้น
local	บูลีน ค่าเริ่มต้นคือ False หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะบังคับให้ genrule นี้ทำงานโดยใช้กลยุทธ์ "ในเครื่อง" ซึ่งหมายความว่าไม่มีการดำเนินการระยะไกล ไม่มีการแซนด์บ็อกซ์ หรือผู้ปฏิบัติงานถาวร ซึ่งเทียบเท่ากับการระบุ 'local' เป็นแท็ก (tags=["local"])
message	สตริง ค่าเริ่มต้นคือ "" ข้อความแสดงความคืบหน้า ข้อความความคืบหน้าที่จะพิมพ์เมื่อดำเนินการในขั้นตอนบิลด์นี้ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้างเอาต์พุต" (หรืออะไรที่ก็น่าเบื่อพอๆ กัน) แต่คุณอาจระบุที่เจาะจงมากขึ้นก็ได้ ใช้แอตทริบิวต์นี้แทน echo หรือคำสั่งการพิมพ์อื่นๆ ในคำสั่ง cmd เพราะจะช่วยให้เครื่องมือสร้างสคริปต์ควบคุมว่าจะพิมพ์ข้อความความคืบหน้าดังกล่าวหรือไม่
output_licenses	ประเภทใบอนุญาต ค่าเริ่มต้นคือ ["none"] โปรดดู common attributes
output_to_bindir	บูลีน nonconfigurable ค่าเริ่มต้นคือ False หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทำให้มีการเขียนไฟล์เอาต์พุตในไดเรกทอรี bin แทนไดเรกทอรี genfiles
tools	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการทรัพยากร Dependency ของเครื่องมือสำหรับกฎนี้ ดูคำจำกัดความของการขึ้นต่อกันสำหรับข้อมูลเพิ่มเติม ระบบบิลด์ช่วยให้มั่นใจได้ว่าข้อกำหนดเบื้องต้นเหล่านี้สร้างขึ้นก่อนที่จะเรียกใช้คำสั่ง genrule ระบบสร้างโดยใช้การกำหนดค่า exec เนื่องจากมีการดำเนินการเครื่องมือเหล่านี้เป็นส่วนหนึ่งของบิลด์ เส้นทางของแต่ละเป้าหมาย tools //x:y จะรับได้โดยใช้ $(location //x:y) *_binary หรือเครื่องมือที่ cmd จะเรียกใช้ต้องปรากฏในรายการนี้ ไม่ใช่ใน srcs เพื่อให้มั่นใจว่าสร้างขึ้นด้วยการกำหนดค่าที่ถูกต้อง

starlark_doc_extract

ดูแหล่งที่มาของกฎ

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() จะแตกข้อมูลเอกสารเกี่ยวกับกฎ ฟังก์ชัน (รวมถึงมาโคร) แง่มุมต่างๆ และผู้ให้บริการที่กำหนดหรือส่งออกอีกครั้งในไฟล์ .bzl หรือ .scl ที่ระบุ เอาต์พุตของกฎนี้คือไบนารี Proto ของ ModuleInfo ตามที่กำหนดไว้ใน stardoc_output.proto ในผังซอร์ส Bazel

เป้าหมายเอาต์พุตโดยนัย

• name.binaryproto (เอาต์พุตเริ่มต้น): Proto ไบนารี ModuleInfo
• name.textproto (สร้างเมื่อขออย่างชัดแจ้งเท่านั้น): ข้อความเวอร์ชัน Proto ของ name.binaryproto

คำเตือน: เราไม่รับประกันว่ารูปแบบเอาต์พุตของกฎนี้จะเสถียร โดยมีจุดประสงค์หลักเพื่อการใช้งานภายในโดย Stardoc

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
deps	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการเป้าหมายที่รวมไฟล์ Starlark ที่ load()-โดย src เป้าหมายเหล่านี้ควรอยู่ภายใต้การใช้งานปกติเป็นเป้าหมาย bzl_library แต่กฎ starlark_doc_extract ไม่ได้บังคับใช้เป้าหมายนั้น และจะยอมรับเป้าหมายทั้งหมดที่มีไฟล์ Starlark อยู่ใน DefaultInfo โปรดทราบว่าไฟล์ Starlark ที่รวมไว้ต้องเป็นไฟล์ในโครงสร้างแหล่งที่มา เนื่องจาก Bazel ไม่สามารถload()สร้างไฟล์ได้
src	ป้ายกำกับ ต้องระบุ ไฟล์ Starlark สำหรับแยกเอกสาร โปรดทราบว่าไฟล์นี้ต้องเป็นไฟล์ในโครงสร้างแหล่งที่มา เนื่องจาก Bazel สร้างload()ไฟล์ไม่ได้
render_main_repo_name	บูลีน ค่าเริ่มต้นคือ False หากเป็น "จริง" แสดงผลป้ายกำกับในที่เก็บหลักในเอกสารที่เผยแพร่ด้วยคอมโพเนนต์ที่เก็บ (กล่าวคือ //foo:bar.bzl จะส่งออกเป็น @main_repo_name//foo:bar.bzl) ชื่อที่ใช้สำหรับที่เก็บหลักมาจาก module(name = ...) ในไฟล์ MODULE.bazel ของที่เก็บหลัก (หากเปิดใช้ Bzlmod) หรือจาก workspace(name = ...) ในไฟล์ WORKSPACE ของที่เก็บหลัก ควรตั้งค่าแอตทริบิวต์นี้เป็น False เมื่อสร้างเอกสารประกอบสำหรับไฟล์ Starlark ที่มีจุดประสงค์เพื่อใช้ภายในที่เก็บเดียวกันเท่านั้น และให้กับ True เมื่อสร้างเอกสารประกอบสำหรับไฟล์ Starlark ซึ่งมีจุดประสงค์เพื่อใช้จากที่เก็บอื่น
symbol_names	รายการสตริง ค่าเริ่มต้นคือ [] รายการชื่อที่เข้าเกณฑ์ของฟังก์ชัน กฎ ผู้ให้บริการ หรือด้านที่ส่งออก (หรือโครงสร้างที่ฝังอยู่) ที่จะดึงข้อมูลเอกสาร (ไม่บังคับ) ในที่นี้ ชื่อที่มีคุณสมบัติหมายถึงชื่อที่เอนทิตีพร้อมใช้งานสำหรับผู้ใช้ของโมดูลนี้ รวมถึงโครงสร้างใดๆ ที่เอนทิตีฝังอยู่เพื่อใช้การกำหนดทิศทาง starlark_doc_extract จะออกเอกสารสําหรับเอนทิตีในกรณีต่อไปนี้เท่านั้น องค์ประกอบแต่ละรายการของชื่อที่เข้าเกณฑ์ของเอนทิตีเป็นแบบสาธารณะ (กล่าวคือ อักขระตัวแรกของชื่อที่ผ่านการรับรองแต่ละรายการจะเป็นตัวอักษร ไม่ใช่ "_") และ รายการ symbol_names ว่างเปล่า (ซึ่งเป็นกรณีเริ่มต้น) หรือ ชื่อที่เข้าเกณฑ์ของเอนทิตี หรือชื่อที่มีคุณสมบัติตามเกณฑ์ของโครงสร้างที่มีเอนทิตีฝังอยู่ในรายการ symbol_names

test_suite

ดูแหล่งที่มาของกฎ

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite กำหนดชุดการทดสอบที่ถือว่า "มีประโยชน์" ต่อมนุษย์ วิธีนี้ทำให้โปรเจ็กต์สามารถกำหนดชุดการทดสอบได้ เช่น "การทดสอบที่คุณต้องทำก่อนเช็คอิน" "การทดสอบภาวะวิกฤตของโปรเจ็กต์" หรือ "การทดสอบย่อยทั้งหมด" คำสั่ง blaze test จะดำเนินการตามโครงสร้างแบบนี้ สำหรับการเรียกใช้อย่าง blaze test //some/test:suite ก่อน Blaze จะแจกแจงเป้าหมายการทดสอบทั้งหมดที่รวมไว้แล้วโดยเป้าหมาย //some/test:suite (เราเรียกว่า "การขยายtest_suite") ก่อน จากนั้น Blaze จะสร้างและทดสอบเป้าหมายเหล่านั้น

ตัวอย่าง

ชุดทดสอบสำหรับทำการทดสอบขนาดเล็กทั้งหมดในแพ็กเกจปัจจุบัน

test_suite(
    name = "small_tests",
    tags = ["small"],
)

ชุดทดสอบที่เรียกใช้ชุดการทดสอบที่ระบุ

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

ชุดทดสอบที่จะทำการทดสอบทั้งหมดในแพ็กเกจปัจจุบันซึ่งทำงานไม่สม่ำเสมอ

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

อาร์กิวเมนต์

Attributes
name	Name (ชื่อ) ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
tags	รายการสตริง ไม่สามารถกำหนดค่าได้ ค่าเริ่มต้นคือ [] รายการแท็กข้อความ เช่น "ขนาดเล็ก" หรือ "ฐานข้อมูล" หรือ "-ขจัด" แท็กอาจเป็นสตริงใดๆ ที่ถูกต้อง แท็กที่ขึ้นต้นด้วยอักขระ "-" จะถือว่าเป็นแท็กเชิงลบ อักขระ "-" นำหน้าไม่ถือว่าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็กชุดโปรแกรม "-small" จะตรงกับขนาด "เล็ก" ของการทดสอบ แท็กอื่นๆ ทั้งหมดจะถือว่าเป็นแท็กเชิงบวก (ไม่บังคับ) หากต้องการให้แท็กเชิงบวกมีความชัดเจนมากขึ้น แท็กอาจขึ้นต้นด้วยอักขระ "+" ซึ่งจะไม่ได้รับการประเมินในฐานะเป็นส่วนหนึ่งของข้อความของแท็ก แต่เป็นเพียงการทําให้ความแตกต่างด้านบวกและด้านลบอ่านได้ง่ายขึ้นเท่านั้น ชุดทดสอบนี้จะรวมเฉพาะกฎทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและไม่มีแท็กเชิงลบเท่านั้นที่จะรวมอยู่ในชุดทดสอบ โปรดทราบว่าการดำเนินการนี้ไม่ได้หมายความว่าระบบจะข้ามการตรวจสอบข้อผิดพลาดสำหรับทรัพยากร Dependency ของการทดสอบที่กรองออก แต่การอ้างอิงในการทดสอบที่ข้ามจะยังคงต้องเป็นไปตามกฎหมาย (เช่น ไม่ถูกบล็อกโดยข้อจำกัดระดับการเข้าถึง) คีย์เวิร์ดของแท็ก manual จะได้รับการจัดการต่างจากคีย์เวิร์ดด้านบนโดย "test_suite" ที่ทําโดยคําสั่ง blaze test ในการเรียกใช้ที่เกี่ยวข้องกับรูปแบบเป้าหมายโดยใช้ไวลด์การ์ด ในส่วนนี้ เป้าหมาย test_suite รายการที่ติดแท็ก "ด้วยตนเอง" จะถูกกรองออก (จึงไม่ขยาย) ลักษณะการทำงานนี้สอดคล้องกับวิธีที่ blaze build และ blaze test จัดการรูปแบบเป้าหมายไวลด์การ์ดโดยทั่วไป โปรดทราบว่าสิ่งนี้แตกต่างอย่างชัดเจนจากลักษณะการทำงานของ blaze query 'tests(E)' เนื่องจากฟังก์ชันการค้นหาของ tests จะขยายชุดโปรแกรมเสมอ โดยไม่คำนึงถึงแท็ก manual โปรดทราบว่า size ของการทดสอบถือเป็นแท็กที่ใช้กรอง หากต้องการ test_suite ที่มีการทดสอบซึ่งมีแท็กที่ใช้พร้อมกันไม่ได้ (เช่น การทดสอบขนาดเล็กและขนาดกลางทั้งหมด) คุณจะต้องสร้างกฎ test_suite 3 ข้อ กฎหนึ่งสำหรับการทดสอบขนาดเล็กทั้งหมด กฎหนึ่งสำหรับการทดสอบขนาดกลางทั้งหมด และกฎอีก 1 ข้อที่รวม 2 กฎก่อนหน้า
tests	รายการป้ายกำกับ ไม่สามารถกำหนดค่าได้ ค่าเริ่มต้นคือ [] รายการชุดทดสอบและเป้าหมายการทดสอบของภาษาใดก็ได้ ใช้ *_test ได้ที่นี่ โดยไม่ขึ้นอยู่กับภาษา อย่างไรก็ตาม ไม่ยอมรับเป้าหมาย *_binary แม้ว่าจะทำการทดสอบก็ตาม การกรองตาม tags ที่ระบุจะทําสำหรับการทดสอบที่แสดงในแอตทริบิวต์นี้โดยตรงเท่านั้น หากแอตทริบิวต์นี้มี test_suite การทดสอบภายในการทดสอบจะไม่กรองโดย test_suite นี้ (ถือว่าได้กรองแล้ว) หากไม่ระบุแอตทริบิวต์ tests หรือว่างเปล่า กฎจะเป็นค่าเริ่มต้นให้รวมกฎการทดสอบทั้งหมดในไฟล์ BUILD ปัจจุบันที่ไม่ได้ติดแท็กเป็น manual กฎเหล่านี้ยังอยู่ภายใต้การกรองของ tag