อาร์กส์

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

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

ซึ่งมักเกิดขึ้นเนื่องจากการดำเนินการจำเป็นต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจากทรัพยากร 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 ค่าเริ่มต้นคือ unbound
ออบเจ็กต์ที่จะต่อท้าย ระบบจะแปลงสตริงโดยใช้ Conversion มาตรฐานที่กล่าวถึงข้างต้น เนื่องจากไม่มีพารามิเตอร์ 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)

เพิ่มอาร์กิวเมนต์หลายรายการต่อท้ายบรรทัดคำสั่งนี้ ระบบจะประมวลผลรายการอย่างช้าๆ ในระหว่างขั้นตอนการดำเนินการ

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

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

พารามิเตอร์

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

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

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

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

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

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

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

format_each string หรือ 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 string หรือ 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 ต้องระบุ
หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อน values โดยไม่ต้องประมวลผล ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีสตริงที่มาจาก values มารวมเข้าด้วยกัน (ซึ่งอาจเกิดขึ้นได้หาก values ว่างเปล่าหรือกรองรายการทั้งหมดแล้ว) หากส่งพารามิเตอร์ตำแหน่งเพียงพารามิเตอร์เดียว ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
values sequence หรือ depset ค่าเริ่มต้นคือ unbound
รายการ, tuple หรือ depset ที่รายการจะเข้าร่วม
join_with ต้องระบุ
สตริงตัวคั่นที่ใช้ในการรวมสตริงที่ได้จากการใช้ map_each และ format_each ในลักษณะเดียวกับ string.join()
map_each โทรออกได้ หรือ None ค่าเริ่มต้นคือ None
เช่นเดียวกับ add_all
format_each string หรือ 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 ต้องระบุ
ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้
  • "multiline": แต่ละรายการ (ชื่ออาร์กิวเมนต์หรือค่า) จะเขียนแบบคำต่อคำไปยังไฟล์พารามิเตอร์ โดยมีอักขระขึ้นบรรทัดใหม่ตามหลัง
  • "shell": เหมือนกับ "multiline" แต่รายการมีการอ้างอิงแบบ shell
  • "flag_per_line": เหมือนกับ "multiline" แต่ (1) เฉพาะแฟล็ก (ขึ้นต้นด้วย "--") จะเขียนลงในไฟล์พารามิเตอร์ และ (2) ค่าของแฟล็ก (หากมี) จะเขียนในบรรทัดเดียวกันโดยใช้ตัวคั่น '=' นี่เป็นรูปแบบที่ไลบรารีธง Abseil คาดหวัง

รูปแบบจะมีค่าเริ่มต้นเป็น "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 ค่าเริ่มต้นคือ False
ระบุว่าจะใส่อาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์เสมอหรือไม่ หากเป็น "เท็จ" Bazel จะตัดสินใจว่าต้องแยกอาร์กิวเมนต์ตามระบบและความยาวอาร์กิวเมนต์หรือไม่