กฎ
ชื่อแทน
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
กฎ alias
จะสร้างอีกชื่อให้กับกฎนั้นๆ
ชื่อแทนจะใช้ได้เฉพาะสำหรับเป้าหมาย "ทั่วไป" เท่านั้น โดยเฉพาะอย่างยิ่ง package_group
และ test_suite
จะใช้ชื่อแทนไม่ได้
กฎของชื่อแทนมีการประกาศระดับการเข้าถึงของตนเอง ในด้านอื่นๆ ทั้งหมด กฎจะทำงานเหมือนกับกฎที่ใช้อ้างอิง (เช่น ระบบจะไม่สนใจการทดสอบในชื่อแทนทดสอบเท่านั้น โดยระบบจะนำกฎที่อ้างอิงมาทดสอบเท่านั้นแทน) โดยมีข้อยกเว้นเล็กน้อย ดังนี้
-
การทดสอบจะไม่ทำงานหากมีการพูดถึงชื่อแทนในบรรทัดคำสั่ง หากต้องการกำหนดชื่อแทนที่เรียกใช้การทดสอบที่อ้างอิง ให้ใช้กฎ
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", ] )ในกรณีเหล่านี้ทั้งหมด การกำหนดค่าจะเปลี่ยนแปลงภายในบิลด์ได้ เช่น ในกรณีที่ต้องสร้างเป้าหมายสำหรับแพลตฟอร์มอื่นที่ต่างจากระดับของแพลตฟอร์ม ซึ่งหมายความว่าแม้ว่า
config_setting
จะไม่ตรงกับแฟล็กบรรทัดคำสั่งระดับบนสุด แต่ก็อาจยังคงตรงกับเป้าหมายของบิลด์บางรายการ
Notes
- ดูการเลือกสำหรับสิ่งที่จะเกิดขึ้นเมื่อ
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
|
constraint_values ขั้นต่ำที่แพลตฟอร์มเป้าหมายต้องระบุเพื่อให้ตรงกับ config_setting นี้ (แพลตฟอร์มการดำเนินการจะไม่พิจารณาที่นี่) ระบบจะไม่สนใจค่าข้อจำกัดเพิ่มเติมใดๆ ที่แพลตฟอร์มไม่สนใจ ดูรายละเอียดได้ที่
แอตทริบิวต์บิลด์ที่กำหนดค่าได้
ในกรณีที่ |
define_values
|
values แต่เฉพาะสำหรับแฟล็ก --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
|
values แต่ใช้กับ
แฟล็กบิลด์ที่กำหนดโดยผู้ใช้
นี่เป็นแอตทริบิวต์ที่แตกต่างกัน เนื่องจากการแจ้งว่าไม่เหมาะสมที่ผู้ใช้กำหนดจะถูกอ้างอิงเป็นป้ายกำกับ ขณะที่แฟล็กในตัวจะอ้างอิงเป็นสตริงที่กำหนดเอง |
values
|
กฎนี้รับการกำหนดค่าของเป้าหมายที่กำหนดค่าไว้ซึ่งอ้างอิงถึงเป้าหมายในคำสั่ง เพื่อความสะดวก ค่าของการกำหนดค่าจะระบุเป็นแฟล็กบิลด์ (โดยไม่มี หากไม่ได้ตั้งค่าสถานะที่บรรทัดคำสั่งอย่างชัดเจน ระบบจะใช้ค่าเริ่มต้น
หากคีย์ปรากฏขึ้นหลายครั้งในพจนานุกรม ระบบจะใช้เฉพาะอินสแตนซ์สุดท้ายเท่านั้น
หากคีย์อ้างอิงถึงแฟล็กที่ตั้งค่าได้หลายครั้งในบรรทัดคำสั่ง (เช่น
|
กลุ่มไฟล์
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, 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 จะเรียงลำดับโดยใช้ --order_output=full
เพื่อบังคับใช้เอาต์พุตตามเชิงกำหนด
ชื่อของไฟล์เอาต์พุตคือชื่อของกฎ
ตัวอย่าง
ตัวอย่างนี้เขียนรายการป้ายกำกับในการปิดทางอ้อมของเป้าหมายที่ระบุไปยังไฟล์
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
อาร์กิวเมนต์
Attributes | |
---|---|
name |
ชื่อที่ไม่ซ้ำกันของเป้าหมายนี้ |
expression
|
:b ในแอตทริบิวต์นี้ในไฟล์ a/BUILD จะหมายถึง //:b เป้าหมาย
|
opts
|
bazel query ได้ ไม่อนุญาตให้ใช้ตัวเลือกการค้นหาบางอย่างที่นี่: --keep_going , --query_file , --universe_scope , --order_results และ --order_output ตัวเลือกที่ไม่ได้ระบุไว้ที่นี่จะมีค่าเริ่มต้นเหมือนกับบรรทัดคำสั่งของ bazel query
|
scope
|
|
strict
|
|
การร่วมเพศ
genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule
จะสร้างไฟล์อย่างน้อย 1 ไฟล์โดยใช้คำสั่ง Bash ที่ผู้ใช้กำหนด
Genrules เป็นกฎบิลด์ทั่วไปที่คุณใช้ได้หากไม่มีกฎที่เจาะจงสําหรับงาน
ตัวอย่างเช่น คุณเรียกใช้ 1 บรรทัดของ Bash ได้ แต่หากต้องการคอมไพล์ไฟล์ C++ ให้ยึดตามกฎ cc_*
ที่มีอยู่ เนื่องจากการดำเนินการที่ยุ่งยากทั้งหมดได้ดำเนินไปเรียบร้อยแล้ว
อย่าใช้ GenRule สำหรับการทดสอบ มีค่าตอบแทนพิเศษสำหรับการทดสอบและผลการทดสอบ รวมถึงนโยบายการแคชและตัวแปรสภาพแวดล้อม โดยทั่วไปแล้ว การทดสอบจะต้องดำเนินการหลังจากที่บิลด์เสร็จสมบูรณ์และในสถาปัตยกรรมเป้าหมาย ในขณะที่ Genrules จะทำงานระหว่างบิลด์และในสถาปัตยกรรมโฮสต์ (ทั้ง 2 แบบอาจแตกต่างกัน) หากต้องการกฎการทดสอบจุดประสงค์ทั่วไป ให้ใช้ sh_test
การพิจารณาการคอมไพล์ข้ามข้อมูล
ดูข้อมูลเพิ่มเติมเกี่ยวกับการคอมไพล์ข้ามได้ในคู่มือผู้ใช้
แม้ว่า Genrules จะทำงานระหว่างบิลด์ แต่เอาต์พุตของโมเดลมักจะใช้หลังจากบิลด์สำหรับการติดตั้งใช้งานหรือทดสอบ ลองพิจารณาตัวอย่างการคอมไพล์โค้ด C สำหรับไมโครคอนโทรลเลอร์ โดยคอมไพเลอร์จะยอมรับซอร์สไฟล์ C และสร้างโค้ดที่ทำงานบนไมโครคอนโทรลเลอร์ แน่นอนว่าโค้ดที่สร้างขึ้นจะไม่สามารถเรียกใช้บน CPU ที่ใช้ในการสร้างโค้ดได้ แต่ตัวคอมไพเลอร์ C (หากคอมไพล์จากซอร์สโค้ด) เองจะต้องทำ
ระบบบิลด์ใช้การกำหนดค่าโฮสต์เพื่ออธิบายเครื่องที่บิลด์ทำงาน และการกำหนดค่าเป้าหมายเพื่ออธิบายเครื่องที่ควรเรียกใช้เอาต์พุตของบิลด์ โดยมีตัวเลือกในการกำหนดค่าเหล่านี้และแยกไฟล์ที่เกี่ยวข้องออกเป็นไดเรกทอรีแยกกันเพื่อหลีกเลี่ยงข้อขัดแย้ง
สำหรับ Genrules ระบบบิลด์จะดูแลให้มีการสร้างทรัพยากร Dependency อย่างเหมาะสม โดยสร้าง srcs
(หากจำเป็น) สำหรับการกำหนดค่าเป้าหมาย, tools
สร้างขึ้นสำหรับการกำหนดค่าโฮสต์ และถือว่าเอาต์พุตสำหรับการกำหนดค่าเป้าหมาย และยังมี
ตัวแปร "Make" ที่คำสั่ง GenRule ส่งผ่านไปยังเครื่องมือที่เกี่ยวข้องได้
กฎเกณฑ์ต้องไม่ได้กำหนดแอตทริบิวต์ deps
โดยกฎอื่นๆ ที่มีมาในตัวจะใช้ข้อมูลเมตาที่อิงตามภาษาซึ่งส่งผ่านระหว่างกฎต่างๆ เพื่อกำหนดวิธีจัดการกฎที่ขึ้นต่อกันโดยอัตโนมัติ แต่ระบบอัตโนมัติระดับนี้ไม่สามารถทำได้สำหรับ Genrules Genrules จะทำงานที่ระดับไฟล์และ Runfile เท่านั้น
กรณีพิเศษ
การคอมไพล์โฮสต์-โฮสต์: ในบางกรณี ระบบบิลด์ต้องเรียกใช้ Genrules เพื่อให้สามารถเรียกใช้เอาต์พุตในระหว่างบิลด์ได้ด้วย ตัวอย่างเช่น หาก GenRule สร้างคอมไพเลอร์ที่กำหนดเองบางรายการ ซึ่งมีการใช้โดยกฎอื่นในภายหลัง กฎแรกจะต้องสร้างเอาต์พุตสำหรับการกำหนดค่าโฮสต์ เพราะนี่คือที่ที่คอมไพเลอร์จะทำงานในอีกรูปแบบหนึ่ง ในกรณีนี้ ระบบบิลด์จะทำสิ่งที่ถูกต้องโดยอัตโนมัติ โดยจะสร้าง srcs
และ outs
ของรุ่นแรกสำหรับการกำหนดค่าโฮสต์แทนการกำหนดค่าเป้าหมาย ดูข้อมูลเพิ่มเติมได้ในคู่มือผู้ใช้
เครื่องมือ JDK และ C++: หากต้องการใช้เครื่องมือจาก JDK หรือชุดคอมไพเลอร์ C++ ระบบบิลด์จะมีชุดตัวแปรที่ใช้ได้ ดูรายละเอียดได้ที่ตัวแปร"ผู้ผลิต"
สภาพแวดล้อมการสร้างกฎ
คำสั่ง genRule จะทำงานโดยเชลล์ Bash ที่กำหนดค่าให้ล้มเหลวเมื่อคำสั่งหรือไปป์ไลน์ล้มเหลวโดยใช้ set -e -o pipefail
เครื่องมือสร้างบิลด์จะเรียกใช้คำสั่ง Bash ในสภาพแวดล้อมกระบวนการที่ปลอดภัยซึ่งกำหนดเฉพาะตัวแปรหลัก เช่น PATH
, PWD
, TMPDIR
และอื่นๆ
ระบบจะไม่ส่งตัวแปรส่วนใหญ่ที่กำหนดในสภาพแวดล้อม Shell ของผู้ใช้ไปยังคำสั่งของ genRule เพื่อให้มั่นใจว่าบิลด์จะทำซ้ำได้ แต่ Bazel (แต่ไม่ใช่ Blaze) จะส่งผ่านค่าตัวแปรสภาพแวดล้อม PATH
ของผู้ใช้
การเปลี่ยนแปลงค่าของ PATH
จะทำให้ Bazel เรียกใช้คำสั่งอีกครั้งในบิลด์ถัดไป
คำสั่ง genRule ไม่ควรเข้าถึงเครือข่าย ยกเว้นเพื่อเชื่อมต่อกระบวนการที่เป็นรายการย่อยของคำสั่งเอง แม้ว่าขณะนี้ยังไม่ได้บังคับใช้ก็ตาม
ระบบบิลด์จะลบไฟล์เอาต์พุตที่มีอยู่โดยอัตโนมัติ แต่จะสร้างไดเรกทอรีระดับบนสุดที่จำเป็นก่อนที่จะเรียกใช้ GenRule นอกจากนี้ยังจะนำไฟล์เอาต์พุตทั้งหมดออกในกรณีที่การทำงานล้มเหลว
คำแนะนำทั่วไป
- ตรวจสอบว่าเครื่องมือที่เรียกใช้โดยกฎเกณฑ์เป็นแบบกำหนดและไม่แบ่งแยก เครื่องมือดังกล่าวไม่ควรเขียนการประทับเวลาลงในเอาต์พุต และควรใช้การจัดลำดับที่เสถียรสำหรับชุดและแผนที่ ตลอดจนเขียนเฉพาะเส้นทางไฟล์สัมพัทธ์ไปยังเอาต์พุต ไม่ใช่เส้นทางสัมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะทำให้เกิดลักษณะการทำงานที่ไม่คาดคิด (Bazel ไม่ได้สร้างกฎเกณฑ์ขึ้นมาใหม่แบบที่คิดไว้) และจะทำให้ประสิทธิภาพของแคชลดลง
- ใช้
$(location)
ให้ครอบคลุมสำหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากการแยกไฟล์เอาต์พุตสำหรับการกำหนดค่าที่แตกต่างกัน ทำให้ Genrules ไม่ต้องใช้เส้นทางแบบฮาร์ดโค้ดและ/หรือเส้นทางแบบสัมบูรณ์ - ควรเขียนมาโคร Starlark ทั่วไปในกรณีที่มีการใช้กฎพื้นฐานเดียวกันหรือคล้ายกันมากในหลายๆ ที่ หากรูปแบบพันธุกรรมซับซ้อน ให้พิจารณานำมาใช้ในสคริปต์หรือใช้เป็นกฎของ Starlark ซึ่งจะช่วยให้อ่านง่ายขึ้นและง่ายขึ้น
- ตรวจสอบว่ารหัสการออกนั้นบ่งบอกถึงความสำเร็จหรือความล้มเหลวของการสร้างกฎอย่างถูกต้อง
- อย่าเขียนข้อความให้ข้อมูลไปยัง stdout หรือ stderr แม้ว่าจะมีประโยชน์สําหรับการแก้ไขข้อบกพร่อง แต่ก็อาจทำให้เกิดสัญญาณรบกวนได้ง่ายๆ การสร้างกฎที่ประสบความสำเร็จไม่ควรเงียบ ในทางกลับกัน การเกิดกฎเกณฑ์ล้มเหลวควรส่งข้อความแสดงข้อผิดพลาดที่ดี
$$
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 จะไม่คัดลอกโครงสร้างไดเรกทอรี/Symlink ที่สร้างโดย genrules และการตรวจสอบทรัพยากร Dependency ของไดเรกทอรีจะไม่เกิดขึ้นจริง
- เมื่ออ้างอิง GenRule ในกฎอื่นๆ คุณจะใช้ป้ายกำกับของ GenRule หรือป้ายกำกับของไฟล์เอาต์พุตแต่ละไฟล์ได้ บางครั้งวิธีหนึ่งเป็นวิธีที่อ่านได้ง่ายกว่า และบางครั้งอาจเป็นการอ้างอิงผลลัพธ์ตามชื่อใน
srcs
ของกฎการบริโภคจะหลีกเลี่ยงการเลือกเอาต์พุตอื่นๆ ของการสร้างกฎโดยไม่ได้ตั้งใจ แต่อาจน่าเบื่อหาก 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
|
ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะตีความชื่อไฟล์เอาต์พุตว่าสัมพันธ์กับแพ็กเกจ
หากตั้งค่าแฟล็ก
คาดว่าคำสั่ง genRule จะสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตำแหน่งที่กำหนดไว้ล่วงหน้า
ตำแหน่งจะใช้ได้ใน |
cmd
|
$(location)
และตัวแปร"ผู้ผลิต"
cmd_bash , cmd_ps และ cmd_bat
หากไม่มีที่เกี่ยวข้อง
หากบรรทัดคำสั่งมีความยาวเกินขีดจำกัดของแพลตฟอร์ม (64, 000 ใน Linux/macOS, 8K ใน Windows) genRule จะเขียนคำสั่งลงในสคริปต์และเรียกใช้สคริปต์นั้นเพื่อแก้ปัญหา การเปลี่ยนแปลงนี้จะมีผลกับแอตทริบิวต์ cmd ทั้งหมด ( |
cmd_bash
|
แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า |
cmd_bat
|
แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า
|
cmd_ps
|
แอตทริบิวต์นี้มีลำดับความสำคัญสูงกว่า
เราเรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่าสภาพแวดล้อมก่อนเรียกใช้คำสั่ง Powershell ในกฎเพื่อทำให้ Powershell ใช้งานได้ง่ายขึ้นและเกิดข้อผิดพลาดน้อยลง
|
exec_tools
|
tools ทุกประการ ยกเว้นว่าจะมีการกำหนดค่าทรัพยากร Dependency เหล่านี้สำหรับแพลตฟอร์มการดำเนินการของกฎแทนการกำหนดค่าโฮสต์
ซึ่งหมายความว่าทรัพยากร Dependency ใน exec_tools จะไม่อยู่ภายใต้ข้อจำกัดเดียวกันกับทรัพยากร Dependency ใน tools กล่าวอย่างเจาะจงคือ ไม่จำเป็นต้องใช้การกำหนดค่าโฮสต์สำหรับทรัพยากร Dependency ชั่วคราวของตนเอง ดูรายละเอียดเพิ่มเติมได้ที่ tools
ทีม Blaze กำลังย้ายข้อมูลการใช้งาน |
executable
|
การตั้งค่าแฟล็กนี้เป็น "จริง" หมายความว่าเอาต์พุตจะเป็นไฟล์ปฏิบัติการและเรียกใช้ได้โดยใช้คำสั่ง ไม่รองรับการประกาศทรัพยากร Dependency สำหรับไฟล์ปฏิบัติการที่สร้างขึ้น |
local
|
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะบังคับให้
ซึ่งเทียบเท่ากับการระบุ "local" เป็นแท็ก ( |
message
|
ข้อความความคืบหน้าที่จะพิมพ์เมื่อดำเนินการขั้นตอนการสร้างนี้ โดยค่าเริ่มต้น ข้อความจะเป็น "กำลังสร้างเอาต์พุต" (หรือรู้สึกเฉยๆ พอๆ กัน) แต่คุณอาจระบุที่เจาะจงมากขึ้นก็ได้ ใช้แอตทริบิวต์นี้แทน |
output_licenses
|
common attributes
|
output_to_bindir
|
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทำให้มีการเขียนไฟล์เอาต์พุตในไดเรกทอรี |
tools
|
ระบบบิลด์ช่วยให้มั่นใจได้ว่าข้อกำหนดเบื้องต้นเหล่านี้สร้างขึ้นก่อนที่จะเรียกใช้คำสั่ง GenRule ซึ่งสร้างขึ้นโดยใช้การกำหนดค่า host เนื่องจากมีการดำเนินการเครื่องมือเหล่านี้เป็นส่วนหนึ่งของบิลด์ คุณจะรับเส้นทางของเป้าหมาย
|
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
|
แท็กที่ขึ้นต้นด้วยอักขระ "-" จะถือว่าเป็นแท็กเชิงลบ อักขระ "-" ที่อยู่ก่อนหน้าไม่ถือว่าเป็นส่วนหนึ่งของแท็ก ดังนั้นแท็ก Suite ที่เป็น "-small" จะตรงกับขนาด "เล็ก" ของการทดสอบ ส่วนแท็กอื่นๆ ทั้งหมดจะถือว่าเป็นแท็กเชิงบวก หากต้องการทำให้แท็กเชิงบวกมีความชัดเจนมากขึ้น แท็กอาจขึ้นต้นด้วยอักขระ "+" ซึ่งจะไม่ได้รับการประเมินในฐานะเป็นส่วนหนึ่งของข้อความของแท็ก แต่เป็นเพียงการทําให้ความแตกต่างในแง่บวกและแง่ลบอ่านได้ง่ายขึ้นเท่านั้น ชุดทดสอบจะรวมเฉพาะกฎทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและไม่มีแท็กเชิงลบเท่านั้น โปรดทราบว่านี่ไม่ได้หมายความว่าการตรวจสอบข้อผิดพลาดสำหรับทรัพยากร Dependency ของการทดสอบที่ถูกกรองออกไปจะถูกข้าม ทรัพยากร Dependency ของการทดสอบที่ข้ามไปแล้วยังคงต้องเป็นไปตามกฎหมาย (เช่น ไม่ถูกบล็อกโดยข้อจำกัดระดับการเข้าถึง)
"การขยายtest_suite" จะดำเนินการด้วยคำสั่ง
โปรดทราบว่า
หากต้องใช้ |
tests
|
สามารถใช้
หากไม่ได้ระบุแอตทริบิวต์ |