ออบเจ็กต์ที่รวมข้อมูลที่จำเป็นในการสร้างบรรทัดคำสั่งบางส่วนหรือทั้งหมดไว้ในลักษณะที่ประหยัดหน่วยความจำ
การดำเนินการมักต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจาก transitive dependencies เช่น บรรทัดคำสั่งของโปรแกรมลิงก์อาจแสดงไฟล์ออบเจ็กต์ทุกไฟล์ที่จุลสารทั้งหมดที่ลิงก์ไว้ต้องใช้ แนวทางปฏิบัติแนะนำคือจัดเก็บข้อมูลที่ส่งผ่านดังกล่าวใน depset
เพื่อให้เป้าหมายหลายรายการแชร์ข้อมูลได้ อย่างไรก็ตาม หากผู้เขียนกฎต้องแปลงชุดข้อมูลเหล่านี้เป็นรายการสตริงเพื่อสร้างบรรทัดคำสั่งการดำเนินการ ก็จะเป็นการทำลายการเพิ่มประสิทธิภาพการแชร์หน่วยความจำนี้
ด้วยเหตุนี้ ฟังก์ชันการสร้างการดำเนินการจึงยอมรับออบเจ็กต์ Args
นอกเหนือจากสตริง ออบเจ็กต์ Args
แต่ละรายการแสดงการต่อสตริงและ Depset เข้าด้วยกัน โดยมีการเปลี่ยนรูปแบบที่ไม่บังคับสำหรับการจัดการข้อมูล ออบเจ็กต์ Args
จะไม่ประมวลผลชุดข้อมูล Dependency ที่ออบเจ็กต์นั้นรวมไว้จนกว่าจะถึงระยะการดําเนินการเมื่อถึงเวลาคํานวณบรรทัดคําสั่ง ซึ่งจะช่วยเลื่อนเวลาการคัดลอกที่มีค่าใช้จ่ายสูงออกไปจนกว่าจะผ่านระยะการวิเคราะห์ ดูข้อมูลเพิ่มเติมได้ที่หน้าการเพิ่มประสิทธิภาพ
Args
สร้างขึ้นโดยการเรียก ctx.actions.args()
โดยสามารถส่งเป็นพารามิเตอร์ arguments
ของ ctx.actions.run()
หรือ ctx.actions.run_shell()
การเปลี่ยนแปลงแต่ละรายการของออบเจ็กต์ Args
จะเพิ่มค่าต่อท้ายบรรทัดคำสั่งสุดท้าย
ฟีเจอร์ map_each
ช่วยให้คุณปรับแต่งวิธีเปลี่ยนรูปแบบรายการเป็นสตริงได้ หากคุณไม่ได้ระบุฟังก์ชัน map_each
การแปลงมาตรฐานจะเป็นดังนี้
- ค่าที่เป็นสตริงอยู่แล้วจะยังคงเดิม
- ระบบจะเปลี่ยนออบเจ็กต์
File
เป็นค่าFile.path
- ระบบจะเปลี่ยนออบเจ็กต์
Label
ให้เป็นการแสดงสตริงที่เปลี่ยนกลับไปเป็นออบเจ็กต์เดียวกันเมื่อแก้ไขในบริบทของที่เก็บข้อมูลหลัก หากเป็นไปได้ การแสดงสตริงจะใช้ชื่อที่ชัดเจนของที่เก็บแทนชื่อตามแบบฉบับของที่เก็บ ซึ่งทำให้การแสดงนี้เหมาะสำหรับใช้ในไฟล์ BUILD แม้ว่าเราจะไม่สามารถรับประกันรูปแบบที่แน่นอนของการแสดง แต่ตัวอย่างทั่วไปคือ//foo:bar
,@repo//foo:bar
และ@@canonical_name~//foo:bar.bzl
- ระบบจะเปลี่ยนประเภทอื่นๆ ทั้งหมดให้เป็นสตริงในลักษณะที่ไม่ได้ระบุ คุณจึงควรหลีกเลี่ยงการส่งค่าที่ไม่ใช่สตริงหรือประเภท
File
ไปยังadd()
และหากส่งค่าไปยังadd_all()
หรือadd_joined()
คุณควรระบุฟังก์ชันmap_each
เมื่อใช้การจัดรูปแบบสตริง (พารามิเตอร์ format
, format_each
และ format_joined
ของเมธอด add*()
) ระบบจะตีความเทมเพลตรูปแบบในลักษณะเดียวกับการแทนที่ %
ในสตริง ยกเว้นว่าเทมเพลตต้องมีตัวยึดตําแหน่งการแทนที่เพียงรายการเดียวและต้องเป็นตัวยึดตําแหน่ง %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
|
required หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความค่านี้เป็นชื่ออาร์กิวเมนต์ เพิ่มชื่ออาร์กิวเมนต์ไว้หน้าค่าโดยไม่มีการประมวลผลใดๆ หากมีการส่งพารามิเตอร์ตำแหน่งเพียงรายการเดียว ระบบจะตีความเป็น value (ดูด้านล่าง)
|
value
|
ค่าเริ่มต้นคือ unbound ออบเจ็กต์ที่จะต่อท้าย ระบบจะแปลงเป็นสตริงโดยใช้การแปลงมาตรฐานที่กล่าวถึงข้างต้น เนื่องจากไม่มีพารามิเตอร์ map_each สําหรับฟังก์ชันนี้ value จึงควรเป็นสตริงหรือ File คุณต้องส่งรายการ Tuple, depset หรือไดเรกทอรี File ไปยัง add_all() หรือ add_joined() แทนเมธอดนี้
|
format
|
string หรือ None
ค่าเริ่มต้นคือ 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
|
required หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความค่านี้เป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ไว้หน้า values เป็นอาร์กิวเมนต์แยกต่างหากโดยไม่มีการประมวลผล ระบบจะไม่เพิ่มชื่ออาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (ซึ่งจะเกิดขึ้นหาก values ว่างเปล่าหรือมีตัวกรองรายการทั้งหมด) หากมีการส่งพารามิเตอร์ตำแหน่งเพียงรายการเดียว ระบบจะตีความเป็น values (ดูด้านล่าง)
|
values
|
sequence หรือ depset
ค่าเริ่มต้นคือ unbound รายการ, tup หรือ depset ที่จะมีรายการต่อท้าย |
map_each
|
Callable หรือ None
ค่าเริ่มต้นคือ None ฟังก์ชันที่แปลงแต่ละรายการเป็นสตริงตั้งแต่ 0 รายการขึ้นไป ซึ่งอาจประมวลผลเพิ่มเติมก่อนต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน ฟังก์ชันนี้จะได้รับอาร์กิวเมนต์ตำแหน่ง 1 หรือ 2 รายการ ได้แก่ รายการที่จะแปลง ตามด้วย ประเภทของผลลัพธ์จะขึ้นอยู่กับจำนวนอาร์กิวเมนต์ที่จะสร้างสำหรับรายการ ดังนี้
None จะมีผลเหมือนกับการแสดงรายการความยาว 1 หรือความยาว 0 ตามลำดับ อย่างไรก็ตาม การหลีกเลี่ยงการสร้างรายการที่ไม่จำเป็นจะมีประสิทธิภาพและอ่านได้ง่ายกว่าโดยปกติแล้ว ระบบจะขยายรายการที่เป็นไดเรกทอรีไปยังเนื้อหาโดยอัตโนมัติเมื่อตั้งค่า เพื่อหลีกเลี่ยงการเก็บรักษาโครงสร้างข้อมูลเฟสการวิเคราะห์ขนาดใหญ่ไว้ในระยะการดำเนินการโดยไม่ตั้งใจ ต้องมีการประกาศฟังก์ชัน คำเตือน: คำสั่ง |
format_each
|
สตริง หรือ None
ค่าเริ่มต้นคือ None รูปแบบสตริงรูปแบบที่ไม่บังคับ ซึ่งจะใช้กับสตริงแต่ละรายการที่ฟังก์ชัน map_each แสดงผล สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" เพียง 1 รายการ
|
before_each
|
string หรือ None
ค่าเริ่มต้นคือ None อาร์กิวเมนต์ที่ไม่บังคับใส่ต่อท้ายก่อนที่อาร์กิวเมนต์แต่ละรายการที่ได้จาก values จะต่อท้าย
|
omit_if_empty
|
ค่าเริ่มต้นคือ True หากเป็น "จริง" และไม่มีอาร์กิวเมนต์ที่มาจาก values ที่จะใส่ต่อท้าย ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง หากเป็นเท็จ ระบบจะยังคงใส่ชื่ออาร์กิวเมนต์และ terminate_with ต่อท้าย (หากระบุไว้) ไม่ว่าจะมีอาร์กิวเมนต์อื่นๆ หรือไม่ก็ตาม
|
uniquify
|
ค่าเริ่มต้นคือ False หากเป็น "จริง" ระบบจะไม่รวมอาร์กิวเมนต์ที่ซ้ำกันซึ่งมาจาก values เฉพาะอาร์กิวเมนต์ที่ปรากฏขึ้นครั้งแรกเท่านั้นที่จะยังคงอยู่ โดยปกติจะไม่จำเป็นต้องใช้ฟีเจอร์นี้ เนื่องจาก Depset จะข้ามรายการที่ซ้ำกันไปแล้ว แต่อาจเป็นประโยชน์หาก map_each ปล่อยสตริงเดียวกันสำหรับหลายรายการ
|
expand_directories
|
ค่าเริ่มต้นคือ True หากเป็น "จริง" ระบบจะขยายไดเรกทอรีใน values เป็นรายการไฟล์แบบแบน ซึ่งจะเกิดขึ้นก่อนที่จะมีการใช้ map_each
|
terminate_with
|
สตริง หรือ None
ค่าเริ่มต้นคือ None อาร์กิวเมนต์ที่ไม่บังคับที่จะเพิ่มต่อท้ายอาร์กิวเมนต์อื่นๆ ทั้งหมด ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (ซึ่งจะเกิดขึ้นหาก values ว่างเปล่าหรือมีรายการทั้งหมดถูกกรองออก)
|
allow_closure
|
ค่าเริ่มต้นคือ False หากเป็น "จริง" จะอนุญาตให้ใช้ตัวปิดท้ายในพารามิเตอร์ฟังก์ชัน เช่น 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
|
required หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความค่านี้เป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กก่อน values โดยไม่มีการประมวลผล ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีสตริงที่มาจาก values เพื่อนำมารวมกัน (ซึ่งอาจเกิดขึ้นหาก values ว่างเปล่าหรือมีตัวกรองรายการทั้งหมด) หากส่งพารามิเตอร์ตำแหน่งเพียงรายการเดียว ระบบจะตีความเป็น values (ดูด้านล่าง)
|
values
|
sequence หรือ depset
ค่าเริ่มต้นคือ unbound ลิสต์ Tuple หรือ depset ที่จะมีรายการเข้าร่วม |
join_with
|
ต้องระบุ สตริงตัวคั่นที่ใช้รวมสตริงที่ได้มาจากการใช้ map_each และ format_each ในลักษณะเดียวกับ string.join()
|
map_each
|
Callable หรือ None
ค่าเริ่มต้นคือ None เหมือนกับ add_all
|
format_each
|
string หรือ None
ค่าเริ่มต้นคือ None ซึ่งเหมือนกับ add_all
|
format_joined
|
string หรือ None
ค่าเริ่มต้นคือ None รูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่รวม สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" เพียง 1 รายการ |
omit_if_empty
|
ค่าเริ่มต้นคือ True หากเป็น "จริง" หากไม่มีสตริงที่จะรวมเข้าด้วยกัน (เนื่องจาก values ว่างเปล่าหรือมีตัวกรองรายการทั้งหมด) ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่มีการเปลี่ยนแปลง หากเป็น "เท็จ" แม้ว่าจะไม่มีสตริงที่เชื่อมเข้าด้วยกัน จะมีการเพิ่มอาร์กิวเมนต์ 2 รายการต่อท้าย ได้แก่ ชื่ออาร์กิวเมนต์ตามด้วยสตริงว่าง (ซึ่งเป็นการรวมตรรกะของสตริงศูนย์)
|
uniquify
|
ค่าเริ่มต้นคือ False เหมือนกับ add_all
|
expand_directories
|
ค่าเริ่มต้นคือ True เหมือนกับ add_all
|
allow_closure
|
ค่าเริ่มต้นคือ False เหมือนกับ add_all
|
set_param_file_format
Args Args.set_param_file_format(format)
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
format
|
required ต้องเป็นหนึ่งใน
รูปแบบเริ่มต้นจะเป็น "shell" หากไม่ได้เรียกใช้ |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
Bazel อาจเลือกที่จะละเว้นการเขียนไฟล์ params ลงในต้นไม้เอาต์พุตระหว่างการดำเนินการเพื่อประสิทธิภาพ หากคุณกำลังแก้ไขข้อบกพร่องในการดำเนินการและต้องการตรวจสอบไฟล์พารามิเตอร์ ให้ส่ง --materialize_param_files
ไปยังบิลด์
พารามิเตอร์
พารามิเตอร์ | คำอธิบาย |
---|---|
param_file_arg
|
ต้องระบุ สตริงรูปแบบที่มี "%s" รายการเดียว หากมีการแยก args ไปยังไฟล์ params ระบบจะแทนที่ args ด้วยอาร์กิวเมนต์ที่ประกอบด้วยสตริงนี้ซึ่งจัดรูปแบบด้วยเส้นทางของไฟล์ params ตัวอย่างเช่น หากมีการแยก args ไปยังไฟล์ params "params.txt" การระบุ "--file=%s" จะทำให้บรรทัดคำสั่งการดำเนินการมี "--file=params.txt" |
use_always
|
ค่าเริ่มต้นคือ False Whether to always spill the args to a params file. หากเป็นเท็จ Bazel จะตัดสินใจว่าต้องแยกอาร์กิวเมนต์หรือไม่โดยอิงตามระบบและความยาวของอาร์กิวเมนต์ |