กฎ
ชื่อแทน
ดูแหล่งที่มาของกฎ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 นี้ (ไม่พิจารณาแพลตฟอร์มการดำเนินการที่นี่) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมที่แพลตฟอร์มถูกละเว้น ดูรายละเอียดได้ที่
แอตทริบิวต์บิลด์ที่กำหนดค่าได้
ในกรณีที่ |
define_values
|
พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ values แต่มีไว้สำหรับ Flag --define โดยเฉพาะ
ซึ่งหมายความว่า config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) ไม่ทำงานเนื่องจากคีย์เดียวกัน ( config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) จับคู่
|
flag_values
|
พจนานุกรม: label -> สตริง nonconfigurable ค่าเริ่มต้นคือ values แต่มีไว้สำหรับ
แฟล็กบิลด์ที่ผู้ใช้กำหนด
แอตทริบิวต์นี้เป็นแอตทริบิวต์ที่แตกต่างกันเนื่องจากมีการอ้างอิง Flag ที่กำหนดโดยผู้ใช้ว่าเป็นป้ายกำกับ แต่จะมีการอ้างอิงแฟล็กในตัวเป็นสตริงที่กำหนดเอง |
values
|
พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ กฎนี้รับการกำหนดค่าของเป้าหมายที่กำหนดค่าไว้ซึ่งอ้างอิงถึงเป้าหมายในคำสั่ง เพื่อความสะดวก ค่าของการกำหนดค่าจะระบุเป็นแฟล็กบิลด์ (โดยไม่มี หากไม่ได้ตั้งค่า Flag อย่างชัดเจนที่บรรทัดคำสั่ง ระบบจะใช้ค่าเริ่มต้น
หากคีย์ปรากฏในพจนานุกรมหลายครั้ง ระบบจะใช้เฉพาะอินสแตนซ์ล่าสุดเท่านั้น
หากคีย์อ้างอิงถึงแฟล็กที่ตั้งค่าได้หลายครั้งในบรรทัดคำสั่ง (เช่น
|
กลุ่มไฟล์
ดูแหล่งที่มาของกฎ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 สําหรับค่าของแอตทริบิวต์ |
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()
จะเรียกใช้การค้นหาที่ระบุในภาษาการค้นหาของ 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
|
บูลีน ค่าเริ่มต้นคือ True เอาต์พุตคำค้นหาจะเขียนในรูปแบบไฟล์ GZIP การตั้งค่านี้ใช้เพื่อหลีกเลี่ยงการเพิ่มขึ้นอย่างรวดเร็วในการใช้หน่วยความจำของ Bazel เมื่อคาดว่าเอาต์พุตการค้นหาจะมีขนาดใหญ่ Bazel บีบอัดเอาต์พุตการค้นหาที่มีขนาดใหญ่กว่า 220 ไบต์ภายในอยู่แล้ว โดยไม่คำนึงถึงค่าของการตั้งค่านี้ ดังนั้นการตั้งค่านี้เป็น 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
|
บูลีน ค่าเริ่มต้นคือ |
Genrule
ดูแหล่งที่มาของกฎgenrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule
จะสร้างไฟล์อย่างน้อย 1 ไฟล์โดยใช้คำสั่ง Bash ที่ผู้ใช้กำหนด
กฎการสร้างคือกฎการสร้างทั่วไปที่คุณใช้ได้หากไม่มีกฎที่เจาะจงสำหรับงานนั้น
ตัวอย่างเช่น คุณสามารถใช้งาน Bash หนึ่งบรรทัด อย่างไรก็ตาม หากจำเป็นต้องคอมไพล์ไฟล์ C++ ให้ใช้กฎ cc_*
ที่มีอยู่ เนื่องจากระบบได้ดำเนินการยกน้ำหนักทั้งหมดให้คุณแล้ว
โปรดทราบว่า genrule ต้องใช้ Shell เพื่อตีความอาร์กิวเมนต์คำสั่ง นอกจากนี้ยังอ้างอิงโปรแกรมที่กำหนดเองที่มีอยู่ใน PATH ได้ง่ายด้วย อย่างไรก็ตาม วิธีนี้ทำให้คำสั่งไม่เจาะจงและอาจทำให้เกิดซ้ำไม่ได้ หากต้องการเรียกใช้เครื่องมือเดียว ให้ลองใช้ run_binary แทน
อย่าใช้ Genrule เพื่อทำการทดสอบ มีค่าตอบแทนพิเศษสำหรับการทดสอบและผลการทดสอบ ซึ่งรวมถึงนโยบายการแคชและตัวแปรสภาพแวดล้อม โดยทั่วไปแล้ว การทดสอบต้องดำเนินการหลังจากที่บิลด์เสร็จสมบูรณ์และในสถาปัตยกรรมเป้าหมายแล้ว ในขณะที่ Genrule จะดำเนินการระหว่างบิลด์และสถาปัตยกรรมผู้บริหาร (ทั้ง 2 เวอร์ชันอาจแตกต่างกัน) หากต้องการกฎการทดสอบสำหรับวัตถุประสงค์ทั่วไป ให้ใช้ sh_test
ข้อควรพิจารณาเกี่ยวกับการรวบรวมคลิป
ดูข้อมูลเพิ่มเติมเกี่ยวกับการคอมไพล์แบบข้ามแพลตฟอร์มได้ที่คู่มือผู้ใช้
แม้ว่า Genrules จะทำงานระหว่างบิลด์ แต่เอาต์พุตมักจะมีการใช้หลังจากบิลด์เพื่อทำให้ใช้งานได้หรือทดสอบ ลองพิจารณาตัวอย่างการคอมไพล์โค้ด C สำหรับไมโครคอนโทรลเลอร์: คอมไพเลอร์จะยอมรับไฟล์ต้นฉบับ C และสร้างโค้ดที่ทำงานบนไมโครคอนโทรลเลอร์ แน่นอนว่าโค้ดที่สร้างขึ้นไม่สามารถทำงานบน CPU ที่ใช้ในการสร้างได้ แต่คอมไพเลอร์ C (หากคอมไพเลอร์จากแหล่งที่มา) จะต้องทำงานนั้นเอง
ระบบบิลด์ใช้การกำหนดค่า exec เพื่ออธิบายเครื่องที่บิลด์นี้ทำงาน และการกำหนดค่าเป้าหมายเพื่ออธิบายเครื่องที่เอาต์พุตของบิลด์ควรทำงาน โดยมอบตัวเลือกในการกำหนดค่าแต่ละไฟล์และแยกไฟล์ที่เกี่ยวข้องออกเป็นไดเรกทอรีแยกกันเพื่อหลีกเลี่ยงข้อขัดแย้ง
สำหรับ Genrule ระบบบิลด์จะตรวจสอบว่าทรัพยากร Dependency สร้างขึ้นอย่างเหมาะสม กล่าวคือมีการสร้าง srcs
(หากจำเป็น) สำหรับการกำหนดค่าเป้าหมาย tools
สร้างขึ้นสำหรับการกำหนดค่า exec และเอาต์พุตจะได้รับการพิจารณาสำหรับการกำหนดค่าเป้าหมาย นอกจากนี้ยังมี
ตัวแปร "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 asls $(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
|
รายการป้ายกำกับ ค่าเริ่มต้นคือ
แอตทริบิวต์นี้ไม่เหมาะสำหรับแสดงรายการเครื่องมือที่ดำเนินการโดย
ระบบบิลด์จะดูแลให้มีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้คำสั่ง genrule ข้อกำหนดดังกล่าวสร้างขึ้นโดยใช้การกำหนดค่าเดียวกันกับคำขอบิลด์ต้นฉบับ ชื่อไฟล์ของข้อกำหนดเบื้องต้นเหล่านี้มีอยู่ในคำสั่งเป็นรายการที่คั่นด้วยช่องว่างใน |
outs
|
รายชื่อชื่อไฟล์ nonconfigurable ต้องระบุ รายการไฟล์ที่กฎนี้สร้างไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะแปลชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ
หากตั้งค่าแฟล็ก
คำสั่ง Genrule ต้องการสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า
ตำแหน่งพร้อมใช้งานใน |
cmd
|
สตริง ค่าเริ่มต้นคือ $(location)
และ ตัวแปร"Make"
cmd_bash , cmd_ps และ cmd_bat
หากไม่มีรายการที่เกี่ยวข้อง
หากบรรทัดคำสั่งยาวเกินขีดจำกัดของแพลตฟอร์ม (64K ใน Linux/macOS, 8K ใน Windows)
Genrule จะเขียนคำสั่งไปยังสคริปต์และเรียกใช้สคริปต์นั้นเพื่อแก้ปัญหา ซึ่งจะมีผลกับแอตทริบิวต์ cmd ทั้งหมด ( |
cmd_bash
|
สตริง ค่าเริ่มต้นคือ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า |
cmd_bat
|
สตริง ค่าเริ่มต้นคือ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า
|
cmd_ps
|
สตริง ค่าเริ่มต้นคือ แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า
เราเรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่าสภาพแวดล้อมก่อนเรียกใช้คำสั่ง Powershell ใน genrule เพื่อให้ Powershell ใช้งานได้ง่ายขึ้นและเกิดข้อผิดพลาดได้ง่ายน้อยลง
|
executable
|
บูลีน nonconfigurable ค่าเริ่มต้นคือ
การตั้งค่าแฟล็กนี้เป็น "จริง" หมายความว่าเอาต์พุตเป็นไฟล์ปฏิบัติการและเรียกใช้ได้โดยใช้คำสั่ง ระบบไม่รองรับการประกาศทรัพยากร Dependency สำหรับไฟล์ปฏิบัติการที่สร้างขึ้น |
local
|
บูลีน ค่าเริ่มต้นคือ
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะบังคับให้
ซึ่งเท่ากับการระบุ "local" เป็นแท็ก ( |
message
|
สตริง ค่าเริ่มต้นคือ
ข้อความความคืบหน้าที่จะพิมพ์เมื่อมีการดำเนินการขั้นตอนบิลด์นี้ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้าง output" (หรืออะไรสักอย่างเท่าๆ กัน) แต่คุณระบุข้อความที่เจาะจงมากกว่านี้ก็ได้ ใช้แอตทริบิวต์นี้แทน |
output_licenses
|
ประเภทใบอนุญาต ค่าเริ่มต้นคือ common attributes
|
output_to_bindir
|
บูลีน nonconfigurable ค่าเริ่มต้นคือ
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทำให้ระบบเขียนไฟล์เอาต์พุตลงในไดเรกทอรี |
tools
|
รายการป้ายกำกับ ค่าเริ่มต้นคือ
ระบบบิลด์จะดูแลให้มีการสร้างข้อกำหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้คำสั่ง Genrule ซึ่งสร้างโดยใช้การกำหนดค่า exec เนื่องจากเครื่องมือเหล่านี้ดำเนินการเป็นส่วนหนึ่งของบิลด์ คุณดูเส้นทางของเป้าหมาย
|
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
|
รายการป้ายกำกับ ค่าเริ่มต้นคือ load() ปรับแต่งโดย src เป้าหมายเหล่านี้ควรอยู่ภายใต้เป้าหมายการใช้งานปกติ
bzl_library แต่กฎ starlark_doc_extract ไม่ได้บังคับใช้เป้าหมายดังกล่าว และยอมรับเป้าหมายที่มีไฟล์ Starlark อยู่ใน DefaultInfo
โปรดทราบว่าไฟล์ Starlark ที่รวมไว้ต้องเป็นไฟล์ในแผนผังต้นทาง โดย Bazel จะ |
src
|
ป้ายกำกับ ต้องระบุ ไฟล์ Starlark ที่จะใช้ดึงข้อมูลเอกสารโปรดทราบว่าไฟล์นี้ต้องเป็นไฟล์ในแผนผังแหล่งที่มา ทั้งนี้ Bazel จะ |
render_main_repo_name
|
บูลีน ค่าเริ่มต้นคือ //foo:bar.bzl เป็น @main_repo_name//foo:bar.bzl )
ชื่อที่ใช้สำหรับที่เก็บหลักมาจาก ควรตั้งค่าแอตทริบิวต์นี้เป็น |
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 ค่าเริ่มต้นคือ แท็กที่ขึ้นต้นด้วย "-" จะถือว่าเป็นแท็กเชิงลบ อักขระ "-" ที่อยู่ก่อนหน้าไม่ถือว่าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็กชุด "-ขนาดเล็ก" จะตรงกับขนาด "เล็ก" ของการทดสอบ ส่วนแท็กอื่นๆ ทั้งหมดจะถือเป็นแท็กเชิงบวก หากต้องการให้แท็กเชิงบวกมีความชัดเจนมากขึ้น แท็กอาจขึ้นต้นด้วยอักขระ "+" ซึ่งระบบจะไม่ประเมินเป็นส่วนหนึ่งของข้อความของแท็ก เพียงแต่ทำให้อ่านความแตกต่างด้านบวกและด้านลบได้ง่ายขึ้น ชุดทดสอบจะรวมเฉพาะกฎทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและไม่มีแท็กใดแท็กหนึ่งเท่านั้น โปรดทราบว่านี่ไม่ได้หมายความว่าระบบจะข้ามข้อผิดพลาดในการตรวจสอบทรัพยากร Dependency ในการทดสอบที่ถูกกรองออก แต่ทรัพยากร Dependency ในการทดสอบที่ถูกข้ามยังคงต้องเป็นข้อมูลทางกฎหมาย (เช่น ไม่ได้ถูกบล็อกโดยข้อจํากัดระดับการมองเห็น)
ระบบจะจัดการกับคีย์เวิร์ดของแท็ก
โปรดทราบว่า
หากต้องการใช้ |
tests
|
รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ
โดยยอมรับ
หากไม่ได้ระบุหรือเว้นว่างแอตทริบิวต์ |