กฎ
ชื่อแทน
ดูแหล่งที่มาของกฎ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",
)
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
name |
ชื่อที่ไม่ซ้ํากันสําหรับเป้าหมายนี้ |
actual
|
|
การตั้งค่ากําหนด
ดูแหล่งที่มาของกฎconfig_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
จับคู่สถานะการกําหนดค่าที่คาดไว้ (แสดงเป็นแฟล็กบิวด์หรือข้อจํากัดของแพลตฟอร์ม) เพื่อวัตถุประสงค์ในการเรียกแอตทริบิวต์ที่กําหนดค่าได้ ดูเลือกวิธีใช้งานกฎนี้และ แอตทริบิวต์ที่กําหนดค่าได้สําหรับภาพรวมของฟีเจอร์ทั่วไป
ตัวอย่าง
รายการต่อไปนี้ตรงกับบิลด์ที่กําหนด --compilation_mode=opt หรือ -c opt (อย่างชัดเจนที่บรรทัดคําสั่งหรือโดยปริยายจากไฟล์ .bazelcc)
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 (ทั้งตามอย่างชัดแจ้งในบรรทัดคําสั่งหรือโดยนัยจากไฟล์ .bazelcc)
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 อาจไม่ตรงกับแฟล็กบรรทัดคําสั่งระดับบนสุด แต่ก็อาจยังคงตรงกับเป้าหมายบิลด์บางรายการอยู่
หมายเหตุ
- ดูเลือกสิ่งที่จะเกิดขึ้นเมื่อมี
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จะให้["a", "b"]ตรวจสอบคําจํากัดความของธง และทดสอบเงื่อนไขอย่างละเอียดเพื่อยืนยันความคาดหวังที่แน่นอน - หากต้องการกําหนดเงื่อนไขที่ไม่ได้สร้างโดยแฟล็กบิลด์ในตัว ให้ใช้
แฟล็กที่กําหนดโดย Starlark คุณยังใช้
--defineได้ด้วย แต่ตัวเลือกนี้มีการรองรับที่ไม่รัดกุม เราจึงไม่แนะนํา ดูการสนทนาเพิ่มเติมที่นี่ - หลีกเลี่ยงการแสดงคําจํากัดความ
config_settingที่เหมือนกันในแพ็กเกจอื่น แต่ให้อ้างอิงconfig_settingทั่วไปที่กําหนดไว้ในแพ็กเกจ Canonical แทน - ใช้
values,define_valuesและconstraint_valuesผสมกันในรูปแบบใดก็ได้ในconfig_settingเดียวกัน แต่ต้องตั้งค่าอย่างน้อย 1 รายการสําหรับconfig_settingที่ต้องการ
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
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 เพื่อแสดงตัวอย่างไดเรกทอรีข้อมูลทดสอบ
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",
],
)
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
name |
ชื่อที่ไม่ซ้ํากันสําหรับเป้าหมายนี้ |
srcs
|
โดยทั่วไปแล้ว จะใช้ผลลัพธ์ของนิพจน์ glob กับค่าของแอตทริบิวต์ |
data
|
ระบบจะเพิ่มเป้าหมายที่มีชื่อในแอตทริบิวต์ |
output_group
|
"กลุ่มเอาต์พุต" คือหมวดหมู่ของอาร์ติแฟกต์เอาต์พุตของเป้าหมายตามที่ระบุไว้ในการใช้งานกฎนั้น |
Gengen
ดูแหล่งที่มาของกฎ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 ขั้นตอนนี้คือ 1 เพราะ genquery ต้องใช้ขอบเขตเพื่อป้องกันเป้าหมายภายนอกการปิดแบบปิดของคําค้นหาที่ส่งผลต่อเอาต์พุต และรายการที่ 2 เนื่องจาก BUILD ไฟล์ไม่รองรับทรัพยากร Dependency แบบไวลด์การ์ด (เช่น deps=["//a/..."] ไม่ได้รับอนุญาต)
เอาต์พุตของ Gengen จะสั่งซื้อโดยใช้ --order_output=full เพื่อบังคับใช้เอาต์พุตแบบกําหนดความเชื่อมโยง
ชื่อของไฟล์เอาต์พุตคือชื่อของกฎ
ตัวอย่าง
ตัวอย่างนี้เขียนรายการป้ายกํากับในการปิดแบบชั่วคราวของเป้าหมายที่ระบุไปยังไฟล์
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
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 ที่กําหนดโดยผู้ใช้
กฎทั่วไปเป็นกฎบิลด์ทั่วไปที่คุณสามารถใช้ได้หากไม่มีกฎเฉพาะสําหรับงาน
เช่น คุณอาจเรียกใช้ Bash One-liner แต่หากต้องการรวบรวมไฟล์ C++ โปรดปฏิบัติตามกฎ cc_* ที่มีอยู่ เนื่องจากมีการดําเนินการยกน้ําหนักทั้งหมดสําหรับคุณแล้ว
โปรดทราบว่า Gengen จําเป็นต้องมี Shell เพื่อตีความอาร์กิวเมนต์คําสั่ง นอกจากนี้ยังอ้างอิงโปรแกรมที่กําหนดเองได้ใน PATH อีกด้วย แต่วิธีนี้ทําให้คําสั่งไม่ใช่แบบตามความหมายและอาจทําซ้ําไม่ได้ หากคุณต้องการเรียกใช้เครื่องมือเดียว ให้ลองใช้ run_binary แทน
อย่าใช้กฎการทดสอบ มีการทดสอบสั่งจ่ายและผลการทดสอบเป็นพิเศษ ซึ่งรวมถึงนโยบายการแคชและตัวแปรสภาพแวดล้อม โดยปกติต้องทดสอบหลังจากที่บิลด์เสร็จสมบูรณ์และในสถาปัตยกรรมเป้าหมาย ส่วนกฎทั่วไปจะทํางานระหว่างบิลด์และสถาปัตยกรรม exec (ทั้ง 2 แบบอาจแตกต่างกัน) หากต้องการใช้กฎการทดสอบเพื่อวัตถุประสงค์ทั่วไป ให้ใช้ sh_test
ข้อควรพิจารณาเกี่ยวกับการรวบรวมหลายวิดีโอ
ดูข้อมูลเพิ่มเติมเกี่ยวกับการรวบรวมการรวบรวมได้ในคู่มือผู้ใช้
แม้ว่า Gengen จะทํางานในระหว่างบิลด์ แต่มักจะใช้เอาต์พุตหลังบิลด์เพื่อติดตั้งใช้งานหรือทดสอบ ดูตัวอย่างการคอมไพล์โค้ด C สําหรับไมโครคอนโทรลเลอร์: คอมไพเลอร์ยอมรับไฟล์แหล่งที่มาของ C และสร้างโค้ดที่ทํางานบนไมโครคอนโทรลเลอร์ โค้ดที่สร้างขึ้นมาอย่างชัดเจนจะใช้งานกับ CPU ที่ใช้ในการสร้างไม่ได้ แต่คอมไพเลอร์ C (หากคอมไพล์มาจากต้นทาง) เองก็จะต้องทํา
ระบบบิวด์จะใช้การกําหนดค่า exec เพื่ออธิบายเครื่องที่เรียกใช้บิวด์และการกําหนดค่าเป้าหมายเพื่ออธิบายเครื่องที่เอาต์พุตของบิวด์ควรทํางาน เพราะมีตัวเลือกในการกําหนดค่าแต่ละรายการเหล่านี้และแยกไฟล์ที่เกี่ยวข้องไปยังไดเรกทอรีแยกต่างหากเพื่อหลีกเลี่ยงข้อขัดแย้ง
สําหรับ Gengen, ระบบบิลด์จะตรวจสอบว่าทรัพยากร Dependency สร้างขึ้นอย่างถูกต้อง
srcs สร้างขึ้น (หากจําเป็น) สําหรับการกําหนดค่า target,
tools สร้างขึ้นสําหรับการกําหนดค่า exec และจะถือว่าเอาต์พุตเป็นของการกําหนดค่า target และยังมี
ตัวแปร "สร้าง" ที่คําสั่ง Gengen สามารถส่งผ่านไปยังเครื่องมือที่เกี่ยวข้องได้ด้วย
โดยตั้งใจว่ากฎที่ระบุไม่มีแอตทริบิวต์ deps กล่าวคือ กฎในตัวอื่นๆ จะใช้ข้อมูลเมตาที่ขึ้นอยู่กับภาษาซึ่งส่งระหว่างกฎเพื่อกําหนดวิธีจัดการกฎที่ต้องพึ่งพาโดยอัตโนมัติ แต่ระบบอัตโนมัติระดับนี้ไม่สามารถบังคับใช้กับกฎทั่วไปได้ กฎทั่วไปจะทํางานที่ระดับไฟล์และการเรียกใช้ไฟล์เท่านั้น
กรณีพิเศษ
การรวบรวมคลิปสําหรับการดําเนินการ: ในบางกรณี ระบบการสร้างต้องเรียกใช้ Gengen ซึ่งทําให้เรียกใช้เอาต์พุตระหว่างบิลด์ได้ด้วย เช่น ระหว่างที่ Gengen สร้างคอมไพเลอร์ที่กําหนดเอง ซึ่งใช้กันต่อไปใน Gengen อื่น ข้อมูลโค้ดแรกจะต้องสร้างเอาต์พุตของการกําหนดค่า exec เพราะเป็นที่คอมไพเลอร์จะทํางานใน genrule อื่น ในกรณีนี้ ระบบบิวด์จะทําสิ่งที่ถูกต้องโดยอัตโนมัติ กล่าวคือจะสร้าง srcs และ outs ของกฎแรกสําหรับการกําหนดค่า exec แทนที่จะเป็นการกําหนดค่าเป้าหมาย ดูข้อมูลเพิ่มเติมที่คู่มือผู้ใช้
เครื่องมือ JDK และ C++: สําหรับการใช้เครื่องมือจาก JDK หรือชุดคอมไพเลอร์ C++ ระบบบิวด์จะมีชุดตัวแปรที่ใช้งานได้ ดูรายละเอียดได้ที่ตัวแปร"สร้าง"
สภาพแวดล้อม Genrule
คําสั่ง Genrule จะดําเนินการโดย Shell ของ Bash ที่กําหนดค่าแล้วไม่สําเร็จเมื่อคําสั่งหรือไปป์ไลน์ล้มเหลว โดยใช้ set -e -o pipefail
เครื่องมือบิลด์จะเรียกใช้คําสั่ง Bash ในสภาพแวดล้อมการประมวลผลแบบสุขาภิบาลที่กําหนดเฉพาะตัวแปรหลัก เช่น PATH, PWD, TMPDIR และอีก 2-3 ตัว
ระบบจะไม่ส่งตัวแปรส่วนใหญ่ที่กําหนดไว้ในสภาพแวดล้อม Shell ของผู้ใช้ไปยังคําสั่งของกฎเพื่อให้แน่ใจว่าบิลด์ทําซ้ําได้ แต่ Bazel (แต่ไม่ใช่ Blaze) จะส่งผ่านค่าของตัวแปรสภาพแวดล้อม PATH ของผู้ใช้
การเปลี่ยนแปลงใดๆ กับค่าของ PATH จะทําให้ Bazel เรียกใช้คําสั่งอีกครั้งในบิลด์ถัดไป
คําสั่งพันธุกรรมไม่ควรเข้าถึงเครือข่าย ยกเว้นการเชื่อมต่อกระบวนการที่เป็นตัวย่อยของคําสั่งเอง แม้ว่าปัจจุบันจะยังไม่ได้บังคับใช้
ระบบบิลด์จะลบไฟล์เอาต์พุตที่มีอยู่โดยอัตโนมัติ แต่จะสร้างไดเรกทอรีหลักที่จําเป็นก่อนเรียกใช้ Gengen และยังนําไฟล์เอาต์พุตออกในกรณีที่เกิดข้อผิดพลาดด้วย
คําแนะนําทั่วไป
- ตรวจสอบว่าเครื่องมือที่ดําเนินการโดยพันธุกรรมมีคําจํากัดความที่ชัดเจนและชัดเจน ไม่ควรเขียนการประทับเวลาไปยังเอาต์พุต และควรใช้การจัดลําดับแบบคงที่สําหรับชุดและแผนที่ ตลอดจนเขียนเฉพาะเส้นทางของไฟล์ที่เกี่ยวข้องไปยังเอาต์พุตเท่านั้น ไม่มีเส้นทางสมบูรณ์ การไม่ปฏิบัติตามกฎนี้จะทําให้เกิดลักษณะการทํางานที่ไม่คาดคิดโดยไม่คาดคิด (Bazel ไม่ได้สร้าง Gengen ที่คุณคิดว่าจะทําใหม่) และลดประสิทธิภาพของแคช
- ใช้
$(location)อย่างครอบคลุมสําหรับเอาต์พุต เครื่องมือ และแหล่งที่มา เนื่องจากการแยกไฟล์เอาต์พุตสําหรับการกําหนดค่าที่แตกต่างกัน กฎ จึงไม่สามารถอาศัยเส้นทางฮาร์ดโค้ดและ/หรือเส้นทางสัมบูรณ์ได้ - เขียนมาโคร Starlark ทั่วไปในกรณีที่มีการใช้พันธุเดียวกันหรือคล้ายกันมากในหลายที่ หากพันธุกรรมมีความซับซ้อน ให้พิจารณาใช้พันธุกรรมในสคริปต์หรือเป็นกฎ Starlark ซึ่งจะช่วยปรับปรุงความสามารถในการอ่านและการทดสอบ
- โปรดตรวจสอบว่ารหัสการออกมีการระบุสําเร็จหรือล้มเหลวของ Gengen
- อย่าเขียนข้อความให้ข้อมูลถึง stdout หรือ derder แม้ว่าจะเป็นประโยชน์สําหรับการแก้ไขข้อบกพร่อง แต่ก็อาจทําให้เกิดเสียงรบกวนได้โดยง่าย ในทางกลับกัน กฎที่ล้มเหลวจะปล่อยข้อความแสดงข้อผิดพลาดที่ดี
$$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 ของไดเรกทอรีคือไม่มีเสียง
- เมื่ออ้างอิง Gengen ในกฎอื่นๆ คุณจะใช้ป้ายกํากับของ Gengen หรือป้ายกํากับของไฟล์เอาต์พุตแต่ละไฟล์ บางครั้งวิธีหนึ่งก็อ่านง่ายกว่ากัน แต่บางครั้งวิธีอ้างอิงอื่นๆ เช่น การอ้างอิงเอาต์พุตตามชื่อใน
srcsของกฎการบริโภคเพื่อหลีกเลี่ยงการรับเอาต์พุตอื่นๆ ของพันธุกรรมโดยไม่ตั้งใจ
ตัวอย่าง
ตัวอย่างนี้สร้าง foo.h ไม่มีแหล่งที่มาเนื่องจากคําสั่งดังกล่าวไม่ได้ใช้อินพุตใดๆ "ไบนารี" ที่เรียกใช้โดยคําสั่งคือสคริปต์ Perl ในแพ็กเกจเดียวกับ Gengen
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) > $@",
)
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
name |
ชื่อที่ไม่ซ้ํากันสําหรับเป้าหมายนี้ คุณอาจอ้างอิงกฎนี้ตามชื่อในส่วน srcs หรือ deps ของกฎ BUILD อื่นๆ หากกฎสร้างไฟล์ต้นฉบับ คุณควรใช้แอตทริบิวต์ srcs
|
srcs
|
แอตทริบิวต์นี้ไม่เหมาะที่จะแสดงเครื่องมือที่
ระบบการสร้างบิลด์นี้จะช่วยสร้างข้อกําหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้คําสั่ง genrule สร้างขึ้นโดยใช้การกําหนดค่าเดียวกับคําขอบิวด์เดิม ชื่อไฟล์ข้อกําหนดเบื้องต้นเหล่านี้พร้อมใช้งานกับคําสั่งเป็นรายการพื้นที่ทํางานที่คั่นด้วยคอมมาใน |
outs
|
ไฟล์เอาต์พุตต้องไม่ข้ามขอบเขตของแพ็กเกจ ระบบจะตีความชื่อไฟล์เอาต์พุตว่าเกี่ยวข้องกับแพ็กเกจ
หากตั้งค่าแฟล็ก
คุณควรใช้คําสั่ง Gerule ในการสร้างไฟล์เอาต์พุตแต่ละไฟล์ในตําแหน่งที่กําหนดไว้ล่วงหน้า
สถานที่อยู่ใน |
cmd
|
$(location)
และ ตัวแปร"ผลิต"
cmd_bash, cmd_ps และ cmd_bat
หากไม่มีรายการที่เกี่ยวข้อง
หากความยาวบรรทัดคําสั่งเกินขีดจํากัดของแพลตฟอร์ม (64, 000 ใน Linux/macOS, 8K ใน Windows) Gengen จะเขียนคําสั่งไปยังสคริปต์และเรียกใช้สคริปต์นั้นเพื่อให้แก้ปัญหา ข้อกําหนดนี้มีผลกับแอตทริบิวต์ cmd ทั้งหมด ( |
cmd_bash
|
แอตทริบิวต์นี้มีลําดับความสําคัญสูงกว่า |
cmd_bat
|
แอตทริบิวต์นี้มีลําดับความสําคัญสูงกว่า
|
cmd_ps
|
แอตทริบิวต์นี้มีลําดับความสําคัญสูงกว่า
เราจะเรียกใช้คําสั่งต่อไปนี้เพื่อตั้งค่าสภาพแวดล้อมก่อนเรียกใช้คําสั่ง Powershell ในกฎ เพื่อให้ Powershell ใช้งานง่ายและมีแนวโน้มที่จะเกิดข้อผิดพลาดน้อยลง
|
exec_tools
|
tools แทน
ก่อนหน้านี้ในเวลาที่ |
executable
|
การตั้งค่าแฟล็กนี้เป็น "จริง" หมายความว่าเอาต์พุตเป็นไฟล์ปฏิบัติการและเรียกใช้ได้โดยใช้คําสั่ง ระบบไม่รองรับการประกาศทรัพยากร Dependency ของข้อมูลสําหรับไฟล์ปฏิบัติการที่สร้างขึ้น |
local
|
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะบังคับให้
ซึ่งเทียบเท่ากับการระบุ "local" เป็นแท็ก ( |
message
|
ข้อความความคืบหน้าที่จะพิมพ์ในขณะที่ดําเนินการขั้นตอนการสร้างนี้ โดยค่าเริ่มต้น ข้อความคือ "การสร้างเอาต์พุต" (หรือบางอย่างที่มีความหมายเท่าๆ กัน) แต่คุณอาจระบุหรือไม่ก็ได้ ใช้แอตทริบิวต์นี้แทน |
output_licenses
|
common attributes
|
output_to_bindir
|
หากตั้งค่าเป็น "จริง" ตัวเลือกนี้จะทําให้เขียนไฟล์เอาต์พุตลงในไดเรกทอรี |
tools
|
ระบบการสร้างบิลด์จะตรวจสอบว่ามีข้อกําหนดเบื้องต้นเหล่านี้ก่อนเรียกใช้คําสั่ง genrule สร้างขึ้นโดยใช้การกําหนดค่า exec เนื่องจากเครื่องมือเหล่านี้ทํางานเป็นส่วนหนึ่งของบิลด์ เส้นทางของเป้าหมาย
|
กลุ่มทดสอบ
ดูแหล่งที่มาของกฎ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"],
)
อาร์กิวเมนต์
| แอตทริบิวต์ | |
|---|---|
name |
ชื่อที่ไม่ซ้ํากันสําหรับเป้าหมายนี้ |
tags
|
แท็กที่เริ่มต้นด้วยอักขระ "-" จะถือว่าเป็นแท็กเชิงลบ ระบบจะไม่พิจารณาอักขระ "-" ที่อยู่ก่อนหน้า แท็กอื่นๆ ทั้งหมดจะถือว่าเป็นแท็กเชิงบวก (ไม่บังคับ) เพื่อให้แท็กเชิงบวกมีความชัดเจนยิ่งขึ้น แท็กอาจขึ้นต้นด้วยอักขระ "+" จะไม่ได้รับการประเมินเป็นส่วนหนึ่งของข้อความของแท็ก เพียงแต่ช่วยให้ความแตกต่างในเชิงบวกและเชิงลบนั้นอ่านง่ายขึ้น มีเพียงชุดทดสอบที่ตรงกับแท็กเชิงบวกทั้งหมดและแท็กเชิงลบทั้งหมดเท่านั้นที่จะรวมอยู่ในชุดทดสอบ ทั้งนี้ไม่ได้หมายความว่าการตรวจสอบข้อผิดพลาดเกี่ยวกับทรัพยากร Dependency ในการทดสอบที่กรองออกจะข้ามทรัพยากร Dependency ในการทดสอบที่ข้ามไปไปจะยังคงถูกต้องตามกฎหมาย (เช่น ไม่ได้ถูกบล็อกโดยข้อจํากัดระดับการเข้าถึง)
โปรดทราบว่า
หากต้องการใช้ |
tests
|
หากไม่ระบุแอตทริบิวต์ |