อาร์กส์

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4

ออบเจ็กต์ที่รวมข้อมูลที่จำเป็นในการสร้างบรรทัดคำสั่งบางส่วนหรือทั้งหมดไว้ในลักษณะที่ประหยัดหน่วยความจำ

การดำเนินการมักต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจาก transitive dependencies เช่น บรรทัดคำสั่งของโปรแกรมลิงก์อาจแสดงไฟล์ออบเจ็กต์ทุกไฟล์ที่จุลสารทั้งหมดที่ลิงก์ไว้ต้องใช้ แนวทางปฏิบัติแนะนำคือจัดเก็บข้อมูลที่ส่งผ่านดังกล่าวใน depset เพื่อให้เป้าหมายหลายรายการแชร์ข้อมูลได้ อย่างไรก็ตาม หากผู้เขียนกฎต้องแปลงชุดข้อมูลเหล่านี้เป็นรายการสตริงเพื่อสร้างบรรทัดคำสั่งการดำเนินการ ก็จะเป็นการทำลายการเพิ่มประสิทธิภาพการแชร์หน่วยความจำนี้

ด้วยเหตุนี้ ฟังก์ชันการสร้างการดำเนินการจึงยอมรับออบเจ็กต์ Args นอกเหนือจากสตริง ออบเจ็กต์ Args แต่ละรายการแสดงการต่อสตริงและชุดข้อมูลย่อย โดยมีการเปลี่ยนรูปแบบที่ไม่บังคับสําหรับการจัดการข้อมูล ออบเจ็กต์ Args จะไม่ประมวลผลชุดข้อมูล Dependency ที่ออบเจ็กต์นั้นรวมไว้จนกว่าจะถึงระยะการดําเนินการเมื่อถึงเวลาคํานวณบรรทัดคําสั่ง ซึ่งจะช่วยเลื่อนเวลาการคัดลอกที่มีราคาแพงไปจนกว่าช่วงการวิเคราะห์จะเสร็จสมบูรณ์ ดูข้อมูลเพิ่มเติมได้ที่หน้าการเพิ่มประสิทธิภาพ

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*()) ระบบจะตีความเทมเพลตรูปแบบในลักษณะเดียวกับการแทนที่ % ในสตริง ยกเว้นว่าเทมเพลตต้องมีตัวยึดตําแหน่งการแทนที่เพียงรายการเดียวและต้องเป็นตัวยึดตําแหน่ง %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 ค่าเริ่มต้นคือ 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)

ต่อท้ายอาร์กิวเมนต์หลายรายการลงในบรรทัดคำสั่งนี้ รายการจะได้รับการประมวลผลแบบ Lazy Loading ในระหว่างระยะการดำเนินการ

การประมวลผลส่วนใหญ่เกิดขึ้นกับรายการอาร์กิวเมนต์ที่จะเพิ่มต่อท้ายตามขั้นตอนต่อไปนี้

  1. รายการ File แต่ละรายการในไดเรกทอรีจะแทนที่ด้วย File ทั้งหมดที่อยู่ในไดเรกทอรีนั้นแบบซ้ำ
  2. หากระบุ map_each ระบบจะใช้กับแต่ละรายการ และต่อสตริงที่เป็นผลลัพธ์เข้าด้วยกันเพื่อสร้างรายการอาร์กิวเมนต์เริ่มต้น มิฉะนั้น รายการอาร์กิวเมนต์เริ่มต้นจะเป็นผลลัพธ์จากการใช้การเปลี่ยนรูปแบบมาตรฐานกับแต่ละรายการ
  3. อาร์กิวเมนต์แต่ละรายการในรายการจะอยู่ในรูปแบบ format_each หากมี
  4. หาก uniquify เป็นจริง ระบบจะนำอาร์กิวเมนต์ที่ซ้ำกันออก รายการแรกคือรายการที่จะยังคงอยู่
  5. หากระบุสตริง before_each ระบบจะแทรกสตริงเป็นอาร์กิวเมนต์ใหม่ก่อนอาร์กิวเมนต์ที่มีอยู่แต่ละรายการในรายการ ซึ่งจะช่วยเพิ่มจำนวนอาร์กิวเมนต์ที่จะเพิ่มเข้ามาด้วยจุดนี้ได้อย่างมีประสิทธิภาพ
  6. ยกเว้นในกรณีที่ลิสต์ว่างและ omit_if_empty เป็นจริง (ค่าเริ่มต้น) ระบบจะแทรกชื่ออาร์กิวเมนต์และ terminate_with เป็นอาร์กิวเมนต์แรกและสุดท้ายตามลำดับ หากระบุไว้
โปรดทราบว่าสตริงว่างเป็นอาร์กิวเมนต์ที่ถูกต้องซึ่งอยู่ภายใต้ขั้นตอนการประมวลผลทั้งหมดเหล่านี้

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
arg_name_or_values ต้องระบุ
หากระบบส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ไว้หน้า values เป็นอาร์กิวเมนต์แยกต่างหากโดยไม่มีการประมวลผล ระบบจะไม่เพิ่มชื่ออาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (ซึ่งจะเกิดขึ้นหาก values ว่างเปล่าหรือมีตัวกรองรายการทั้งหมด) หากมีการส่งพารามิเตอร์ตำแหน่งเพียงรายการเดียว ระบบจะตีความเป็น values (ดูด้านล่าง)
values sequence หรือ depset ค่าเริ่มต้นคือ unbound
รายการ, tup หรือ depset ที่จะมีรายการต่อท้าย
map_each callable หรือ None ค่าเริ่มต้นคือ None
ฟังก์ชันที่แปลงแต่ละรายการให้เป็นสตริงตั้งแต่ 0 รายการขึ้นไป ซึ่งอาจได้รับการประมวลผลเพิ่มเติมก่อนต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน

ฟังก์ชันนี้จะได้รับอาร์กิวเมนต์ตำแหน่ง 1 หรือ 2 รายการ ได้แก่ รายการที่จะแปลง ตามด้วย DirectoryExpander (ไม่บังคับ) ระบบจะส่งอาร์กิวเมนต์ที่ 2 เฉพาะในกรณีที่ฟังก์ชันที่ระบุเป็นฟังก์ชันที่ผู้ใช้กำหนด (ไม่ใช่ฟังก์ชันในตัว) และประกาศพารามิเตอร์มากกว่า 1 รายการ

ประเภทของผลลัพธ์จะขึ้นอยู่กับจำนวนอาร์กิวเมนต์ที่จะสร้างสำหรับรายการ ดังนี้

  • ในกรณีทั่วไปเมื่อแต่ละรายการกลายเป็นสตริงเดียว ฟังก์ชันควรแสดงผลสตริงนั้น
  • หากระบบกรองรายการออกทั้งหมด ฟังก์ชันควรแสดงผล None
  • หากรายการเปลี่ยนเป็นสตริงหลายรายการ ฟังก์ชันจะแสดงรายการสตริงเหล่านั้น
การคืนค่าสตริงเดียวหรือ None จะมีผลเหมือนกับการคืนค่าลิสต์ที่มีความยาว 1 หรือ 0 ตามลำดับ อย่างไรก็ตาม การหลีกเลี่ยงการสร้างรายการที่ไม่จำเป็นจะมีประสิทธิภาพและอ่านได้ง่ายกว่า

โดยปกติแล้ว ระบบจะขยายรายการที่เป็นไดเรกทอรีไปยังเนื้อหาโดยอัตโนมัติเมื่อตั้งค่า expand_directories=True แต่วิธีนี้จะไม่ขยายไดเรกทอรีที่อยู่ภายในค่าอื่นๆ เช่น เมื่อรายการเป็น Struct ที่มีไดเรกทอรีเป็นช่อง ในกรณีนี้ คุณสามารถใช้อาร์กิวเมนต์ DirectoryExpander เพื่อรับไฟล์ของไดเรกทอรีหนึ่งๆ ด้วยตนเอง

คุณต้องประกาศฟังก์ชัน map_each ด้วยคำสั่ง def ระดับบนสุดเพื่อหลีกเลี่ยงการเก็บโครงสร้างข้อมูลขนาดใหญ่ในระยะการวิเคราะห์ไว้ในระยะการดําเนินการโดยไม่ตั้งใจ โดยฟังก์ชันดังกล่าวต้องไม่ใช่การปิดฟังก์ชันที่ฝังอยู่โดยค่าเริ่มต้น

คำเตือน: คำสั่ง print() ที่ดำเนินการระหว่างการเรียกใช้ map_each จะไม่แสดงผลลัพธ์ที่มองเห็นได้

format_each สตริง หรือ None ค่าเริ่มต้นคือ None
รูปแบบสตริงรูปแบบที่ไม่บังคับ ซึ่งจะใช้กับสตริงแต่ละรายการที่ฟังก์ชัน map_each แสดงผล สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" เพียง 1 รายการ
before_each สตริง หรือ 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 สตริง หรือ None ค่าเริ่มต้นคือ None
เหมือนกับ add_all
format_joined string หรือ None ค่าเริ่มต้นคือ None
รูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่รวม สตริงรูปแบบต้องมีตัวยึดตําแหน่ง "%s" เพียง 1 รายการ
omit_if_empty ค่าเริ่มต้นคือ True
หากเป็น "จริง" หากไม่มีสตริงให้ผนวกเข้าด้วยกัน (เนื่องจาก values ว่างเปล่าหรือมีการกรองรายการทั้งหมด) การประมวลผลเพิ่มเติมทั้งหมดจะถูกระงับและบรรทัดคำสั่งจะไม่มีการเปลี่ยนแปลง หากเป็นเท็จ ระบบจะเพิ่มอาร์กิวเมนต์ 2 รายการต่อท้ายแม้ว่าจะไม่มีสตริงที่จะรวมกันก็ตาม ได้แก่ ชื่ออาร์กิวเมนต์ตามด้วยสตริงว่าง (ซึ่งเป็นการรวมตรรกะของสตริง 0)
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
ต้องเป็นหนึ่งใน
  • "multiline": แต่ละรายการ (ชื่ออาร์กิวเมนต์หรือค่า) จะเขียนแบบคำต่อคำลงในไฟล์พารามิเตอร์โดยมีอักขระบรรทัดใหม่ต่อท้าย
  • "shell": เหมือนกับ "multiline" แต่รายการจะอยู่ในเครื่องหมายคำพูดของเชลล์
  • "flag_per_line": เหมือนกับ "multiline" แต่จะ (1) เขียนเฉพาะ Flag (ขึ้นต้นด้วย "--") ลงในไฟล์ param และ (2) ค่าของ Flag (หากมี) จะเขียนในบรรทัดเดียวกันโดยคั่นด้วยเครื่องหมาย "=" นี่เป็นรูปแบบที่ไลบรารี Flag ของ Abseil คาดไว้

รูปแบบเริ่มต้นจะเป็น "shell" หากไม่ได้เรียกใช้

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

แสดง args ในไฟล์ params โดยแทนที่ด้วยเคอร์เซอร์ไปยังไฟล์ param ใช้เมื่อ args อาจใหญ่เกินขีดจำกัดความยาวคำสั่งของระบบ

Bazel อาจเลือกที่จะละเว้นการเขียนไฟล์ params ลงในต้นไม้เอาต์พุตระหว่างการดำเนินการเพื่อประสิทธิภาพ หากคุณกำลังแก้ไขข้อบกพร่องในการดำเนินการและต้องการตรวจสอบไฟล์พารามิเตอร์ ให้ส่ง --materialize_param_files ไปยังบิลด์

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
param_file_arg ต้องระบุ
สตริงรูปแบบที่มี "%s" รายการเดียว หากอาร์กิวเมนต์นี้กระจัดกระจายไปยังไฟล์พารามิเตอร์ ระบบจะแทนที่พารามิเตอร์ด้วยอาร์กิวเมนต์ที่ประกอบด้วยสตริงนี้ซึ่งมีการจัดรูปแบบด้วยเส้นทางของไฟล์พารามิเตอร์

ตัวอย่างเช่น หากมีการแยก args ไปยังไฟล์ params "params.txt" การระบุ "--file=%s" จะทำให้บรรทัดคำสั่งการดำเนินการมี "--file=params.txt"

use_always ค่าเริ่มต้นคือ False
Whether to always spill the args to a params file. หากเป็น "เท็จ" Bazel จะตัดสินใจว่าต้องใส่อาร์กิวเมนต์ตามระบบและความยาวอาร์กิวเมนต์หรือไม่