ซึ่งมักเกิดขึ้นที่การดำเนินการจำเป็นต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจากทรัพยากร Dependency แบบสกรรม ตัวอย่างเช่น บรรทัดคำสั่ง Linker อาจแสดงไฟล์ออบเจ็กต์ทุกไฟล์ที่จำเป็นสำหรับไลบรารีทั้งหมดที่ลิงก์อยู่ แนวทางปฏิบัติแนะนําคือการจัดเก็บข้อมูลสกรรมกริยาดังกล่าวใน depset
เพื่อให้แชร์กับหลายเป้าหมายได้ อย่างไรก็ตาม ถ้าผู้เขียนกฎต้องแปลงหน่วยต่างๆ เหล่านี้เป็นรายการสตริงเพื่อสร้างบรรทัดคำสั่งการดำเนินการ ก็อาจทำให้การเพิ่มประสิทธิภาพการแชร์หน่วยความจำนี้ไม่ชนะ
ด้วยเหตุนี้ ฟังก์ชันการสร้างการดำเนินการจึงยอมรับออบเจ็กต์ Args
รายการเพิ่มเติมจากสตริง ออบเจ็กต์ Args
แต่ละรายการแสดงถึงการต่อสตริงและ Depset เข้าด้วยกัน พร้อมการเปลี่ยนรูปแบบที่ไม่บังคับสําหรับการจัดการข้อมูล ออบเจ็กต์ Args
ไม่ประมวลผลดีพเซ็ตที่ห่อหุ้มไว้จนกว่าจะถึงระยะการดำเนินการ เมื่อถึงเวลาคำนวณบรรทัดคำสั่ง ซึ่งจะช่วยเลื่อนการคัดลอกราคาแพงออกไปจนกว่าจะเสร็จสิ้นระยะการวิเคราะห์ โปรดดูข้อมูลเพิ่มเติมในหน้าการเพิ่มประสิทธิภาพ
Args
สร้างขึ้นโดยการเรียก ctx.actions.args()
ซึ่งสามารถส่งผ่านเป็นพารามิเตอร์ arguments
ของ ctx.actions.run()
หรือ ctx.actions.run_shell()
การกลายพันธุ์แต่ละรายการของออบเจ็กต์ Args
จะเพิ่มค่าต่อท้ายบรรทัดคำสั่งในตอนท้าย
ฟีเจอร์ map_each
ให้คุณปรับแต่งวิธีเปลี่ยนรูปแบบรายการเป็นสตริงได้ หากคุณไม่ระบุฟังก์ชัน map_each
จำนวน Conversion มาตรฐานจะเป็นดังนี้
- ค่าที่เป็นสตริงอยู่แล้วจะปล่อยไว้ตามเดิม
- ออบเจ็กต์
File
รายการได้เปลี่ยนเป็นค่าFile.path
- ส่วนประเภทอื่นๆ ทั้งหมดจะเปลี่ยนเป็นสตริงในลักษณะที่ไม่ระบุ ด้วยเหตุนี้ คุณจึงควรหลีกเลี่ยงการส่งค่าที่ไม่ใช่สตริงหรือประเภท
File
ไปยังadd()
และหากส่งค่าดังกล่าวไปยังadd_all()
หรือadd_joined()
คุณควรระบุฟังก์ชันmap_each
เมื่อใช้การจัดรูปแบบสตริง (format
, format_each
และพารามิเตอร์ format_joined
ของเมธอด add*()
) ระบบจะตีความเทมเพลตรูปแบบในลักษณะเดียวกันกับการแทนที่ %
ในสตริง ยกเว้นว่าเทมเพลตต้องมีตัวยึดตำแหน่งที่ใช้แทน 1 รายการและต้องเป็น %s
ใช้อักขระหลีกกับเปอร์เซ็นต์ลิตรที่เป็น %%
ได้ ระบบจะใช้การจัดรูปแบบหลังจากแปลงค่าเป็นสตริงตามด้านบน
เมธอด add*()
แต่ละเมธอดมีแบบฟอร์มทางเลือกที่ยอมรับพารามิเตอร์ตําแหน่งเพิ่มเติม ซึ่งก็คือสตริง "ชื่ออาร์กิวเมนต์" ที่จะแทรกก่อนอาร์กิวเมนต์ที่เหลือ สำหรับ add_all
และ add_joined
ระบบจะไม่เพิ่มสตริงที่เกินมาหากลำดับว่างเปล่า ตัวอย่างเช่น การใช้งานเดียวกันอาจเพิ่ม --foo val1 val2 val3 --bar
หรือเพียง --bar
ลงในบรรทัดคำสั่งก็ได้ ทั้งนี้ขึ้นอยู่กับว่าลำดับที่ระบุมี val1..val3
หรือว่างเปล่า
หากขนาดของบรรทัดคำสั่งอาจยาวกว่าขนาดสูงสุดที่ระบบอนุญาต อาร์กิวเมนต์อาจถูกแบ่งออกเป็นไฟล์พารามิเตอร์ได้ โปรดดู use_param_file()
และ set_param_file_format()
ตัวอย่างเช่น สมมติว่าเราต้องการสร้างบรรทัดคำสั่ง
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --bazเราสามารถใช้ออบเจ็กต์
Args
ต่อไปนี้ # foo_deps and bar_deps are depsets containing # File objects for the foo and bar .txt files. args = ctx.actions.args() args.add_all("--foo", foo_deps) args.add_joined("--bar", bar_deps, join_with=",") args.add("--baz") ctx.actions.run( ... arguments = [args], ... )
สมาชิก
เพิ่ม
Args Args.add(arg_name_or_value, value=unbound, *, format=None)เพิ่มอาร์กิวเมนต์ต่อท้ายบรรทัดคำสั่งนี้
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
arg_name_or_value
|
ต้องระบุ หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อนค่าโดยไม่มีการประมวลผลใดๆ หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น value (ดูด้านล่าง)
|
value
|
default = unbound ออบเจ็กต์ที่จะต่อท้าย ซึ่งจะแปลงเป็นสตริงโดยใช้ Conversion มาตรฐานที่กล่าวถึงข้างต้น เนื่องจากไม่มีพารามิเตอร์ map_each สำหรับฟังก์ชันนี้ value จึงควรเป็นสตริงหรือ File ต้องส่งรายการ, Tuple, Depset หรือไดเรกทอรี File ไปยัง add_all() หรือ add_joined() แทนเมธอดนี้
|
format
|
string; or None ; ค่าเริ่มต้น = ไม่มีรูปแบบสตริงที่จะนำไปใช้กับเวอร์ชันสตริงของ value
|
add_all
Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)เพิ่มอาร์กิวเมนต์หลายตัวต่อท้ายบรรทัดคำสั่งนี้ ระบบจะประมวลผลสินค้าอย่างช้าๆ ในระหว่างขั้นตอนการดำเนินการ
การประมวลผลส่วนใหญ่จะเกิดขึ้นในรายการของอาร์กิวเมนต์ที่จะเพิ่มต่อท้าย ตามขั้นตอนต่อไปนี้
- แต่ละรายการในไดเรกทอรี
File
จะถูกแทนที่ด้วยFile
ทั้งหมดที่มีอยู่ในไดเรกทอรีนั้นซ้ำๆ - หากระบุ
map_each
ค่านี้จะมีผลกับแต่ละรายการ และรายการสตริงที่เป็นผลลัพธ์จะต่อกันเพื่อสร้างรายการอาร์กิวเมนต์เริ่มต้น มิเช่นนั้น รายการอาร์กิวเมนต์เริ่มต้นจะเป็นผลลัพธ์ของการใช้ Conversion มาตรฐานกับแต่ละรายการ - อาร์กิวเมนต์แต่ละรายการในรายการจะอยู่ในรูปแบบ
format_each
หากมี - หาก
uniquify
เป็นจริง ระบบจะนำอาร์กิวเมนต์ที่ซ้ำกันออก สิ่งที่เกิดขึ้นครั้งแรกเป็นสิ่งที่เกิดขึ้นต่อไปได้ - หากระบุสตริง
before_each
ระบบจะแทรกสตริงนี้เป็นอาร์กิวเมนต์ใหม่ก่อนอาร์กิวเมนต์ที่มีอยู่แต่ละรายการในรายการ วิธีนี้จะเพิ่มจำนวนอาร์กิวเมนต์ที่จะต่อท้ายในจุดนี้เป็น 2 เท่าได้อย่างมีประสิทธิภาพ - ยกเว้นในกรณีที่รายการว่างเปล่าและ
omit_if_empty
เป็นจริง (ค่าเริ่มต้น) ระบบจะแทรกชื่ออาร์กิวเมนต์และterminate_with
เป็นอาร์กิวเมนต์แรกและอาร์กิวเมนต์สุดท้ายตามลำดับ หากมีการระบุไว้
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
arg_name_or_values
|
ต้องระบุ หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ไว้ก่อน values โดยไม่ต้องประมวลผล ระบบจะไม่เพิ่มชื่ออาร์กิวเมนต์นี้หาก omit_if_empty เป็น true (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือระบบจะกรองรายการทั้งหมด) หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
|
values
|
sequence; or depset ; ค่าเริ่มต้น = ไม่มีการเชื่อมโยงรายการ, กลุ่ม Tuple หรือ Depset ที่จะผนวกรายการ |
map_each
|
callable; or None ; ค่าเริ่มต้น = ไม่มีฟังก์ชันที่แปลงแต่ละรายการเป็นสตริงหรือสตริงมากกว่า 1 รายการ ซึ่งอาจมีการประมวลผลเพิ่มเติมก่อนที่จะต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน ฟังก์ชันจะส่งอาร์กิวเมนต์ตำแหน่ง 1 หรือ 2 อาร์กิวเมนต์ คือ รายการที่จะแปลง ตามด้วย ประเภทของค่าการแสดงผลจะขึ้นอยู่กับจำนวนอาร์กิวเมนต์ที่จะสร้างสำหรับรายการ ดังนี้
None มีผลเหมือนกับการแสดงผลรายการความยาว 1 หรือความยาว 0 ตามลำดับ อย่างไรก็ตาม วิธีนี้จะมีประสิทธิภาพและอ่านได้ง่ายกว่าเพื่อหลีกเลี่ยงการสร้างรายการที่ไม่จำเป็นโดยปกติแล้ว รายการที่เป็นไดเรกทอรีจะขยายไปยังเนื้อหาโดยอัตโนมัติเมื่อตั้งค่า เพื่อหลีกเลี่ยงการเก็บรักษาโครงสร้างข้อมูลขนาดใหญ่จากระยะการวิเคราะห์ไปยังระยะดำเนินการโดยไม่ได้ตั้งใจ จะต้องประกาศฟังก์ชัน คำเตือน: คำสั่ง |
format_each
|
string; or None ; ค่าเริ่มต้น = ไม่มีรูปแบบสตริงที่ไม่บังคับซึ่งใช้กับแต่ละสตริงที่แสดงผลโดยฟังก์ชัน map_each สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ
|
before_each
|
string; or None ;
default = ไม่มีสตริงที่ไม่บังคับซึ่งควรต่อท้ายก่อนอาร์กิวเมนต์แต่ละรายการที่ได้จาก values จะต่อท้าย
|
omit_if_empty
|
ค่าเริ่มต้น = True หากเป็น "จริง" หากไม่มีอาร์กิวเมนต์ที่ได้จาก values มาต่อท้าย ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง หากเป็น "เท็จ" ชื่ออาร์กิวเมนต์และ terminate_with (หากมี) จะยังคงต่อท้ายอยู่ไม่ว่าจะมีอาร์กิวเมนต์อื่นๆ หรือไม่ก็ตาม
|
uniquify
|
default = False หากเป็น true อาร์กิวเมนต์ที่ซ้ำกันซึ่งได้มาจาก values จะถูกละเว้น เฉพาะรายการแรกของอาร์กิวเมนต์แต่ละรายการเท่านั้นที่จะยังคงอยู่ โดยปกติแล้วจะไม่จำเป็นต้องใช้ฟีเจอร์นี้ เนื่องจาก Depset จะตัดรายการที่ซ้ำออกไปอยู่แล้ว แต่การดำเนินการนี้จะมีประโยชน์หาก map_each ปล่อยสตริงเดียวกันสำหรับหลายรายการ
|
expand_directories
|
default = True หากเป็น "จริง" ระบบจะขยายไดเรกทอรีใน values เป็นรายการไฟล์แบบรวม ซึ่งจะเกิดขึ้นก่อนที่ map_each จะมีผล
|
terminate_with
|
string; or None ;
default = ไม่มีสตริงที่ไม่บังคับซึ่งต่อท้ายอาร์กิวเมนต์อื่นๆ ทั้งหมด ระบบจะไม่เพิ่มสตริงนี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือระบบจะกรองรายการทั้งหมด)
|
allow_closure
|
ค่าเริ่มต้น = เท็จ หากเป็น "จริง" อนุญาตให้ใช้การปิดในพารามิเตอร์ฟังก์ชัน เช่น map_each โดยทั่วไปแล้วการดำเนินการนี้จะไม่จำเป็นและอาจมีความเสี่ยงที่จะเก็บรักษาโครงสร้างข้อมูลระยะวิเคราะห์ขนาดใหญ่ไว้ในระยะดำเนินการ
|
add_joined
Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)เพิ่มอาร์กิวเมนต์ต่อท้ายบรรทัดคำสั่งนี้โดยการนำค่าหลายค่ามาต่อกันโดยใช้ตัวคั่น ระบบจะประมวลผลสินค้าอย่างช้าๆ ในระหว่างขั้นตอนการดำเนินการ
การประมวลผลจะคล้ายกับ add_all()
แต่ระบบจะรวมรายการอาร์กิวเมนต์ที่มาจาก values
เป็นอาร์กิวเมนต์เดียวเสมือนกับ join_with.join(...)
จากนั้นจะจัดรูปแบบโดยใช้เทมเพลตสตริง format_joined
ที่ระบุ สิ่งที่ต่างจาก add_all()
คือจะไม่มีพารามิเตอร์ before_each
หรือ terminate_with
เนื่องจากโดยทั่วไปแล้ว รายการเหล่านี้ไม่มีประโยชน์เมื่อรวมรายการเป็นอาร์กิวเมนต์เดียว
หากไม่มีสตริงที่จะนำมารวมในอาร์กิวเมนต์หลังจากการกรอง และ omit_if_empty
เป็น True (ค่าเริ่มต้น) จะไม่มีการประมวลผลใดๆ หรือหากไม่มีสตริงที่จะผนวก แต่ omit_if_empty
เป็นค่าเท็จ สตริงที่รวมจะเป็นสตริงว่างเปล่า
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
arg_name_or_values
|
ต้องระบุ หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อนวันที่ values โดยไม่ประมวลผล ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีสตริงที่มาจาก values มารวมเข้าด้วยกัน (ซึ่งอาจเกิดขึ้นหาก values ว่างเปล่าหรือกรองรายการทั้งหมดออก) หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
|
values
|
sequence; or depset ; ค่าเริ่มต้น = ไม่มีการเชื่อมโยงรายการ, Tuple หรือ Depset ที่จะเข้าร่วม |
join_with
|
ต้องระบุ สตริงตัวคั่นที่ใช้เพื่อรวมสตริงที่ได้รับจากการใช้ map_each และ format_each ในลักษณะเดียวกับ string.join()
|
map_each
|
callable; or None ; default = ไม่มีเหมือนกับ add_all
|
format_each
|
string; or None ; default = ไม่มีเหมือนกับ add_all
|
format_joined
|
string; or None ; ค่าเริ่มต้น = ไม่มีรูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่ผนวก สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ |
omit_if_empty
|
ค่าเริ่มต้น = จริง หากเป็น "จริง" หากไม่มีสตริงที่ต้องรวมเข้าด้วยกัน (อาจเป็นเพราะ values ว่างเปล่าหรือทุกรายการถูกกรองออก) ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง ถ้าเป็น "เท็จ" แม้ว่าจะไม่มีสตริงใดๆ ที่จะมารวมเข้าด้วยกัน จะมีการเพิ่มอาร์กิวเมนต์ 2 ตัวต่อท้าย นั่นคือชื่ออาร์กิวเมนต์ตามด้วยสตริงว่าง (ซึ่งเป็นการรวมเชิงตรรกะของสตริงที่เป็น 0)
|
uniquify
|
default = False เหมือนกับ add_all
|
expand_directories
|
default = True เหมือนกับ add_all
|
allow_closure
|
default = False เหมือนกับ add_all
|
set_param_file_format
Args Args.set_param_file_format(format)ตั้งค่ารูปแบบไฟล์ของพารามิเตอร์ หากใช้
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
format
|
ต้องระบุ ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
รูปแบบจะมีค่าเริ่มต้นเป็น "shell" หากไม่มีการเรียกใช้ |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)กระจายอาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์ แล้วแทนที่ด้วยตัวชี้ไปยังไฟล์พารามิเตอร์ ใช้เมื่ออาร์กิวเมนต์อาจใหญ่เกินไปสำหรับขีดจำกัดความยาวของคำสั่งของระบบ
Bazel อาจเลือกเขียนไฟล์พารามิเตอร์ไปยังแผนผังเอาต์พุตระหว่างการดำเนินการเพื่อให้มีประสิทธิภาพ หากคุณกำลังแก้ไขข้อบกพร่องและต้องการตรวจสอบไฟล์พารามิเตอร์ ให้ส่ง --materialize_param_files
ไปยังบิลด์ของคุณ
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
param_file_arg
|
ต้องระบุ สตริงรูปแบบที่มี "%s" เดียว หากอาร์กิวเมนต์แยกไปยังไฟล์พารามิเตอร์ ระบบจะแทนที่อาร์กิวเมนต์เหล่านั้นด้วยอาร์กิวเมนต์ที่ประกอบด้วยสตริงนี้ซึ่งจัดรูปแบบด้วยเส้นทางของไฟล์พารามิเตอร์ ตัวอย่างเช่น ถ้าอาร์กิวเมนต์ถูกแยกไปเป็นไฟล์ของพารามิเตอร์ "params.txt" การระบุ "--file=%s" จะทำให้บรรทัดคำสั่งการดำเนินการมี "--file=params.txt" |
use_always
|
default = False ระบุว่าจะกระจายอาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์เสมอหรือไม่ หากเป็น "เท็จ" Bazel จะตัดสินว่าจะต้องแยกอาร์กิวเมนต์ตามระบบและความยาวอาร์กิวเมนต์หรือไม่ |