ซึ่งมักเกิดขึ้นเนื่องจากการดำเนินการจำเป็นต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจากทรัพยากร Dependency ทางอ้อม ตัวอย่างเช่น บรรทัดคำสั่ง Linker อาจแสดงรายชื่อไฟล์ออบเจ็กต์ทั้งหมดที่ต้องการสำหรับไลบรารีทั้งหมดที่ลิงก์ แนวทางปฏิบัติแนะนำคือให้จัดเก็บข้อมูลการเปลี่ยนแปลงดังกล่าวไว้ใน depset
เพื่อให้แชร์กับเป้าหมายจำนวนมากได้ อย่างไรก็ตาม ถ้าผู้เขียนกฎต้องแปลง 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 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อนค่าโดยไม่มีการประมวลผล หากส่งพารามิเตอร์ตำแหน่งเพียงพารามิเตอร์เดียว ระบบจะตีความว่าเป็น value (ดูด้านล่าง)
|
value
|
default = unbound ออบเจ็กต์ที่จะต่อท้าย ระบบจะแปลงสตริงโดยใช้ Conversion มาตรฐานที่กล่าวถึงข้างต้น เนื่องจากไม่มีพารามิเตอร์ map_each สำหรับฟังก์ชันนี้ value ควรเป็นสตริงหรือ File ต้องส่งรายการ, tuple, depset หรือไดเรกทอรี File ไปยัง add_all() หรือ add_joined() แทนวิธีการนี้
|
format
|
string; or None ;
default = ไม่มีรูปแบบสตริงที่จะนำไปใช้กับเวอร์ชันสตริงของ 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 เป็น "จริง" (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือกรองรายการทั้งหมดแล้ว) หากส่งพารามิเตอร์ตำแหน่งเพียงพารามิเตอร์เดียว ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
|
values
|
sequence; or depset ; default = ไม่มีการเชื่อมโยงรายการ, Tuple หรือ Depset ที่จะต่อท้ายรายการ |
map_each
|
callable; or None ;
ค่าเริ่มต้น = ไม่มีฟังก์ชันที่แปลงแต่ละรายการเป็นสตริงหรือสตริงตั้งแต่ 0 สตริงขึ้นไป ซึ่งอาจมีการประมวลผลเพิ่มเติมก่อนที่จะนำไปต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน ฟังก์ชันจะส่งผ่านอาร์กิวเมนต์ตำแหน่ง 1 หรือ 2 อาร์กิวเมนต์ ได้แก่ รายการที่จะแปลง ตามด้วย ประเภทของค่าการแสดงผลจะขึ้นอยู่กับจำนวนอาร์กิวเมนต์ที่จะสร้างสำหรับรายการ ดังนี้
None มีผลเหมือนกับการแสดงผลรายการความยาว 1 หรือความยาว 0 ตามลำดับ อย่างไรก็ตาม ข้อความนี้จะมีประสิทธิภาพและอ่านได้ง่ายขึ้นเพื่อหลีกเลี่ยงการสร้างรายการที่ไม่จำเป็นโดยปกติแล้ว รายการที่เป็นไดเรกทอรีจะขยายไปยังเนื้อหาโดยอัตโนมัติเมื่อมีการตั้งค่า หากต้องการหลีกเลี่ยงการเก็บรักษาโครงสร้างข้อมูลระยะการวิเคราะห์ขนาดใหญ่ในระยะการดำเนินการโดยไม่ตั้งใจ จะต้องประกาศฟังก์ชัน คำเตือน: คำสั่ง |
format_each
|
string; or None ;
default = ไม่มีรูปแบบสตริงที่ไม่บังคับซึ่งใช้กับแต่ละสตริงที่แสดงผลโดยฟังก์ชัน map_each สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ
|
before_each
|
string; or None ;
default = ไม่มีสตริงที่ไม่บังคับที่จะใส่ต่อท้ายก่อนอาร์กิวเมนต์แต่ละรายการที่ได้จาก values จะต่อท้าย
|
omit_if_empty
|
default = True หากเป็น "จริง" หากไม่มีอาร์กิวเมนต์ที่มาจาก values มาต่อท้าย ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง หากเป็น "เท็จ" ชื่ออาร์กิวเมนต์และ terminate_with (หากมี) จะยังคงต่อท้ายไม่ว่าจะมีอาร์กิวเมนต์อื่นๆ หรือไม่ก็ตาม
|
uniquify
|
default = False หากจริง ระบบจะละเว้นอาร์กิวเมนต์ที่ซ้ำกันที่มาจาก values เฉพาะรายการแรกของแต่ละอาร์กิวเมนต์เท่านั้นที่จะยังคงอยู่ โดยปกติแล้วจะไม่จำเป็นต้องใช้ฟีเจอร์นี้เนื่องจาก depset จะข้ามรายการที่ซ้ำกันไปแล้ว แต่อาจเป็นประโยชน์หาก map_each ปล่อยสตริงเดียวกันสำหรับหลายรายการ
|
expand_directories
|
default = True หากเป็น "จริง" ไดเรกทอรีใดก็ตามใน values จะขยายเป็นรายการไฟล์แบบรวม ซึ่งจะเกิดขึ้นก่อนที่ map_each จะมีผล
|
terminate_with
|
string; or None ;
default = ไม่มีสตริงที่ไม่บังคับที่จะต่อท้ายอาร์กิวเมนต์อื่นๆ ทั้งหมด ระบบจะไม่เพิ่มสตริงนี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือกรองรายการทั้งหมดแล้ว)
|
allow_closure
|
default = False หากเป็น true จะใช้การปิดในพารามิเตอร์ฟังก์ชันได้ เช่น 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
เป็น "จริง" (ค่าเริ่มต้น) ระบบจะไม่ประมวลผล หรือหากไม่มีสตริงที่จะผนวก แต่ omit_if_empty
เป็นเท็จ สตริงที่รวมจะเป็นสตริงว่างเปล่า
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
arg_name_or_values
|
ต้องระบุ หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อน values โดยไม่ต้องประมวลผล ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีสตริงที่มาจาก values มารวมเข้าด้วยกัน (ซึ่งอาจเกิดขึ้นได้หาก values ว่างเปล่าหรือกรองรายการทั้งหมดแล้ว) หากส่งพารามิเตอร์ตำแหน่งเพียงพารามิเตอร์เดียว ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
|
values
|
sequence; or depset ; default = Unboundรายการ, 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 ;
default = ไม่มีรูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่ผนวก สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ |
omit_if_empty
|
default = True หากเป็น "จริง" หากไม่มีสตริงที่จะผนวกเข้าด้วยกัน (อาจเป็นเพราะ 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 จะตัดสินใจว่าต้องแยกอาร์กิวเมนต์ตามระบบและความยาวอาร์กิวเมนต์หรือไม่ |