กฎทั่วไป

รายงานปัญหา ดูแหล่งที่มา Nightly{/19/} Nightly{/19/} /4} /20}

กฎ

• ชื่อแทน
• 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	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
actual	ป้ายกำกับ ต้องระบุ เป้าหมายที่ชื่อแทนนี้อ้างถึง ซึ่งไม่จำเป็นต้องเป็นกฎ แต่จะเป็นไฟล์อินพุตก็ได้

config_setting

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

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

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

ตัวอย่าง

รายการต่อไปนี้ตรงกับบิลด์ใดก็ตามที่ตั้งค่า --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",
      ]
  )
  

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

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

ตัวอย่าง

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

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

หรือใช้ 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	สตริง ค่าเริ่มต้นคือ "" กลุ่มเอาต์พุตที่จะรวบรวมอาร์ติแฟกต์จากแหล่งที่มา หากระบุแอตทริบิวต์นี้ ระบบจะส่งออกอาร์ติแฟกต์จากกลุ่มเอาต์พุตที่ระบุของทรัพยากร 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 เมื่อคาดว่าเอาต์พุตการค้นหาจะมีขนาดใหญ่ 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 หนึ่งบรรทัด อย่างไรก็ตาม หากจำเป็นต้องคอมไพล์ไฟล์ C++ ให้ใช้กฎ cc_* ที่มีอยู่ เนื่องจากระบบได้ดำเนินการยกน้ำหนักทั้งหมดให้คุณแล้ว

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

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

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

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

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

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

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

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

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

คดีพิเศษ

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

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

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

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

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

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

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

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

• ตรวจสอบให้แน่ใจว่าเครื่องมือที่เรียกใช้โดยกฎพันธุกรรมมีความละเอียดอ่อนและมีความต่อเนื่อง ไม่ควรเขียนการประทับเวลาไปยังเอาต์พุต และควรใช้ลำดับที่เสถียรสำหรับชุดและแมป รวมถึงเขียนเฉพาะเส้นทางของไฟล์สัมพัทธ์ไปยังเอาต์พุตโดยใช้เส้นทางสัมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะนำไปสู่ลักษณะการสร้างที่ไม่คาดคิด (Bazel ไม่สร้าง Genrule ที่คุณคิดขึ้นใหม่) และ ลดประสิทธิภาพของแคช
• ใช้ $(location) อย่างครอบคลุมสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากการแยกไฟล์เอาต์พุตสำหรับการกำหนดค่าที่แตกต่างกัน Genrule จึงใช้เส้นทางแบบฮาร์ดโค้ดและ/หรือแบบสัมบูรณ์ไม่ได้
• เขียนมาโคร Starlark ทั่วไปเผื่อในกรณีที่มีการใช้กฎเกณฑ์เดียวกันหรือคล้ายกันมากใน หลายที่ หาก Genrule ซับซ้อน ให้พิจารณาใช้งานในสคริปต์หรือกฎ Starlark วิธีนี้จะช่วยเพิ่มความสะดวกในการอ่านและการทดสอบ
• ตรวจสอบว่าโค้ดสำหรับออกแสดงถึงความสำเร็จหรือความล้มเหลวของกฎ
• อย่าเขียนข้อความแจ้งข้อมูลไปยัง 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) หรืออาจดูเส้นทางของเป้าหมาย //x:y แต่ละรายการของ srcs ได้โดยใช้ $(location //x:y) หรือใช้ $< หากเป็นรายการเดียวใน srcs
outs	รายชื่อชื่อไฟล์ nonconfigurable ต้องระบุ รายการไฟล์ที่กฎนี้สร้าง ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะแปลชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ หากตั้งค่าแฟล็ก executable ไว้ outs ต้องมีป้ายกำกับเพียง 1 รายการเท่านั้น คำสั่ง Genrule ต้องการสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า ตำแหน่งพร้อมใช้งานใน cmd โดยใช้ตัวแปร "Make" ที่เจาะจงตามกฎ ($@, $(OUTS), $(@D) หรือ $(RULEDIR)) หรือใช้การแทนที่ $(location)
cmd	สตริง ค่าเริ่มต้นคือ "" คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับการแทนที่ $(location) และ ตัวแปร"Make" มีการใช้การแทนที่ $(location) รายการแรก โดยแทนที่รายการ $(location label) และ $(locations label) ทั้งหมด (และการสร้างที่คล้ายกันซึ่งใช้ตัวแปรที่เกี่ยวข้อง execpath, execpaths, rootpath และ rootpaths) จากนั้น ตัวแปร"Make" จะขยายออก โปรดทราบว่าตัวแปรที่กำหนดไว้ล่วงหน้า $(JAVA), $(JAVAC) และ $(JAVABASE) จะขยายออกภายใต้การกำหนดค่า exec ดังนั้นการเรียกใช้ Java ที่ทำงานเป็นส่วนหนึ่งของขั้นตอนบิลด์จะโหลดไลบรารีที่ใช้ร่วมกันและทรัพยากร Dependency อื่นๆ ได้อย่างถูกต้อง สุดท้าย ระบบจะดำเนินการคำสั่งโดยใช้ 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	สตริง ค่าเริ่มต้นคือ "" คำสั่งแบบกลุ่มที่จะเรียกใช้ใน 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	สตริง ค่าเริ่มต้นคือ "" ข้อความความคืบหน้า ข้อความความคืบหน้าที่จะพิมพ์เมื่อมีการดำเนินการขั้นตอนบิลด์นี้ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้าง output" (หรืออะไรสักอย่างเท่าๆ กัน) แต่คุณระบุข้อความที่เจาะจงมากกว่านี้ก็ได้ ใช้แอตทริบิวต์นี้แทน 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 ที่ระบุ เอาต์พุตของกฎนี้คือ ModuleInfo Proto ไบนารีตามที่กำหนดไว้ใน stardoc_output.proto ในโครงสร้างต้นทางของ Bazel

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

• name.binaryproto (เอาต์พุตเริ่มต้น): ModuleInfo Proto ของไบนารี
• name.textproto (สร้างเฉพาะในกรณีที่มีการขออย่างชัดแจ้งเท่านั้น): ข้อความเวอร์ชัน Pro ของ 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	รายการสตริง ค่าเริ่มต้นคือ [] รายการที่ไม่บังคับของชื่อที่เข้าเกณฑ์ของฟังก์ชัน กฎ ผู้ให้บริการ หรือด้านต่างๆ (หรือโครงสร้างที่มีการซ้อนกัน) ที่ส่งออกสำหรับดึงข้อมูลเอกสาร ในที่นี้ ชื่อที่เข้าเกณฑ์หมายถึงชื่อที่เอนทิตีพร้อมใช้งานสำหรับผู้ใช้ของโมดูล รวมถึงโครงสร้างที่เอนทิตีซ้อนกันไว้สำหรับการกำหนดชื่อ 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 ก่อน (เราเรียกว่า "การขยาย 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	รายการสตริง nonconfigurable ค่าเริ่มต้นคือ [] รายการแท็กข้อความ เช่น "เล็ก" หรือ "ฐานข้อมูล" หรือ "-ไม่สม่ำเสมอ" แท็กอาจเป็นสตริงใดก็ได้ที่ถูกต้อง แท็กที่ขึ้นต้นด้วย "-" จะถือว่าเป็นแท็กเชิงลบ อักขระ "-" ที่อยู่ก่อนหน้าไม่ถือว่าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็กชุด "-ขนาดเล็ก" จะตรงกับขนาด "เล็ก" ของการทดสอบ ส่วนแท็กอื่นๆ ทั้งหมดจะถือเป็นแท็กเชิงบวก หากต้องการให้แท็กเชิงบวกมีความชัดเจนมากขึ้น แท็กอาจขึ้นต้นด้วยอักขระ "+" ซึ่งระบบจะไม่ประเมินเป็นส่วนหนึ่งของข้อความของแท็ก เพียงแต่ทำให้อ่านความแตกต่างด้านบวกและด้านลบได้ง่ายขึ้น ชุดทดสอบจะรวมเฉพาะกฎทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและไม่มีแท็กใดแท็กหนึ่งเท่านั้น โปรดทราบว่านี่ไม่ได้หมายความว่าระบบจะข้ามข้อผิดพลาดในการตรวจสอบทรัพยากร Dependency ในการทดสอบที่ถูกกรองออก แต่ทรัพยากร Dependency ในการทดสอบที่ถูกข้ามยังคงต้องเป็นข้อมูลทางกฎหมาย (เช่น ไม่ได้ถูกบล็อกโดยข้อจํากัดระดับการมองเห็น) ระบบจะจัดการกับคีย์เวิร์ดของแท็ก manual ที่แตกต่างจากข้างต้นโดย "การขยายtest_suite" ซึ่งทําโดยคําสั่ง bazel test ในการเรียกใช้ที่เกี่ยวข้องกับรูปแบบเป้าหมายไวลด์การ์ด เป้าหมาย test_suite รายการที่ติดแท็ก "ด้วยตนเอง" จะถูกกรองออก (จึงไม่ขยายออก) ลักษณะการทำงานนี้สอดคล้องกับวิธีที่ bazel build และ bazel test จัดการรูปแบบเป้าหมายไวลด์การ์ดโดยทั่วไป โปรดทราบว่านโยบายนี้แตกต่างจากลักษณะการทำงานของ bazel query 'tests(E)' อย่างชัดเจน เนื่องจากฟังก์ชันการค้นหาของ tests จะขยายชุดโปรแกรมเสมอ โดยไม่คำนึงถึงแท็ก manual โปรดทราบว่า size ของการทดสอบจะถือเป็นแท็กสำหรับการกรอง หากต้องการใช้ test_suite ที่มีการทดสอบที่มีแท็กเฉพาะร่วมกัน (เช่น การทดสอบขนาดเล็กและขนาดกลางทั้งหมด) คุณจะต้องสร้างกฎ test_suite 3 ข้อ กฎ 1 ข้อสำหรับการทดสอบขนาดเล็กทั้งหมด กฎ 1 ข้อสำหรับการทดสอบขนาดกลางทั้งหมด และ 1 ข้อรวม 2 กฎก่อนหน้านี้
tests	รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ [] รายการชุดทดสอบและเป้าหมายทดสอบของภาษาใดก็ได้ โดยยอมรับ *_test ทั้งหมดที่นี่ โดยไม่คำนึงถึงภาษา อย่างไรก็ตาม ระบบไม่ยอมรับเป้าหมาย *_binary แม้ว่าจะเป็นการทดสอบก็ตาม การกรองตาม tags ที่ระบุจะใช้สำหรับการทดสอบที่แสดงอยู่ในแอตทริบิวต์นี้โดยตรงเท่านั้น หากแอตทริบิวต์นี้มี test_suite การทดสอบภายในเหล่านั้นจะไม่กรองด้วย test_suite นี้ (ถือว่าได้รับการกรองแล้ว) หากไม่ได้ระบุหรือเว้นว่างแอตทริบิวต์ tests ไว้ กฎจะมีค่าเริ่มต้นเป็นการรวมกฎการทดสอบทั้งหมดในไฟล์ BUILD ปัจจุบันที่ไม่ได้ติดแท็กเป็น manual กฎเหล่านี้ยังคงขึ้นอยู่กับการกรองtag