กฎทั่วไป

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

กฎ

ชื่อแทน

ดูแหล่งที่มาของกฎ
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",
      ]
  )
  
ในทุกกรณีเหล่านี้ การกำหนดค่าอาจเปลี่ยนแปลงภายในบิลด์ได้ เช่น หากต้องสร้างเป้าหมายสำหรับแพลตฟอร์มอื่นที่ไม่ใช่แพลตฟอร์มของ dep ซึ่งหมายความว่าแม้ว่า config_setting จะไม่ตรงกับ Flag บรรทัดคำสั่งระดับบนสุด แต่ก็อาจยังคงตรงกับเป้าหมายการสร้างบางรายการ

หมายเหตุ

  • ดูสิ่งที่จะเกิดขึ้นเมื่อ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 ความหมายที่แน่นอนจะแตกต่างกันไปในแต่ละ Flag ตัวอย่างเช่น --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 และทดสอบเงื่อนไขอย่างละเอียดเพื่อยืนยันสิ่งที่คาดหวัง

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

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

Attributes
name

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

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

constraint_values

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

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

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

define_values

พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ {}

เหมือนกันกับ values แต่ สำหรับการตั้งค่าสถานะ --define โดยเฉพาะ

--define นั้นพิเศษเนื่องจากไวยากรณ์ (--define KEY=VAL) หมายความว่า KEY=VAL เป็นค่าจากมุมมองของ Flag ของ 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

พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ {}

ชุดของการกำหนดค่าที่ตรงกับกฎนี้ (แสดงเป็นแฟล็กบิลด์)

กฎนี้รับการกำหนดค่าของเป้าหมายที่กำหนดค่าไว้ซึ่ง อ้างถึงในคำสั่ง select ถือว่าได้ "จับคู่" คำขอ Bazel หากทุกๆ คำในพจนานุกรม การกำหนดค่าตรงกับค่าที่คาดไว้ของรายการ ตัวอย่างเช่น values = {"compilation_mode": "opt"} ตรงกับคำขอ bazel build --compilation_mode=opt ... และ bazel build -c opt ... ในกฎที่กำหนดค่าเป้าหมาย

เพื่อความสะดวก ค่าของการกำหนดค่าจึงมีการระบุเป็นแฟล็กบิลด์ (ไม่มี "--" ก่อนหน้า) แต่อย่าลืมว่าทั้ง 2 สิ่งนี้ไม่เหมือนกัน เนื่องจากเป้าหมายสามารถสร้างได้หลายรูปแบบภายในบิลด์เดียวกัน เช่น "cpu" ของการกำหนดค่า exec ตรงกับค่าของ --host_cpu ไม่ใช่ --cpu ดังนั้น config_setting เดียวกันในอินสแตนซ์ต่างๆ อาจจับคู่กับการเรียกใช้เดียวกันแตกต่างกันไป ทั้งนี้ขึ้นอยู่กับการกําหนดค่าของกฎที่ใช้ config_setting

หากไม่ได้ตั้งค่า Flag อย่างชัดเจนในบรรทัดคำสั่ง ระบบจะใช้ค่าเริ่มต้นของ 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 ของกฎที่ขึ้นอยู่กับกฎข้อนี้ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้และพึ่งพาไฟล์ข้อมูลได้ที่ส่วนการพึ่งพาข้อมูลและเอกสารประกอบทั่วไปของ data

output_group

String; ค่าเริ่มต้นคือ ""

กลุ่มเอาต์พุตที่จะรวบรวมอาร์ติแฟกต์จากแหล่งที่มา หากระบุแอตทริบิวต์นี้ ระบบจะส่งออกอาร์ติแฟกต์จากกลุ่มเอาต์พุตที่ระบุของข้อกําหนดเบื้องต้นแทนกลุ่มเอาต์พุตเริ่มต้น

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

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 เป็น "จริง" (หาก strict เป็น "เท็จ" ระบบจะข้ามเป้าหมายที่อยู่นอกขอบเขตพร้อมแสดงคำเตือน) วิธีที่ง่ายที่สุดในการหลีกเลี่ยงปัญหานี้คือระบุป้ายกำกับเดียวกันในขอบเขตเดียวกับในนิพจน์การค้นหา

ความแตกต่างเพียงอย่างเดียวระหว่างคำค้นหาที่อนุญาตที่นี่และในคำสั่ง คือข้อความค้นหาที่มีข้อกำหนดเป้าหมายไวลด์การ์ด (เช่น //pkg:*หรือ//pkg:all) ไม่ได้รับอนุญาตที่นี่ สาเหตุมี 2 ประการ ประการแรก เนื่องจาก genquery ต้องระบุขอบเขตเพื่อป้องกันไม่ให้เป้าหมายที่อยู่นอกการปิดเชิงสื่อกลางของการค้นหาส่งผลต่อเอาต์พุต และประการที่ 2 เนื่องจากไฟล์ 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 จะบีบอัดเอาต์พุตการค้นหาที่มีขนาดใหญ่กว่า 220 ไบต์อยู่แล้วภายในโดยไม่คำนึงถึงค่าของการตั้งค่านี้ ดังนั้นการตั้งค่านี้เป็น 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 ที่ผู้ใช้กำหนด

Genrules คือกฎการสร้างทั่วไปที่คุณใช้ได้หากไม่มีกฎเฉพาะสำหรับงาน เช่น คุณอาจเรียกใช้ 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 นอกจากนี้ยังมี ตัวแปร "Make" ที่คำสั่ง genrule สามารถส่งไปยังเครื่องมือที่เกี่ยวข้องได้

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

กรณีพิเศษ

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

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

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

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

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

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

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

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

  • ตรวจสอบว่าเครื่องมือที่ genrule เรียกใช้เป็นแบบกำหนดได้และปิดผนึก ผู้ใช้ไม่ควรเขียน การประทับเวลาไปยังเอาต์พุต และควรใช้การจัดลำดับที่เสถียรสำหรับชุดและแผนที่ รวมถึง เขียนเฉพาะเส้นทางไฟล์สัมพัทธ์ไปยังเอาต์พุต ไม่ใช่เส้นทางสัมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะ ทำให้เกิดลักษณะการสร้างที่ไม่คาดคิด (Bazel ไม่ได้สร้าง Genrule ใหม่อย่างที่คุณคิด) และ ทำให้ประสิทธิภาพของแคชลดลง
  • ใช้ $(location) อย่างครอบคลุมสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากมีการแยกไฟล์เอาต์พุตสําหรับการกําหนดค่าต่างๆ Genrules จึงใช้เส้นทางแบบฮาร์ดโค้ดและ/หรือเส้นทางสัมบูรณ์ไม่ได้
  • เขียนมาโคร Starlark ทั่วไปในกรณีที่มีการใช้กฎเกณฑ์เดียวกันหรือคล้ายกันมากใน หลายสถานที่ หาก genrule มีความซับซ้อน ให้พิจารณานำไปใช้ในสคริปต์หรือเป็นกฎ Starlark ซึ่งจะช่วยปรับปรุงความสามารถในการอ่านและความสามารถในการทดสอบ
  • ตรวจสอบว่าโค้ดสำหรับออกแสดงถึงความสำเร็จหรือความล้มเหลวของกฎ
  • อย่าเขียนข้อความที่ให้ข้อมูลไปยัง stdout หรือ stderr แม้ว่าจะมีประโยชน์สำหรับการแก้ไขข้อบกพร่อง แต่การดำเนินการนี้อาจกลายเป็นการรบกวนได้ง่ายๆ การดำเนินการ 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 ไม่คัดลอกไปยังไดเรกทอรี/ลิงก์สัญลักษณ์ สร้างโดย 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 ของผู้ใช้เหล่านั้นแทน

ระบบบิลด์จะสร้างข้อกําหนดเบื้องต้นเหล่านี้ก่อนที่จะเรียกใช้คําสั่ง genrule โดยระบบจะสร้างโดยใช้การกําหนดค่าเดียวกับคําขอบิลด์เดิม ชื่อไฟล์ของข้อกำหนดเบื้องต้นเหล่านี้จะมีให้กับคำสั่ง รายการที่คั่นด้วยช่องว่างใน $(SRCS) อีกทางเลือกหนึ่งคือเส้นทางของบุคคล รับ srcs เป้าหมาย //x:y ได้โดยใช้ $(location //x:y) หรือใช้ $< หากนี่เป็นข้อมูลเดียวใน srcs

outs

รายการชื่อไฟล์ กำหนดค่าไม่ได้ ต้องระบุ

รายการไฟล์ที่กฎนี้สร้าง

ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะแปลชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ

หากตั้งค่า Flag executable แล้ว outs ต้องมีป้ายกำกับเพียงรายการเดียว

ระบบคาดว่าคําสั่ง genrule จะสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า ตำแหน่งพร้อมใช้งานใน cmd โดยใช้ตัวแปร "Make" สำหรับ genrule โดยเฉพาะ ($@, $(OUTS), $(@D) หรือ $(RULEDIR)) หรือใช้การแทนที่ $(location)

cmd

String; ค่าเริ่มต้นคือ ""

คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับ $(location) และ "ผู้ผลิต" ตัวแปร
  1. มีการใช้การแทนที่ $(location) รายการแรกแล้ว โดยแทนที่รายการ $(location label) และ $(locations label) ทั้งหมด (และรายการอื่นๆ ที่คล้ายกัน การสร้างโดยใช้ตัวแปรที่เกี่ยวข้อง execpath, execpaths rootpath และ rootpaths)
  2. จากนั้น "สร้าง" ตัวแปรจะขยายออก โปรดทราบว่าตัวแปรที่กําหนดไว้ล่วงหน้า $(JAVA), $(JAVAC) และ $(JAVABASE) จะขยายภายใต้การกําหนดค่า exec เพื่อให้การเรียกใช้ Java ที่ทํางานเป็นส่วนหนึ่งของขั้นตอนการสร้างโหลดไลบรารีที่แชร์และข้อกําหนดอื่นๆ อย่างถูกต้อง
  3. สุดท้าย ระบบจะเรียกใช้คำสั่งที่ได้โดยใช้เชลล์ Bash หากรหัสทางออกคือ ไม่เป็นศูนย์จะถือว่าคำสั่งล้มเหลว
นี่คือค่าสำรองของ 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

สตริง ค่าเริ่มต้นคือ ""

คำสั่งแบตช์ที่จะทำงานใน Windows

แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า cmd และ cmd_bash คำสั่งจะทำงานในลักษณะเดียวกันกับแอตทริบิวต์ cmd โดยมีเมธอด ความแตกต่างดังต่อไปนี้

  • แอตทริบิวต์นี้ใช้ได้กับ Windows เท่านั้น
  • คำสั่งจะทำงานด้วย cmd.exe /c พร้อมอาร์กิวเมนต์เริ่มต้นต่อไปนี้
    • /S - นำเครื่องหมายคำพูดแรกและเครื่องหมายคำพูดสุดท้ายออก แล้วดำเนินการกับส่วนที่เหลือตามเดิม
    • /E:ON - เปิดใช้ชุดคำสั่งเพิ่มเติม
    • /V:ON - เปิดใช้การขยายตัวแปรที่ล่าช้า
    • /D - ละเว้นรายการรีจิสทรี AutoRun
  • หลัง $(location) และ "สร้าง" แทน เส้นทางจะ ขยายไปยังเส้นทางรูปแบบ 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

ประกาศเอาต์พุตที่เป็นไฟล์ปฏิบัติการ

การตั้งค่า Flag นี้เป็น "จริง" หมายความว่าเอาต์พุตเป็นไฟล์ที่เรียกใช้ได้และสามารถเรียกใช้โดยใช้คำสั่ง run ในกรณีนี้ genrule ต้องสร้างเอาต์พุตเพียงรายการเดียว หากตั้งค่าแอตทริบิวต์นี้ 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

หากเป็น "จริง" ระบบจะแสดงผลป้ายกำกับในที่เก็บข้อมูลหลักในเอกสารประกอบที่สร้างขึ้นด้วยคอมโพเนนต์ repo (กล่าวคือ ระบบจะแสดง //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 จะแสดงเอกสารประกอบสำหรับเอนทิตีก็ต่อเมื่อ

  1. ส่วนประกอบแต่ละส่วนของชื่อที่เข้าเกณฑ์ของเอนทิตีเป็นแบบสาธารณะ (กล่าวคือ อักขระของแต่ละส่วนประกอบของชื่อที่เข้าเกณฑ์จะเป็นตัวอักษร ไม่ใช่ "_") และ
    1. อย่างใดอย่างหนึ่งที่รายการ symbol_names ว่างเปล่า (ซึ่งเป็นค่าเริ่มต้น ตัวพิมพ์ใหญ่/เล็ก) หรือ
    2. ชื่อที่เข้าเกณฑ์ของเอนทิตี หรือชื่อที่เข้าเกณฑ์ของโครงสร้างที่นิติบุคคล ซ้อนกันอยู่ และอยู่ในรายการ 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" ของชุดทดสอบ แท็กอื่นๆ ทั้งหมดจะได้รับการพิจารณา แท็กเชิงบวก

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

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

ระบบจะดำเนินการกับคีย์เวิร์ดของแท็ก 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

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

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

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

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