บ่อยครั้งที่การดําเนินการกําหนดให้มีบรรทัดคําสั่งขนาดใหญ่ที่มีค่าสะสมจากการอ้างอิงแบบสับเปลี่ยน ตัวอย่างเช่น บรรทัดคําสั่ง Linker อาจแสดงรายการออบเจ็กต์ทั้งหมดซึ่งไลบรารีทั้งหมดที่กําลังลิงก์อยู่จําเป็นต้องใช้ แนวทางปฏิบัติที่ดีที่สุดคือการจัดเก็บข้อมูลทางอ้อมใน depset
เพื่อให้สามารถแชร์กับหลายเป้าหมายได้ แต่หากผู้เขียนกฎต้องแปลงค่าเหล่านี้ไปเป็นรายการของสตริง เพื่อสร้างบรรทัดคําสั่งการดําเนินการ ก็จะใช้การเพิ่มประสิทธิภาพการแชร์หน่วยความจํานี้ไม่ได้
ด้วยเหตุนี้ ฟังก์ชันการสร้างการทํางานจะยอมรับออบเจ็กต์ Args
เพิ่มเติมจากสตริง ออบเจ็กต์ Args
แต่ละรายการจะแสดงการต่อกันของสตริงและสตริง พร้อมการเปลี่ยนรูปแบบที่ไม่บังคับสําหรับการจัดการข้อมูล ออบเจ็กต์ Args
ไม่ประมวลผลส่วนที่แสดงผลซึ่งห่อหุ้มอยู่จนกว่าจะถึงระยะการดําเนินการ หากคํานวณบรรทัดคําสั่ง ซึ่งจะช่วยชะลอการคัดลอกราคาที่แพงไปจนกว่าระยะการวิเคราะห์จะเสร็จสิ้น ดูข้อมูลเพิ่มเติมในหน้าการเพิ่มประสิทธิภาพ
Args
สร้างขึ้นโดยการเรียกใช้ ctx.actions.args()
พารามิเตอร์เหล่านี้สามารถส่งผ่านได้เป็นพารามิเตอร์ arguments
ของ ctx.actions.run()
หรือ ctx.actions.run_shell()
การเปลี่ยนแปลงแต่ละครั้งของออบเจ็กต์ Args
จะเพิ่มค่าต่อท้ายบรรทัดคําสั่งสุดท้าย
ฟีเจอร์ map_each
ให้คุณปรับแต่งวิธีแปลงสินค้าให้เป็นสตริง หากคุณไม่ระบุฟังก์ชัน map_each
การแปลงมาตรฐานจะเป็นดังนี้
- ค่าที่เป็นสตริงอยู่แล้วจะคงไว้ตามเดิม
- ออบเจ็กต์
File
จะเปลี่ยนเป็นค่าFile.path
- ประเภทอื่นๆ ทั้งหมดถูกเปลี่ยนเป็นสตริงในลักษณะที่ไม่ระบุ ดังนั้นคุณควรหลีกเลี่ยงการส่งค่าที่ไม่ใช่สตริงหรือประเภท
File
ไปยังadd()
และหากคุณส่งผ่านค่าไปยังadd_all()
หรือadd_joined()
คุณควรมีฟังก์ชันmap_each
เมื่อใช้การจัดรูปแบบสตริง (format
, format_each
และพารามิเตอร์ format_joined
ของเมธอด add*()
) ระบบจะตีความเทมเพลตรูปแบบในลักษณะเดียวกับ %
การแทนที่สตริง เว้นแต่เทมเพลตจะต้องมีตัวยึดตําแหน่งการแทนที่ 1 รายการและต้องเป็น %s
เปอร์เซ็นต์ตามตัวอักษรอาจใช้ Escape เป็น %%
การจัดรูปแบบจะมีผลหลังจากแปลงค่าเป็นสตริงตามที่ระบุไว้ข้างต้น
เมธอด 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 ;
ค่าเริ่มต้น = ไม่มีรูปแบบสตริงรูปแบบที่จะใช้กับ value เวอร์ชันใช้สตริง
|
เพิ่มทั้งหมด
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)เพิ่มอาร์กิวเมนต์หลายรายการต่อท้ายบรรทัดคําสั่งนี้ ระบบจะประมวลผลรายการแบบ Lazy Loading ในระหว่างขั้นตอนการดําเนินการ
การประมวลผลส่วนใหญ่เกิดขึ้นผ่านรายการอาร์กิวเมนต์ที่จะเพิ่มต่อท้าย ตามขั้นตอนต่อไปนี้
- ระบบจะแทนที่แต่ละรายการใน
File
ด้วยFile
ทั้งหมดที่เกิดซ้ําในไดเรกทอรีนั้น - หากมีการระบุ
map_each
ระบบจะนําค่านั้นไปใช้กับแต่ละรายการ และจะเชื่อมโยงรายการสตริงที่ได้เข้าด้วยกันเพื่อสร้างรายการอาร์กิวเมนต์เริ่มต้น มิเช่นนั้น รายการอาร์กิวเมนต์เริ่มต้นจะเป็นผลลัพธ์จากการใช้ Conversion มาตรฐานกับแต่ละรายการ - อาร์กิวเมนต์แต่ละรายการในรายการจะจัดรูปแบบด้วย
format_each
หากมี - หาก
uniquify
เป็นจริง ระบบจะนําอาร์กิวเมนต์ที่ซ้ํากันออก รายการที่ 1 คือรายการที่เหลือ - หากมีการระบุสตริง
before_each
ระบบจะแทรกสตริงนั้นเป็นอาร์กิวเมนต์ใหม่ก่อนอาร์กิวเมนต์แต่ละรายการที่อยู่ในรายการ วิธีนี้จะเพิ่มจํานวนอาร์กิวเมนต์ที่จะเพิ่มต่อท้ายเป็น 2 เท่า - ยกเว้นในกรณีที่รายการว่างเปล่าและมี
omit_if_empty
เป็นจริง (ค่าเริ่มต้น) ระบบจะแทรกชื่ออาร์กิวเมนต์และterminate_with
เป็นอาร์กิวเมนต์แรกและอาร์กิวเมนต์สุดท้ายตามลําดับ
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
arg_name_or_values
|
ต้องระบุ หากระบบส่งพารามิเตอร์ตําแหน่ง 2 รายการ ระบบจะตีความเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อน values เป็นอาร์กิวเมนต์แยกต่างหากโดยไม่ต้องประมวลผล ระบบจะไม่เพิ่มชื่ออาร์กิวเมนต์นี้หาก omit_if_empty เป็น "จริง" (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (เช่น หาก values ว่างเปล่าหรือกรองรายการทั้งหมด) หากมีการส่งพารามิเตอร์ตําแหน่งเพียงรายการเดียว ระบบจะตีความเป็น values (ดูด้านล่าง)
|
values
|
sequence; or depset ;
default = unboundรายการ, tuple หรือ depset ที่มีรายการต่อท้าย |
map_each
|
callable; or None ;
ค่าเริ่มต้น = ไม่มีฟังก์ชันที่แปลงแต่ละรายการเป็นสตริงตั้งแต่ 0 รายการขึ้นไป ซึ่งระบบอาจประมวลผลเพิ่มเติมก่อนที่จะต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน ฟังก์ชันจะถูกส่งผ่านอาร์กิวเมนต์ตําแหน่ง 1 หรือ 2 รายการ ได้แก่ รายการที่จะแปลงตามด้วย ประเภทของค่าการคืนสินค้าขึ้นอยู่กับจํานวนอาร์กิวเมนต์ที่จะสร้างสําหรับรายการดังกล่าว ดังนี้
None มีผลเหมือนกับการแสดงรายการความยาว 1 หรือความยาว 0 ตามลําดับ แต่มีประสิทธิภาพมากกว่าและอ่านได้ง่ายเพื่อหลีกเลี่ยงการสร้างรายการที่ไม่จําเป็นโดยปกติแล้ว สินค้าที่เป็นไดเรกทอรีจะขยายไปยังเนื้อหาโดยอัตโนมัติเมื่อมีการตั้งค่า ฟังก์ชัน คําเตือน: คําสั่ง |
format_each
|
string; or None ;
ค่าเริ่มต้น = ไม่มีรูปแบบสตริงรูปแบบที่ไม่บังคับ ซึ่งใช้กับแต่ละสตริงที่แสดงโดยฟังก์ชัน map_each สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" 1 รายการ
|
before_each
|
string; or None ;
ค่าเริ่มต้น = ไม่มีอาร์กิวเมนต์ที่ไม่บังคับที่จะเพิ่มต่อท้ายก่อนที่แต่ละอาร์กิวเมนต์ที่ได้มาจาก values จะถูกเพิ่มต่อท้าย
|
omit_if_empty
|
default = True หากค่าเป็น True ถ้าไม่มีอาร์กิวเมนต์มาจาก values ที่จะต่อท้าย ระบบจะประมวลผลการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคําสั่งจะไม่เปลี่ยนแปลง หากเป็น "เท็จ" ระบบจะเติมชื่ออาร์กิวเมนต์และ terminate_with ต่อท้าย ไม่ว่าจะมีอาร์กิวเมนต์อื่นๆ หรือไม่ก็ตาม
|
uniquify
|
default = False หากเป็นจริง ระบบจะไม่สนใจอาร์กิวเมนต์ที่ซ้ํากันซึ่งมาจาก values ไว้ เฉพาะอาร์กิวเมนต์แรกเท่านั้นที่จะยังคงอยู่ โดยปกติไม่จําเป็นต้องใช้ฟีเจอร์นี้ เนื่องจาก Depset ไม่แสดงรายการซ้ําอยู่แล้ว แต่อาจเป็นประโยชน์หาก map_each ปล่อยสตริงเดียวกันสําหรับสินค้าหลายรายการ
|
expand_directories
|
default = True หาก true ระบบจะขยายไดเรกทอรีใน values ไปยังรายการไฟล์แบบคงที่ ซึ่งจะเกิดขึ้นก่อนที่จะมีการใช้ map_each
|
terminate_with
|
string; or None ;
default = Noneอาร์กิวเมนต์ที่ไม่บังคับต่อท้ายต่อท้ายอาร์กิวเมนต์อื่นๆ ทั้งหมด ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็น "จริง" (ค่าเริ่มต้น) และจะไม่มีรายการอื่นๆ ต่อท้าย (ในกรณีที่ values ว่างเปล่าหรือทุกรายการในมีการกรอง)
|
allow_closure
|
default = False หากเป็น "จริง" จะอนุญาตให้ใช้การปิดในพารามิเตอร์ฟังก์ชัน เช่น map_each ซึ่งโดยปกติจะไม่จําเป็นและมีความเสี่ยงที่จะมีโครงสร้างข้อมูลระยะการวิเคราะห์ขนาดใหญ่ในระยะดําเนินการ
|
เข้าร่วมแล้ว
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)เพิ่มอาร์กิวเมนต์ต่อท้ายบรรทัดคําสั่งนี้โดยการเชื่อมค่าหลายค่าเข้าด้วยกันโดยใช้ตัวคั่น ระบบจะประมวลผลรายการแบบ Lazy Loading ในระหว่างขั้นตอนการดําเนินการ
การประมวลผลคล้ายกับ 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 = Noneเช่นเดียวกับ add_all
|
format_each
|
string; or None ;
default = Noneเช่นเดียวกับ add_all
|
format_joined
|
string; or None ;
ค่าเริ่มต้น = ไม่มีรูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่เข้าร่วม สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" 1 รายการ |
omit_if_empty
|
default = True หากค่าเป็น True หากไม่มีสตริงที่จะเชื่อมโยงกัน (เนื่องจาก values ว่างเปล่าหรือได้กรองรายการทั้งหมดออก) ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคําสั่งจะไม่เปลี่ยนแปลง หากเป็น "เท็จ" แม้ว่าจะไม่มีสตริงที่จะเชื่อมโยงกัน แต่ระบบจะเพิ่มอาร์กิวเมนต์ 2 รายการต่อท้าย: ชื่ออาร์กิวเมนต์ตามด้วยสตริงว่าง (ซึ่งเป็นการรวมเชิงตรรกะของสตริงที่เป็นศูนย์)
|
uniquify
|
default = False เช่นเดียวกับ add_all
|
expand_directories
|
default = True เช่นเดียวกับ add_all
|
allow_closure
|
default = False เช่นเดียวกับ add_all
|
รูปแบบ_พารามิเตอร์ของไฟล์_ตั้ง
Args Args.set_param_file_format(format)กําหนดรูปแบบของไฟล์พารามิเตอร์ (หากมี)
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
format
|
ต้องระบุ ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้
รูปแบบจะมีค่าเริ่มต้นเป็น "shell" หากไม่ได้เรียกใช้ |
ใช้ไฟล์_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)กระจายอาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์ โดยแทนที่ด้วยอาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์ ใช้เมื่ออาร์กิวเมนต์ของคุณอาจใหญ่เกินไปสําหรับขีดจํากัดความยาวของคําสั่งของระบบ
บาเซลอาจเลือกกรอกไฟล์พารามิเตอร์ลงในโครงสร้างเอาต์พุตระหว่างการดําเนินการเพื่อให้เกิดประสิทธิภาพ หากคุณจะแก้ไขข้อบกพร่องและการดําเนินการที่ต้องการตรวจสอบไฟล์พารามิเตอร์ ให้ส่ง --materialize_param_files
ไปยังบิวด์
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
param_file_arg
|
ต้องระบุ สตริงรูปแบบที่มี "%s" เพียงตัวเดียว หากหกอาร์กิวเมนต์ให้กับไฟล์พารามิเตอร์ อาร์กิวเมนต์จะถูกแทนที่ด้วยอาร์กิวเมนต์ที่ประกอบด้วยสตริงนี้ซึ่งจัดรูปแบบด้วยเส้นทางของไฟล์พารามิเตอร์ เช่น หากอาร์กิวเมนต์หกหลุดไปยังไฟล์พารามิเตอร์ "params.txt" การระบุ "--file=%s" จะทําให้บรรทัดคําสั่งสําหรับการดําเนินการมี "--file=params.txt" |
use_always
|
default = False เลือกว่าจะส่งอาร์กิวเมนต์ถึงไฟล์พารามิเตอร์เสมอหรือไม่ หากเป็น "เท็จ" Bazel จะตัดสินใจว่าต้องแตกอาร์กิวเมนต์ตามระบบและความยาวของอาร์กิวเมนต์หรือไม่ |