กฎทั่วไป

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

กฎ

alias
config_setting
filegroup
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

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

name

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

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

actual

ป้ายกำกับ (ต้องระบุ)

เป้าหมายที่แอนนาล็อกนี้อ้างอิงถึง โดยไม่จำเป็นต้องเป็นกฎ อาจเป็นไฟล์อินพุตก็ได้

config_setting

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

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

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

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

ในทุกกรณีเหล่านี้ การกำหนดค่าอาจเปลี่ยนแปลงภายในบิลด์ได้ เช่น หากต้องสร้างเป้าหมายสำหรับแพลตฟอร์มอื่นที่ไม่ใช่แพลตฟอร์มของ 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
รายการป้ายกํากับ ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ []
ชุดขั้นต่ำของ constraint_values ที่แพลตฟอร์มเป้าหมายต้องระบุเพื่อให้ตรงกับ config_setting นี้ (ระบบจะไม่พิจารณาแพลตฟอร์มการเรียกใช้) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมที่แพลตฟอร์มมี ดูรายละเอียดได้ที่หัวข้อ แอตทริบิวต์การสร้างที่กำหนดค่าได้
หาก config_setting 2 รายการตรงกับใน select เดียวกัน และอีกรายการหนึ่งมี Flag และ constraint_setting ทั้งหมดเหมือนกับอีกรายการและมากกว่า 1 รายการ ระบบจะเลือกการตั้งค่า 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 -> String; nonconfigurable; ค่าเริ่มต้นคือ {}
เหมือนกับ values แต่ใช้สำหรับ Flag การสร้างที่ผู้ใช้กำหนด
แอตทริบิวต์นี้เป็นแอตทริบิวต์ที่แยกต่างหากเนื่องจากระบบจะอ้างอิง Flag ที่กําหนดโดยผู้ใช้เป็นป้ายกํากับ ขณะที่อ้างอิง Flag ในตัวเป็นสตริงที่กำหนดเอง

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

กรณีพิเศษ

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

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

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

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

เมื่ออ้างอิง 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
รายชื่อชื่อไฟล์ nonconfigurable ต้องระบุ
รายการไฟล์ที่สร้างขึ้นโดยกฎนี้
ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะแปลชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ

หากตั้งค่าแฟล็ก executable ไว้ outs ต้องมีป้ายกำกับเพียง 1 รายการเท่านั้น

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

cmd
สตริง ค่าเริ่มต้นคือ ""
คำสั่งที่จะเรียกใช้ ขึ้นอยู่กับการแทนที่ $(location) และตัวแปร "Make"

มีการใช้การแทนที่ $(location) รายการแรก โดยแทนที่รายการ $(location label) และ $(locations label) ทั้งหมด (และการสร้างที่คล้ายกันซึ่งใช้ตัวแปรที่เกี่ยวข้อง execpath, execpaths, rootpath และ rootpaths)

ถัดไป ระบบจะขยายตัวแปร"Make" โปรดทราบว่าตัวแปรที่กำหนดไว้ล่วงหน้า $(JAVA), $(JAVAC) และ $(JAVABASE) จะขยายออกภายใต้การกำหนดค่า exec ดังนั้นการเรียกใช้ Java ที่ทำงานเป็นส่วนหนึ่งของขั้นตอนบิลด์จะโหลดไลบรารีที่ใช้ร่วมกันและทรัพยากร Dependency อื่นๆ ได้อย่างถูกต้อง

สุดท้าย ระบบจะเรียกใช้คำสั่งที่ได้โดยใช้เชลล์ Bash หากโค้ดสำหรับออกไม่ใช่ 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 - ละเว้นรายการรีจิสทรีการทำงานอัตโนมัติ

หลังจากการแทนที่ $(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' - ในกรณีที่มีคำสั่งหลายรายการที่คั่นด้วย ; ระบบจะออกทันทีหาก CmdLet ของ Powershell ดำเนินการไม่สำเร็จ แต่การดำเนินการนี้ไม่ใช้ได้กับคำสั่งภายนอก

$PSDefaultParameterValues['*:Encoding'] = 'utf8' - เปลี่ยนการเข้ารหัสเริ่มต้นจาก utf-16 เป็น utf-8

executable
บูลีน ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ False
ประกาศว่าเอาต์พุตเป็นแบบเรียกใช้ได้
การตั้งค่าแฟล็กนี้เป็น "จริง" หมายความว่าเอาต์พุตเป็นไฟล์ปฏิบัติการและเรียกใช้ได้โดยใช้คำสั่ง run ในกรณีนี้ genrule จะต้องสร้างเอาต์พุตเพียงรายการเดียว หากตั้งค่าแอตทริบิวต์นี้ไว้ run จะพยายามเรียกใช้ไฟล์โดยไม่คำนึงถึงเนื้อหา

ระบบไม่รองรับการประกาศข้อมูลที่ต้องพึ่งพาสําหรับไฟล์ปฏิบัติการที่สร้างขึ้น

local
บูลีน ค่าเริ่มต้นคือ False

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

ซึ่งเท่ากับการระบุ "local" เป็นแท็ก (tags=["local"])

message
สตริง ค่าเริ่มต้นคือ ""
ข้อความความคืบหน้า
ข้อความความคืบหน้าที่จะพิมพ์เมื่อมีการดำเนินการขั้นตอนบิลด์นี้ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้างเอาต์พุต" (หรือข้อความที่กระอักกระอ่วนพอๆ กัน) แต่คุณระบุข้อความที่เจาะจงมากขึ้นได้ ใช้แอตทริบิวต์นี้แทน echo หรือคำสั่งพิมพ์อื่นๆ ในคำสั่ง cmd เนื่องจากจะช่วยให้เครื่องมือสร้างควบคุมได้ว่าจะให้พิมพ์ข้อความความคืบหน้าดังกล่าวหรือไม่

output_licenses
ประเภทใบอนุญาต ค่าเริ่มต้นคือ ["none"]
ดู common attributes

output_to_bindir
บูลีน ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ False

หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทําให้ระบบเขียนไฟล์เอาต์พุตลงในไดเรกทอรี bin instead of the genfiles directory.

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

ชุดเป้าหมายที่ตัวแปร Make ของ genrule นี้ได้รับอนุญาตให้เข้าถึง หรือเป้าหมาย toolchain_type ที่ genrule นี้จะเข้าถึง

toolchain ที่เข้าถึงผ่าน toolchain_type จะต้องมีผู้ให้บริการ TemplateVariableInfo ด้วย ซึ่งเป้าหมายจะใช้เพื่อเข้าถึงรายละเอียด toolchain ได้

tools
รายการป้ายกํากับ ค่าเริ่มต้นคือ []
รายการการอ้างอิงเครื่องมือสําหรับกฎนี้ ดูข้อมูลเพิ่มเติมได้ที่คำจำกัดความของทรัพยากร 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 โปรโตคอลไบนารีตามที่ระบุไว้ ใน stardoc_output.proto ในซอร์สทรี Bazel
เป้าหมายเอาต์พุตโดยนัย

name.binaryproto (เอาต์พุตเริ่มต้น): ModuleInfo Proto ของไบนารี

name.textproto (จะสร้างขึ้นก็ต่อเมื่อมีการขออย่างชัดเจนเท่านั้น): name.binaryproto เวอร์ชันข้อความ proto

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

คอมโพเนนต์แต่ละรายการของชื่อที่ผ่านการรับรองของเอนทิตีเป็นแบบสาธารณะ (กล่าวคือ อักขระแรกของคอมโพเนนต์แต่ละรายการของชื่อที่ผ่านการรับรองต้องเป็นตัวอักษร ไม่ใช่ "_") และ

อย่างใดอย่างหนึ่งที่รายการ 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 ค่าเริ่มต้นคือ []
รายการแท็กข้อความ เช่น "เล็ก" หรือ "ฐานข้อมูล" หรือ "-ไม่สม่ำเสมอ" แท็กอาจเป็นสตริงใดก็ได้ที่ถูกต้อง
แท็กที่ขึ้นต้นด้วย "-" จะถือว่าเป็นแท็กเชิงลบ ระบบจะไม่ถือว่าอักขระ "-" ที่อยู่ก่อนหน้าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็กชุด "-small" จึงตรงกับขนาด "small" ของการทดสอบ แท็กอื่นๆ ทั้งหมดจะถือว่าเป็นแท็กเชิงบวก

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

เฉพาะกฎการทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและแท็กเชิงลบไม่มีเท่านั้นที่จะรวมอยู่ในชุดทดสอบ โปรดทราบว่านี่ไม่ได้หมายความว่าระบบจะข้ามข้อผิดพลาดในการตรวจสอบทรัพยากร 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

Attributes
`name`	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
`constraint_values`	รายการป้ายกํากับ ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ `[]` ชุดขั้นต่ำของ `constraint_values` ที่แพลตฟอร์มเป้าหมายต้องระบุเพื่อให้ตรงกับ `config_setting` นี้ (ระบบจะไม่พิจารณาแพลตฟอร์มการเรียกใช้) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมที่แพลตฟอร์มมี ดูรายละเอียดได้ที่หัวข้อ แอตทริบิวต์การสร้างที่กำหนดค่าได้ หาก `config_setting` 2 รายการตรงกับใน `select` เดียวกัน และอีกรายการหนึ่งมี Flag และ `constraint_setting` ทั้งหมดเหมือนกับอีกรายการและมากกว่า 1 รายการ ระบบจะเลือกการตั้งค่า 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 -> String; nonconfigurable; ค่าเริ่มต้นคือ `{}` เหมือนกับ `values` แต่ใช้สำหรับ Flag การสร้างที่ผู้ใช้กำหนด แอตทริบิวต์นี้เป็นแอตทริบิวต์ที่แยกต่างหากเนื่องจากระบบจะอ้างอิง Flag ที่กําหนดโดยผู้ใช้เป็นป้ายกํากับ ขณะที่อ้างอิง Flag ในตัวเป็นสตริงที่กำหนดเอง
`values`	พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ `{}` ชุดค่าการกำหนดค่าที่ตรงกับกฎนี้ (แสดงเป็น Flag การสร้าง) กฎนี้จะรับค่ากําหนดของเป้าหมายที่กําหนดค่าไว้ซึ่งอ้างอิงกฎนี้ในคำสั่ง `select` จะถือว่า "จับคู่" การเรียกใช้ Bazel หากการกำหนดค่าสำหรับทุกรายการในพจนานุกรมตรงกับค่าที่คาดไว้ของรายการ ตัวอย่างเช่น `values = {"compilation_mode": "opt"}` จับคู่กับการเรียกใช้ `bazel build --compilation_mode=opt ...` และ `bazel build -c opt ...` ในกฎที่กําหนดค่าเป้าหมาย เพื่อความสะดวก ค่าการกําหนดค่าจะระบุเป็น Flag การสร้าง (โดยไม่มี `"--"` อยู่ข้างหน้า) แต่โปรดทราบว่าทั้ง 2 อย่างนี้ไม่เหมือนกัน เนื่องจากเป้าหมายสามารถสร้างจากการกำหนดค่าหลายรายการภายในบิลด์เดียวกันได้ เช่น "cpu" ของการกำหนดค่า exec ตรงกับค่าของ `--host_cpu` ไม่ใช่ `--cpu` ดังนั้น `config_setting` เดียวกันในอินสแตนซ์ต่างๆ อาจจับคู่กับการเรียกใช้เดียวกันแตกต่างกันไป ทั้งนี้ขึ้นอยู่กับการกําหนดค่าของกฎที่ใช้ `config_setting` หากไม่ได้ตั้งค่า Flag อย่างชัดเจนในบรรทัดคำสั่ง ระบบจะใช้ค่าเริ่มต้นของ Flag นั้น หากคีย์ปรากฏหลายครั้งในพจนานุกรม ระบบจะใช้เฉพาะอินสแตนซ์ล่าสุด หากคีย์อ้างอิงถึง Flag ที่ตั้งค่าได้หลายครั้งในบรรทัดคำสั่ง (เช่น `bazel build --copt=foo --copt=bar --copt=baz ...`) ระบบจะจับคู่ได้หากการตั้งค่ารายการใดรายการหนึ่งตรงกัน

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

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

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