การลงทะเบียน BazelCon 2024 เปิดให้ลงทะเบียนแล้วในตอนนี้

หน้านี้ได้รับการแปลโดย Cloud Translation API

กฎทั่วไป

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

กฎ

อีเมลแทน
config_setting
กลุ่มไฟล์
Genquery
Genrule
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 ในนามแฝงจะถูกละเว้น และ testonly-ness ของกฎที่อ้างอิงแทน) โดยมีข้อยกเว้นบางประการดังนี้

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

ตัวอย่าง

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

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

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

Attributes

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 ไม่ตรงกับแฟล็กบรรทัดคำสั่งระดับบนสุด แต่อาจยังตรงกันอยู่ เป้าหมายของบิลด์

หมายเหตุ

โปรดดูการเลือกสำหรับสิ่งที่จะเกิดขึ้นเมื่อหลายรายการ config_setting ตรงกับสถานะการกำหนดค่าปัจจุบัน
สําหรับ Flag ที่รองรับรูปแบบชวเลข (เช่น --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 ให้ผลลัพธ์ ["a", "b"] ตรวจสอบคำจำกัดความของ Flag และทดสอบ เงื่อนไขโดยละเอียดเพื่อยืนยันความคาดหวังที่ถูกต้อง
หากต้องการกำหนดเงื่อนไขที่ไม่ได้สร้างโมเดลด้วยแฟล็กบิลด์ในตัว ให้ใช้ แฟล็กที่กำหนดโดย Starlark คุณใช้ --define ได้ด้วย แต่ตัวเลือกนี้จะรัดกุมกว่า แต่ไม่แนะนำให้ใช้ โปรดดู ที่นี่เพื่อดูการสนทนาเพิ่มเติม
หลีกเลี่ยงการใช้คำจำกัดความ config_setting ที่เหมือนกันในแพ็กเกจอื่นซ้ำ แต่ให้อ้างอิง config_setting ทั่วไปที่กำหนดไว้ในแพ็กเกจ Canonical แทน
values define_values และ constraint_values สามารถใช้ชุดค่าผสมใดก็ได้ใน config_setting เดียวกัน แต่ต้องมีอย่างน้อย กำหนดสำหรับ config_setting ใดๆ ก็ได้

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

Attributes
`name`	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`constraint_values`	รายการป้ายกำกับ nonconfigurable; ค่าเริ่มต้นคือ `[]` ชุดต่ำสุดของ `constraint_values` ที่แพลตฟอร์มเป้าหมายต้องระบุ เพื่อจับคู่`config_setting`นี้ (แพลตฟอร์มการดำเนินการ ที่เกี่ยวข้องกันที่นี่) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมที่แพลตฟอร์มถูกละเว้น โปรดดู รายละเอียดแอตทริบิวต์บิลด์ที่กำหนดค่าได้ ในกรณีที่ `config_setting` ทั้ง 2 รายการตรงกัน `select` แอตทริบิวต์นี้ไม่ได้รับการพิจารณาเพื่อวัตถุประสงค์ในการพิจารณา หนึ่งใน `config_setting` เป็นความเชี่ยวชาญพิเศษของอีกด้านหรือไม่ ในอีก คำหนึ่งๆ `config_setting` ไม่อาจจับคู่กับแพลตฟอร์มหนึ่งๆ ได้ดีกว่าแพลตฟอร์มอื่น
`define_values`	พจนานุกรม: สตริง -> String; 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 ปกติ และสามารถผสมกับแอตทริบิวต์นี้ได้อย่างอิสระ ตราบใดที่คีย์พจนานุกรมยังคงแตกต่างกัน
`flag_values`	พจนานุกรม: label -> String; nonconfigurable; ค่าเริ่มต้นคือ `{}` เหมือนกันกับ `values` แต่ สำหรับ แฟล็กบิลด์ที่ผู้ใช้กำหนด ซึ่งเป็นแอตทริบิวต์ที่เด่นชัดเนื่องจาก Flag ที่ผู้ใช้กำหนดจะอ้างอิงว่าเป็นป้ายกำกับในขณะที่ แฟล็กในตัวจะอ้างอิงเป็นสตริงที่กำหนดเอง
`values`	พจนานุกรม: สตริง -> String; nonconfigurable; ค่าเริ่มต้นคือ `{}` ชุดของการกำหนดค่าที่ตรงกับกฎนี้ (แสดงเป็นแฟล็กบิลด์) กฎนี้รับการกำหนดค่าของเป้าหมายที่กำหนดค่าไว้ซึ่ง อ้างถึงในคำสั่ง `select` ถือว่าได้ "จับคู่" คำขอ Bazel หากทุกๆ คำในพจนานุกรม การกำหนดค่าตรงกับค่าที่คาดไว้ของรายการ ตัวอย่างเช่น `values = {"compilation_mode": "opt"}` ตรงกับคำขอ `bazel build --compilation_mode=opt ...` และ `bazel build -c opt ...` ในกฎที่กำหนดค่าเป้าหมาย เพื่อความสะดวก ค่าของการกำหนดค่าจึงมีการระบุเป็นแฟล็กบิลด์ (ไม่มี `"--"` ก่อนหน้า) แต่อย่าลืมว่าทั้ง 2 สิ่งนี้ไม่เหมือนกัน ช่วงเวลานี้ คือเพราะเป้าหมายสามารถสร้างจากการกำหนดค่าได้หลายรายการภายในรายการเดียวกัน งานสร้าง เช่น "CPU" ของการกำหนดค่าการดำเนินการ ตรงกับค่าของ `--host_cpu` ไม่ใช่ `--cpu` ดังนั้น อินสแตนซ์ที่แตกต่างกัน `config_setting` เดียวกันอาจตรงกับการเรียกใช้เดียวกันแตกต่างกัน โดยขึ้นอยู่กับการกำหนดค่าของกฎที่ใช้กฎนั้นๆ หากไม่ได้ตั้งค่า Flag อย่างชัดเจนที่บรรทัดคำสั่ง ระบบจะใช้ค่าเริ่มต้น หากคีย์ปรากฏในพจนานุกรมหลายครั้ง ระบบจะใช้เฉพาะอินสแตนซ์ล่าสุดเท่านั้น หากคีย์อ้างอิงถึงแฟล็กที่ตั้งค่าได้หลายครั้งในบรรทัดคำสั่ง (เช่น `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`	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`srcs`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการเป้าหมายที่เป็นสมาชิกของกลุ่มไฟล์ เป็นเรื่องปกติที่จะใช้ผลลัพธ์ของนิพจน์ glob สำหรับ ค่าของแอตทริบิวต์ `srcs`
`data`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการไฟล์ที่กฎนี้ต้องการในระหว่างรันไทม์ ระบบจะเพิ่มเป้าหมายที่มีชื่อในแอตทริบิวต์ `data` ไปยัง `runfiles` ของกฎ `filegroup` นี้ เมื่อ มีการอ้างอิง `filegroup` ในแอตทริบิวต์ `data` ของ กฎอีกข้อคือ`runfiles` ระบบจะเพิ่มกฎนั้นลงใน`runfiles` ของกฎที่ขึ้นอยู่กับกฎ ดูทรัพยากร Dependency ของข้อมูล และเอกสารทั่วไปของ `data` สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีอ้างอิงและใช้ไฟล์ข้อมูล
`output_group`	String; ค่าเริ่มต้นคือ `""` กลุ่มเอาต์พุตที่จะรวบรวมอาร์ติแฟกต์จากแหล่งที่มา หากแอตทริบิวต์นี้คือ ที่ระบุไว้ ระบบจะส่งออกอาร์ติแฟกต์จากกลุ่มเอาต์พุตที่ระบุของทรัพยากร 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 ไม่รองรับทรัพยากร Dependency ที่เป็นไวลด์การ์ด (เช่น deps=["//a/..."]) )

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

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

ตัวอย่าง

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

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

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

Attributes
`name`	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`compressed_output`	บูลีน ค่าเริ่มต้นคือ `False` หากเป็น `True` เอาต์พุตคำค้นหาจะเขียนในรูปแบบไฟล์ GZIP ใช้การตั้งค่านี้ได้ เพื่อเลี่ยงการใช้หน่วยความจำของ Bazel ที่เพิ่มขึ้นอย่างรวดเร็วเมื่อคาดว่าเอาต์พุตของคำค้นหาจะมีขนาดใหญ่ บาเซล บีบอัดเอาต์พุตของการค้นหาที่มีขนาดใหญ่กว่า 2²⁰ ไบต์เป็นการภายในอยู่แล้วโดยไม่คำนึงถึง ค่าของการตั้งค่านี้ ดังนั้นการตั้งค่าเป็น `True` อาจไม่ลดการคงไว้ ฮีป แต่จะทำให้ Bazel ข้ามการคลายการบีบอัดเมื่อเขียนไฟล์เอาต์พุตได้ ซึ่งอาจทำให้ต้องใช้หน่วยความจำมาก
`expression`	String; ต้องระบุ การค้นหาที่จะดำเนินการ ซึ่งตรงข้ามกับบรรทัดคำสั่งและที่อื่นๆ ในไฟล์ 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 หนึ่งบรรทัด แต่หากต้องการคอมไพล์ไฟล์ C++ ให้ใช้ ตามกฎcc_*ที่มีอยู่ เนื่องจากได้เพิ่มภาระงานหนักๆ ทั้งหมดแล้ว สำหรับคุณ

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

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

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

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

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

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

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

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

คดีพิเศษ

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

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

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

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

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

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

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

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

ตรวจสอบให้แน่ใจว่าเครื่องมือที่เรียกใช้โดยกฎพันธุกรรมมีความละเอียดอ่อนและมีความต่อเนื่อง ผู้ใช้ไม่ควรเขียน การประทับเวลาไปยังเอาต์พุต และควรใช้การจัดลำดับที่เสถียรสำหรับชุดและแผนที่ รวมถึง เขียนเฉพาะเส้นทางไฟล์สัมพัทธ์ไปยังเอาต์พุต ไม่ใช่เส้นทางสัมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะ ทำให้เกิดลักษณะการสร้างที่ไม่คาดคิด (Bazel ไม่ได้สร้าง Genrule ใหม่อย่างที่คุณคิด) และ ทำให้ประสิทธิภาพของแคชลดลง
ใช้ $(location) อย่างครอบคลุมสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจาก การแยกไฟล์เอาต์พุตสำหรับการกำหนดค่าที่แตกต่างกัน Genrule จะอาศัยฮาร์ดโค้ดไม่ได้ และ/หรือเส้นทางสัมบูรณ์
เขียนมาโคร Starlark ทั่วไปเผื่อในกรณีที่มีการใช้กฎเกณฑ์เดียวกันหรือคล้ายกันมากใน หลายสถานที่ หาก 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 ไม่คัดลอกไปยังไดเรกทอรี/ลิงก์สัญลักษณ์ สร้างโดย Genrule และการตรวจสอบทรัพยากร Dependency ของไดเรกทอรีจะไม่ส่งเสียง
เมื่ออ้างอิง Genrule ในกฎอื่นๆ คุณสามารถใช้ป้ายกำกับของ 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`	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้ คุณอาจอ้างอิงกฎนี้ใน `srcs` หรือ `deps` ของ `BUILD` อื่นๆ กฎ หากกฎสร้างไฟล์ต้นฉบับ คุณควรใช้เมธอด `srcs`
`srcs`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการอินพุตสำหรับกฎนี้ เช่น ไฟล์ต้นฉบับที่จะประมวลผล แอตทริบิวต์นี้ไม่เหมาะสำหรับแสดงรายการเครื่องมือที่ดำเนินการโดย `cmd` ใช้ แอตทริบิวต์ `tools` ของผู้ใช้เหล่านั้นแทน ระบบบิลด์จะดูแลให้มีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้กฎ Gen คำสั่ง; ที่สร้างขึ้นโดยใช้การกำหนดค่าเดียวกับคำขอบิลด์เดิม ชื่อไฟล์ของข้อกำหนดเบื้องต้นเหล่านี้จะมีให้กับคำสั่ง รายการที่คั่นด้วยช่องว่างใน `$(SRCS)` อีกทางเลือกหนึ่งคือเส้นทางของบุคคล รับ `srcs` เป้าหมาย `//x:y` ได้โดยใช้ `$(location //x:y)` หรือใช้ `$<` หากนี่เป็นข้อมูลเดียวใน `srcs`
`outs`	รายการชื่อไฟล์ nonconfigurable; ต้องระบุ รายการไฟล์ที่กฎนี้สร้าง ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะแปลชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ หากตั้งค่าแฟล็ก `executable` ไว้ `outs` ต้องมีเพียง 1 รายการ ป้ายกำกับ คำสั่ง Genrule ต้องการสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า ตำแหน่งแสดงใน `cmd` โดยใช้ "Make" ที่เจาะจงตามกฎ ตัวแปร (`$@`, `$(OUTS)`, `$(@D)` หรือ `$(RULEDIR)`) หรือใช้ การแทน `$(location)`
`cmd`	String; ค่าเริ่มต้นคือ `""` คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับ `$(location)` และ "ผู้ผลิต" ตัวแปร มีการใช้การแทนที่ `$(location)` รายการแรกแล้ว โดยแทนที่รายการ `$(location label)` และ `$(locations label)` ทั้งหมด (และรายการอื่นๆ ที่คล้ายกัน การสร้างโดยใช้ตัวแปรที่เกี่ยวข้อง `execpath`, `execpaths` `rootpath` และ `rootpaths`) จากนั้น "สร้าง" ตัวแปรจะขยายออก โปรดทราบว่า ตัวแปรที่กำหนดล่วงหน้า `$(JAVA)`, `$(JAVAC)` และ `$(JAVABASE)` จะขยายออกภายใต้การกำหนดค่า exec ดังนั้นการเรียกใช้ Java ที่ทำงานเป็นส่วนหนึ่งของขั้นตอนบิลด์จะโหลดไลบรารีที่ใช้ร่วมกันและ ทรัพยากร Dependency สุดท้าย ระบบจะดำเนินการคำสั่งโดยใช้ Bash Shell หากรหัสทางออกคือ ไม่เป็นศูนย์จะถือว่าคำสั่งล้มเหลว นี่คือตัวเลือกสำรองของ `cmd_bash`, `cmd_ps` และ `cmd_bat` หากไม่มีข้อใดเลย หากบรรทัดคำสั่งยาวเกินขีดจำกัดของแพลตฟอร์ม (64K ใน Linux/macOS, 8K ใน Windows) จากนั้น Genrule จะเขียนคำสั่งลงในสคริปต์และเรียกใช้สคริปต์นั้นเพื่อแก้ปัญหา ช่วงเวลานี้ ใช้กับแอตทริบิวต์ cmd ทั้งหมด (`cmd`, `cmd_bash`, `cmd_ps`, `cmd_bat`)
`cmd_bash`	String; ค่าเริ่มต้นคือ `""` คำสั่ง Bash ที่จะเรียกใช้ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า `cmd` คำสั่งจะขยายและ จะทำงานในลักษณะเดียวกันกับแอตทริบิวต์ `cmd`
`cmd_bat`	String; ค่าเริ่มต้นคือ `""` คำสั่งแบบกลุ่มที่จะเรียกใช้ใน Windows แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า `cmd` และ `cmd_bash` คำสั่งจะทำงานในลักษณะเดียวกันกับแอตทริบิวต์ `cmd` โดยมีเมธอด ความแตกต่างดังต่อไปนี้ แอตทริบิวต์นี้ใช้ได้กับ Windows เท่านั้น คำสั่งจะทำงานด้วย `cmd.exe /c` พร้อมอาร์กิวเมนต์เริ่มต้นต่อไปนี้ `/S` - ตัดข้อความที่ยกมาและคำสุดท้ายออกและดำเนินการอย่างอื่นตามเดิม `/E:ON` - เปิดใช้ชุดคำสั่งเพิ่มเติม `/V:ON` - เปิดใช้การขยายตัวแปรที่ล่าช้า `/D` - ละเว้นรายการรีจิสทรี AutoRun หลัง $(location) และ "ผู้ผลิต" แทน เส้นทางจะ ขยายไปยังเส้นทางรูปแบบ Windows (พร้อมด้วยแบ็กสแลช)
`cmd_ps`	String; ค่าเริ่มต้นคือ `""` คำสั่ง Powershell สำหรับเรียกใช้ใน Windows แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า `cmd`, `cmd_bash` และ `cmd_bat` คำสั่งจะทำงานในลักษณะเดียวกับ `cmd` ซึ่งมีความแตกต่างดังต่อไปนี้ แอตทริบิวต์นี้ใช้ได้กับ Windows เท่านั้น คำสั่งทำงานด้วย `powershell.exe /c` เพื่อให้ Powershell ใช้งานง่ายและมีโอกาสเกิดข้อผิดพลาดน้อยลง เราจึงเรียกใช้สิ่งต่อไปนี้ คำสั่งเพื่อตั้งค่าสภาพแวดล้อมก่อนเรียกใช้คำสั่ง Powershell ใน genrule `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`	String; ค่าเริ่มต้นคือ `""` ข้อความความคืบหน้า ข้อความความคืบหน้าที่จะพิมพ์เมื่อมีการดำเนินการขั้นตอนบิลด์นี้ โดยค่าเริ่มต้น แอตทริบิวต์ ข้อความคือ "กำลังสร้างเอาต์พุต" (หรืออะไรบางอย่างที่ไม่ซับซ้อน) แต่คุณอาจให้ ที่เจาะจงมากขึ้น ใช้แอตทริบิวต์นี้แทน `echo` หรือรูปอัดอื่นๆ ในคำสั่ง `cmd` เพราะจะทำให้เครื่องมือสร้างสามารถควบคุม มีการพิมพ์ข้อความความคืบหน้าดังกล่าวหรือไม่
`output_licenses`	ประเภทใบอนุญาต ค่าเริ่มต้นคือ `["none"]` โปรดดู `common attributes`
`output_to_bindir`	บูลีน nonconfigurable; ค่าเริ่มต้นคือ `False` หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทำให้มีการเขียนไฟล์เอาต์พุตลงใน `bin` แทนที่จะเป็นไดเรกทอรี `genfiles`
`tools`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการทรัพยากร Dependency ของเครื่องมือสำหรับกฎนี้ ดูคำจำกัดความของ dependencies เพื่อดูข้อมูลเพิ่มเติม ระบบบิลด์จะดูแลให้มีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้คำสั่ง 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 ไฟล์ เอาต์พุตของกฎนี้คือ ModuleInfo Proto แบบไบนารีตามที่กำหนดไว้ ใน stardoc_output.proto ในแผนผังแหล่งที่มาของ Bazel

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

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

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

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

Attributes
`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`	รายการสตริง ค่าเริ่มต้นคือ `[]` รายการที่ไม่บังคับของชื่อที่เข้าเกณฑ์ของฟังก์ชัน กฎ ผู้ให้บริการ หรือแง่มุมต่างๆ ที่ส่งออก (หรือ ที่ซ้อนอยู่) เพื่อดึงข้อมูลเอกสารประกอบ ในที่นี้ name หมายถึงชื่อที่เอนทิตีพร้อมใช้งานสำหรับผู้ใช้ของโมดูล รวมถึง Struct ที่เอนทิตีฝังอยู่สำหรับเนมสเปซ `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

ชื่อ ต้องระบุ

ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้

tags

รายการสตริง nonconfigurable; ค่าเริ่มต้นคือ []

รายการแท็กข้อความ เช่น "เล็ก" หรือ "ฐานข้อมูล" หรือ "-ไม่สม่ำเสมอ" แท็กอาจเป็นสตริงใดก็ได้ที่ถูกต้อง

แท็กที่ขึ้นต้นด้วย "-" ถือเป็นแท็กเชิงลบ อยู่หน้า "-" ไม่ถือว่าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็กชุด ของ "-small" ตรงกับค่า "small" ของการทดสอบ ขนาด แท็กอื่นๆ ทั้งหมดจะได้รับการพิจารณา แท็กเชิงบวก

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

เฉพาะกฎทดสอบที่ตรงกับแท็กบวกทั้งหมดและไม่มีแท็กเชิงลบ แท็กจะรวมอยู่ในชุดทดสอบ โปรดทราบว่าไม่ได้หมายความว่าการตรวจสอบข้อผิดพลาด สำหรับทรัพยากร Dependency ของการทดสอบที่ถูกกรองออกจะถูกข้ามไป ทรัพยากร Dependency ที่ข้ามไป การทดสอบยังคงต้องเป็นข้อมูลทางกฎหมาย (เช่น ไม่ได้ถูกบล็อกโดยข้อจํากัดระดับการมองเห็น)

ระบบจะดำเนินการกับคีย์เวิร์ดของแท็ก manual แตกต่างจากข้างต้นโดย "การขยาย test_suite" ดำเนินการโดยคำสั่ง blaze test ในการเรียกใช้ ที่เกี่ยวข้องกับไวลด์การ์ด รูปแบบเป้าหมาย ที่นั่น test_suite เป้าหมายที่ติดแท็ก "ด้วยตนเอง" จะถูกกรองออก (ดังนั้นจึงไม่ใช่ ขยาย) พฤติกรรมนี้สอดคล้องกับวิธีที่ blaze build และ รูปแบบเป้าหมายไวลด์การ์ดที่ใช้จัดการ blaze test โดยทั่วไป โปรดทราบว่านี่คือ แตกต่างจากลักษณะการทำงานของ blaze query 'tests(E)' อย่างชัดเจน เนื่องจากห้องสวีท ขยายเสมอโดยฟังก์ชันการค้นหา tests โดยไม่คำนึงถึง manual

โปรดทราบว่า size ของการทดสอบจะถือเป็นแท็กสำหรับการกรอง

หากคุณต้องการ test_suite ที่มีการทดสอบกับแท็กที่ใช้พร้อมกันไม่ได้ (เช่น การทดสอบขนาดเล็กและขนาดกลางทั้งหมด) คุณจะต้องสร้าง test_suite 3 รายการ กฎหนึ่งข้อคือ กฎข้อหนึ่งต่อหนึ่งการทดสอบขนาดเล็กทั้งหมด หนึ่งข้อสำหรับการทดสอบขั้นกลางทั้งหมด และอีกข้อหนึ่งที่รวม 2 อันก่อนหน้า

tests

รายการป้ายกำกับ nonconfigurable; ค่าเริ่มต้นคือ []

รายการชุดทดสอบและเป้าหมายทดสอบของภาษาใดก็ได้

โดยยอมรับ *_test ทั้งหมดที่นี่ โดยไม่คำนึงถึงภาษา ยังไม่ได้ติดต่อ อย่างไรก็ตาม เป้าหมาย *_binary จะได้รับการยอมรับ แม้ว่าจะเป็นการทดสอบก็ตาม การกรองตาม tags ที่ระบุจะดําเนินการเฉพาะกับการทดสอบที่แสดงในรายการโดยตรงใน แอตทริบิวต์นี้ หากแอตทริบิวต์นี้มี test_suite การทดสอบภายใน รายการเหล่านั้นจะไม่ผ่านการกรองโดย test_suite นี้ (จะถือเป็น กรองแล้ว)

หากไม่ได้ระบุหรือเว้นว่างแอตทริบิวต์ tests ไว้ กฎจะมีค่าเริ่มต้นเป็น รวมกฎการทดสอบทั้งหมดในไฟล์ BUILD ปัจจุบันที่ไม่ได้ติดแท็ก manual กฎเหล่านี้ยังคงขึ้นอยู่กับการกรองtag