Build Foundation เริ่มรับสมัครสมาชิกผู้ก่อตั้งแล้ว เข้าร่วมรายชื่ออีเมล อ่านข้อตกลงในการเข้าร่วม และลงทะเบียน

กฎทั่วไป

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

กฎ

alias
config_setting
filegroup
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"
      }
  )

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

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

Attributes
`name`	ชื่อ (ต้องระบุ) ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`constraint_values`	รายการป้ายกำกับ กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ `[]` ชุด `constraint_values` ขั้นต่ำที่แพลตฟอร์มเป้าหมายต้องระบุ เพื่อให้ตรงกับ `config_setting` นี้ (ระบบจะไม่พิจารณาแพลตฟอร์มการดำเนินการที่นี่) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมที่แพลตฟอร์มมี ดูรายละเอียดได้ที่ แอตทริบิวต์บิลด์ที่กำหนดค่าได้ หาก `config_setting` 2 รายการตรงกันใน `select` เดียวกัน และรายการหนึ่งมี แฟล็กและ `constraint_setting` เหมือนกับอีกรายการทั้งหมด รวมถึงมีแฟล็กและ `constraint_setting` เพิ่มเติม ระบบจะเลือกรายการที่มีการตั้งค่ามากกว่า ซึ่งเรียกว่า "การเชี่ยวชาญ" เช่น `config_setting` ที่ตรงกับ `x86` และ `Linux` จะมีความเชี่ยวชาญ มากกว่า `config_setting` ที่ตรงกับ `x86` หาก `config_setting` 2 รายการตรงกันและทั้ง 2 รายการมี `constraint_value` ที่ไม่มีในอีกรายการหนึ่ง จะถือว่าเป็นข้อผิดพลาด
`define_values`	พจนานุกรม: สตริง -> สตริง กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ `{}` เหมือนกับ `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 -> String; nonconfigurable; ค่าเริ่มต้นคือ `{}` เหมือนกับ `values` แต่ สำหรับ Flag บิลด์ที่ผู้ใช้กำหนด นี่เป็นแอตทริบิวต์ที่แตกต่างกันเนื่องจากมีการอ้างอิงแฟล็กที่กำหนดโดยผู้ใช้เป็นป้ายกำกับ ขณะที่ มีการอ้างอิงแฟล็กในตัวเป็นสตริงที่กำหนดเอง
`values`	พจนานุกรม: สตริง -> สตริง กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ `{}` ชุดค่าการกำหนดค่าที่ตรงกับกฎนี้ (แสดงเป็นแฟล็กบิลด์) กฎนี้จะรับค่ากำหนดของเป้าหมายที่กำหนดค่าไว้ซึ่ง อ้างอิงในคำสั่ง `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 ไม่ใช่ตัวแทนของการแสดงเป้าหมายในบรรทัดคำสั่งหรือ ในแอตทริบิวต์ของกฎอื่น เนื่องจากเป้าหมายมีพร็อพเพอร์ตี้มากมายนอกเหนือจากเอาต์พุต ซึ่งไม่ได้รวบรวมในลักษณะเดียวกัน อย่างไรก็ตาม ยังคงมีประโยชน์ในบางกรณี เช่น ในแอตทริบิวต์ srcs ของ genrule หรือแอตทริบิวต์ data ของกฎ *_binary

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

ตัวอย่าง

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

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

หรือใช้ glob เพื่อทำการ Crawl ไดเรกทอรี 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` ของกฎที่ขึ้นอยู่กับกฎนั้น ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้ไฟล์ข้อมูลและขึ้นอยู่กับไฟล์ข้อมูลได้ที่ส่วนการขึ้นต่อกันของข้อมูล และเอกสารทั่วไปของ `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() เรียกใช้การค้นหาที่ระบุไว้ใน ภาษาการค้นหาของ Bazel และส่งออกผลลัพธ์ ไปยังไฟล์

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

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

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

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

ตัวอย่าง

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

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

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

Attributes
`name`	ชื่อ (ต้องระบุ) ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`compressed_output`	บูลีน ค่าเริ่มต้นคือ `False` หาก `True` ระบบจะเขียนเอาต์พุตการค้นหาในรูปแบบไฟล์ GZIP การตั้งค่านี้ใช้ได้ เพื่อหลีกเลี่ยงการเพิ่มขึ้นของการใช้หน่วยความจำของ Bazel เมื่อคาดว่าเอาต์พุตการค้นหาจะมีขนาดใหญ่ Bazel จะบีบอัดเอาต์พุตการค้นหาที่มีขนาดมากกว่า 2²⁰ ไบต์ภายในอยู่แล้ว ไม่ว่าค่าของการตั้งค่านี้จะเป็นอย่างไร ดังนั้นการตั้งค่านี้เป็น `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 ที่ผู้ใช้กำหนด

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

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

เช่นเดียวกับการดำเนินการอื่นๆ การดำเนินการที่สร้างโดย genrules ไม่ควรสมมติสิ่งใดเกี่ยวกับ ไดเรกทอรีการทำงาน สิ่งที่ Bazel รับประกันทั้งหมดคืออินพุตที่ประกาศไว้จะพร้อมใช้งานที่ เส้นทางที่ $(location) แสดงผลสำหรับป้ายกำกับ ตัวอย่างเช่น หากการดำเนินการทำงานใน แซนด์บ็อกซ์หรือจากระยะไกล การติดตั้งใช้งานแซนด์บ็อกซ์หรือการดำเนินการจากระยะไกลจะเป็นตัวกำหนด ไดเรกทอรีการทำงาน หากเรียกใช้โดยตรง (ใช้กลยุทธ์ standalone) ไดเรกทอรีการทำงานจะเป็นรูทการดำเนินการ นั่นคือ ผลลัพธ์ของ bazel info execution_root

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

ข้อควรพิจารณาในการคอมไพล์แบบข้ามระบบ

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

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

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

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

เราตั้งใจที่จะไม่กำหนดแอตทริบิวต์ deps ใน genrule เนื่องจากกฎอื่นๆ ที่มีอยู่ภายในใช้ข้อมูลเมตาที่ขึ้นอยู่กับภาษาซึ่งส่งผ่านระหว่างกฎเพื่อกำหนดวิธีจัดการกฎที่ขึ้นต่อกันโดยอัตโนมัติ แต่การทำงานอัตโนมัติในระดับนี้ไม่สามารถใช้กับ genrule ได้ Genrules work purely at the file and runfiles level.

กรณีพิเศษ

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

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

สภาพแวดล้อม Genrule

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

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

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

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

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

โปรดตรวจสอบว่าเครื่องมือที่เรียกใช้โดย genrule เป็นแบบดีเทอร์มินิสติกและเฮอร์เมติก โดยไม่ควรเขียน การประทับเวลาลงในเอาต์พุต และควรใช้การจัดลำดับที่เสถียรสำหรับชุดและแผนที่ รวมถึง เขียนเฉพาะเส้นทางไฟล์แบบสัมพัทธ์ไปยังเอาต์พุตเท่านั้น ไม่ใช่เส้นทางแบบสัมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะ ทําให้เกิดลักษณะการทํางานของการบิลด์ที่ไม่คาดคิด (Bazel ไม่สร้าง genrule ใหม่ตามที่คุณคิด) และทําให้ประสิทธิภาพของแคชลดลง
ใช้ $(location) อย่างกว้างขวางสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากมีการแยกไฟล์เอาต์พุตสำหรับการกำหนดค่าต่างๆ genrule จึงไม่สามารถใช้เส้นทางที่ฮาร์ดโค้ดและ/หรือเส้นทางแบบสัมบูรณ์ได้
เขียนมาโคร Starlark ทั่วไปในกรณีที่มีการใช้ genrule เดียวกันหรือคล้ายกันมากในหลายที่ หาก genrule มีความซับซ้อน ให้พิจารณาใช้ในสคริปต์หรือเป็น กฎ Starlark ซึ่งจะช่วยให้อ่านได้ง่ายขึ้นและทดสอบได้
โปรดตรวจสอบว่ารหัสออกระบุความสำเร็จหรือความล้มเหลวของ genrule อย่างถูกต้อง
อย่าเขียนข้อความข้อมูลไปยัง stdout หรือ stderr แม้ว่าจะมีประโยชน์สำหรับการแก้ไขข้อบกพร่อง แต่ก็อาจ กลายเป็นสัญญาณรบกวนได้ง่ายๆ genrule ที่สำเร็จควรไม่มีเอาต์พุต ในทางกลับกัน genrule ที่ล้มเหลว ควรแสดงข้อความแสดงข้อผิดพลาดที่ดี
$$ 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 และการตรวจสอบทรัพยากร 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` แทน ระบบบิลด์จะตรวจสอบว่ามีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนที่จะเรียกใช้คำสั่ง genrule โดยจะสร้างขึ้นโดยใช้การกำหนดค่าเดียวกันกับคำขอบิลด์เดิม ชื่อไฟล์ของข้อกำหนดเบื้องต้นเหล่านี้พร้อมใช้งานกับคำสั่งเป็นรายการที่คั่นด้วยช่องว่างใน `$(SRCS)` หรืออาจรับเส้นทางของเป้าหมาย `srcs` `//x:y` แต่ละรายการได้โดยใช้ `$(location //x:y)` หรือใช้ `$<` หากเป็นรายการเดียวใน `srcs`
`outs`	รายการชื่อไฟล์ กำหนดค่าไม่ได้ ต้องระบุ รายการไฟล์ที่สร้างขึ้นโดยกฎนี้ ไฟล์เอาต์พุตต้องไม่อยู่นอกขอบเขตของแพ็กเกจ ระบบจะตีความชื่อไฟล์เอาต์พุตเป็นแบบสัมพัทธ์กับแพ็กเกจ หากตั้งค่าแฟล็ก `executable` ไว้ `outs` ต้องมีป้ายกำกับเพียงป้ายเดียว คำสั่ง genrule คาดว่าจะสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า ตำแหน่งจะอยู่ใน `cmd` โดยใช้ตัวแปร "Make" ที่เฉพาะเจเนอเรชัน (`$@`, `$(OUTS)`, `$(@D)` หรือ `$(RULEDIR)`) หรือใช้การแทนที่ `$(location)`
`cmd`	สตริง ค่าเริ่มต้นคือ `""` คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับ`$(location)`และการแทนที่ตัวแปร"Make" ระบบจะใช้การแทนที่`$(location)`ก่อน โดยแทนที่อินสแตนซ์ทั้งหมดของ `$(location label)` และ `$(locations label)` (และโครงสร้างที่คล้ายกัน โดยใช้ตัวแปรที่เกี่ยวข้อง `execpath`, `execpaths`, `rootpath` และ `rootpaths`) จากนั้นระบบจะขยายตัวแปร"สร้าง" โปรดทราบว่าตัวแปรที่กำหนดไว้ล่วงหน้า `$(JAVA)`, `$(JAVAC)` และ `$(JAVABASE)` จะขยายภายใต้การกำหนดค่า exec ดังนั้นการเรียกใช้ Java ที่ทำงานเป็นส่วนหนึ่งของขั้นตอนการสร้างจะโหลดไลบรารีที่แชร์และการอ้างอิงอื่นๆ ได้อย่างถูกต้อง สุดท้าย ระบบจะเรียกใช้คำสั่งที่ได้โดยใช้ Bash Shell หากรหัสออกเป็น ไม่ใช่ 0 ระบบจะถือว่าคำสั่งล้มเหลว นี่คือตัวเลือกสำรองของ `cmd_bash`, `cmd_ps` และ `cmd_bat` หากไม่มีตัวเลือกใดที่เกี่ยวข้อง หากความยาวของบรรทัดคำสั่งเกินขีดจำกัดของแพลตฟอร์ม (64K ใน Linux/macOS, 8K ใน Windows) genrule จะเขียนคำสั่งลงในสคริปต์และเรียกใช้สคริปต์นั้นเพื่อหลีกเลี่ยง ซึ่ง ใช้กับแอตทริบิวต์ cmd ทั้งหมด (`cmd`, `cmd_bash`, `cmd_ps`, `cmd_bat`)
`cmd_bash`	สตริง ค่าเริ่มต้นคือ `""` คำสั่ง Bash ที่จะเรียกใช้ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า `cmd` ระบบจะขยายคำสั่งและ เรียกใช้ในลักษณะเดียวกับแอตทริบิวต์ `cmd`
`cmd_bat`	สตริง ค่าเริ่มต้นคือ `""` คำสั่ง Batch ที่จะเรียกใช้ใน 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 ได้ง่ายขึ้นและมีข้อผิดพลาดน้อยลง เราจึงเรียกใช้คำสั่งต่อไปนี้ เพื่อตั้งค่าสภาพแวดล้อมก่อนที่จะเรียกใช้คำสั่ง Powershell ใน genrule `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` - อนุญาตให้เรียกใช้ สคริปต์ที่ไม่ได้ลงนาม `$errorActionPreference='Stop'` - ในกรณีที่มีหลายคำสั่ง คั่นด้วย `;` การดำเนินการจะออกทันทีหาก CmdLet ของ Powershell ล้มเหลว แต่จะไม่ทำงานสำหรับคำสั่งภายนอก `$PSDefaultParameterValues['*:Encoding'] = 'utf8'` - เปลี่ยนการเข้ารหัสเริ่มต้น จาก utf-16 เป็น utf-8
`executable`	บูลีน กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ `False` ประกาศว่าเอาต์พุตเป็นไฟล์ที่เรียกใช้งานได้ การตั้งค่าสถานะนี้เป็น "จริง" หมายความว่าเอาต์พุตเป็นไฟล์ที่สั่งการได้และเรียกใช้ได้โดยใช้คำสั่ง `run` ในกรณีนี้ genrule ต้องสร้างเอาต์พุต 1 รายการเท่านั้น หากตั้งค่าแอตทริบิวต์นี้ `run` จะพยายามเรียกใช้ไฟล์โดยไม่คำนึงถึง เนื้อหาของไฟล์ ระบบไม่รองรับการประกาศการขึ้นต่อกันของข้อมูลสำหรับไฟล์ที่เรียกใช้งานที่สร้างขึ้น
`local`	บูลีน ค่าเริ่มต้นคือ `False` หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะบังคับให้ `genrule` นี้ทำงานโดยใช้กลยุทธ์ "ในเครื่อง" ซึ่งหมายความว่าจะไม่มีการดำเนินการจากระยะไกล ไม่มีแซนด์บ็อกซ์ และไม่มี Worker แบบถาวร ซึ่งเทียบเท่ากับการระบุ "local" เป็นแท็ก (`tags=["local"]`)
`message`	สตริง ค่าเริ่มต้นคือ `""` ข้อความแสดงความคืบหน้า ข้อความความคืบหน้าที่จะพิมพ์เมื่อขั้นตอนบิลด์นี้ดำเนินการ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้างเอาต์พุต" (หรือข้อความที่คล้ายกัน) แต่คุณอาจระบุข้อความที่เจาะจงมากขึ้นได้ ใช้แอตทริบิวต์นี้แทน `echo` หรือคำสั่ง print อื่นๆ ในคำสั่ง `cmd` เนื่องจากจะช่วยให้เครื่องมือบิลด์ควบคุมได้ว่าจะพิมพ์ข้อความความคืบหน้าดังกล่าวหรือไม่
`output_licenses`	ประเภทใบอนุญาต ค่าเริ่มต้นคือ `["none"]` ดู `common attributes`
`output_to_bindir`	บูลีน กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ `False` หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทำให้ระบบเขียนไฟล์เอาต์พุตลงในไดเรกทอรี `bin` แทนไดเรกทอรี `genfiles`
`tools`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการการอ้างอิงของเครื่องมือสำหรับกฎนี้ ดูข้อมูลเพิ่มเติมได้ที่คำจำกัดความของการขึ้นต่อกัน ระบบบิลด์จะตรวจสอบว่ามีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนที่จะเรียกใช้คำสั่ง 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 ไบนารีโปรโตตามที่กำหนดไว้ ใน stardoc_output.proto ในโครงสร้างแหล่งที่มาของ Bazel

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

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

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

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

Attributes
`name`	ชื่อ (ต้องระบุ) ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`deps`	รายการป้ายกำกับ ค่าเริ่มต้นคือ `[]` รายการเป้าหมายที่ครอบคลุมไฟล์ Starlark ซึ่ง`load()`-ed โดย `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`	รายการสตริง ค่าเริ่มต้นคือ `[]` รายการชื่อที่ผ่านการรับรองของฟังก์ชัน กฎ ผู้ให้บริการ หรือแง่มุม (หรือ โครงสร้างที่มีการซ้อนกัน) ที่ส่งออกซึ่งจะดึงข้อมูลเอกสาร (ไม่บังคับ) ในที่นี้ ชื่อที่ผ่านการรับรอง แล้วหมายถึงชื่อที่ใช้ในการทำให้เอนทิตีพร้อมใช้งานสำหรับผู้ใช้โมดูล รวมถึงโครงสร้างใดๆ ที่เอนทิตีซ้อนอยู่เพื่อการกำหนด Namespace `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 จะกำหนดชุดการทดสอบที่ถือว่า "มีประโยชน์" ต่อมนุษย์ ซึ่งจะช่วยให้โปรเจ็กต์กำหนดชุดการทดสอบได้ เช่น "การทดสอบที่คุณต้องเรียกใช้ก่อนเช็คอิน" "การทดสอบความเครียดของโปรเจ็กต์" หรือ "การทดสอบขนาดเล็กทั้งหมด" คำสั่ง bazel test จะพิจารณาการจัดระเบียบประเภทนี้ สำหรับการเรียกใช้ เช่น bazel test //some/test:suite Bazel จะแจงเป้าหมายการทดสอบทั้งหมดที่รวมอยู่โดยอ้อมในเป้าหมาย //some/test:suite ก่อน (เราเรียกขั้นตอนนี้ว่า "การขยายชุดทดสอบ") จากนั้น Bazel จะสร้างและทดสอบเป้าหมายเหล่านั้น

ตัวอย่าง

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

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

รายการสตริง กำหนดค่าไม่ได้ ค่าเริ่มต้นคือ []

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

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

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

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

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

โปรดทราบว่า size ของการทดสอบถือเป็นแท็กเพื่อวัตถุประสงค์ในการกรอง

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

tests

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

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

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

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

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

กฎ

ชื่อแทน

ตัวอย่าง

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

config_setting

ตัวอย่าง

หมายเหตุ

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

กลุ่มไฟล์

ตัวอย่าง

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

genquery

ตัวอย่าง

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

genrule

ข้อควรพิจารณาในการคอมไพล์แบบข้ามระบบ

กรณีพิเศษ

สภาพแวดล้อม Genrule

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

ตัวอย่าง

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

starlark_doc_extract

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

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

test_suite

ตัวอย่าง

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

กฎทั่วไป