อาร์กส์

รายงานปัญหา ดูซอร์สโค้ด

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

บ่อยครั้งที่การดําเนินการกําหนดให้มีบรรทัดคําสั่งขนาดใหญ่ที่มีค่าสะสมจากการอ้างอิงแบบสับเปลี่ยน ตัวอย่างเช่น บรรทัดคําสั่ง 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 ในระหว่างขั้นตอนการดําเนินการ

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

  1. ระบบจะแทนที่แต่ละรายการใน File ด้วย File ทั้งหมดที่เกิดซ้ําในไดเรกทอรีนั้น
  2. หากมีการระบุ map_each ระบบจะนําค่านั้นไปใช้กับแต่ละรายการ และจะเชื่อมโยงรายการสตริงที่ได้เข้าด้วยกันเพื่อสร้างรายการอาร์กิวเมนต์เริ่มต้น มิเช่นนั้น รายการอาร์กิวเมนต์เริ่มต้นจะเป็นผลลัพธ์จากการใช้ Conversion มาตรฐานกับแต่ละรายการ
  3. อาร์กิวเมนต์แต่ละรายการในรายการจะจัดรูปแบบด้วย format_each หากมี
  4. หาก uniquify เป็นจริง ระบบจะนําอาร์กิวเมนต์ที่ซ้ํากันออก รายการที่ 1 คือรายการที่เหลือ
  5. หากมีการระบุสตริง before_each ระบบจะแทรกสตริงนั้นเป็นอาร์กิวเมนต์ใหม่ก่อนอาร์กิวเมนต์แต่ละรายการที่อยู่ในรายการ วิธีนี้จะเพิ่มจํานวนอาร์กิวเมนต์ที่จะเพิ่มต่อท้ายเป็น 2 เท่า
  6. ยกเว้นในกรณีที่รายการว่างเปล่าและมี 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 รายการ ได้แก่ รายการที่จะแปลงตามด้วย DirectoryExpander ซึ่งไม่บังคับ อาร์กิวเมนต์ที่ 2 จะถูกส่งก็ต่อเมื่อฟังก์ชันที่ผู้ใช้กําหนด (ไม่ใช่ในตัว) และประกาศพารามิเตอร์มากกว่าหนึ่งตัว

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

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

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

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

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

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 ต้องระบุ
ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้
  • "multiline": แต่ละรายการ (อาร์กิวเมนต์หรือค่าอาร์กิวเมนต์) จะเขียนแบบคําต่อไปยังไฟล์พารามิเตอร์ที่มีอักขระขึ้นบรรทัดใหม่ตามด้วย
  • "shell": เหมือนกับ "multiline" แต่สินค้าดังกล่าวยกมาแบบ shell
  • "flag_per_line": เหมือนกับ "multiline" แต่ (1) จะเขียนเฉพาะแฟล็ก (ขึ้นต้นด้วย '--') ไปยังไฟล์ param และ (2) ค่าของ Flag ถ้ามีบนบรรทัดเดียวกันโดยมี '=' ตัวคั่น นี่คือรูปแบบที่ไลบรารีการแจ้งว่าไม่เหมาะสมของ Abseil คาดการณ์ไว้

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