อาร์กส์

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

ซึ่งมักเกิดขึ้นที่การดำเนินการจำเป็นต้องใช้บรรทัดคำสั่งขนาดใหญ่ซึ่งมีค่าที่รวบรวมจากทรัพยากร Dependency แบบสกรรม ตัวอย่างเช่น บรรทัดคำสั่ง Linker อาจแสดงไฟล์ออบเจ็กต์ทุกไฟล์ที่จำเป็นสำหรับไลบรารีทั้งหมดที่ลิงก์อยู่ แนวทางปฏิบัติแนะนําคือการจัดเก็บข้อมูลสกรรมกริยาดังกล่าวใน 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 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อนค่าโดยไม่มีการประมวลผลใดๆ หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น value (ดูด้านล่าง)
value default = unbound
ออบเจ็กต์ที่จะต่อท้าย ซึ่งจะแปลงเป็นสตริงโดยใช้ Conversion มาตรฐานที่กล่าวถึงข้างต้น เนื่องจากไม่มีพารามิเตอร์ map_each สำหรับฟังก์ชันนี้ value จึงควรเป็นสตริงหรือ File ต้องส่งรายการ, Tuple, Depset หรือไดเรกทอรี File ไปยัง add_all() หรือ add_joined() แทนเมธอดนี้
format string; or 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 เป็น true (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือระบบจะกรองรายการทั้งหมด) หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
values sequence; or depset; ค่าเริ่มต้น = ไม่มีการเชื่อมโยง
รายการ, กลุ่ม Tuple หรือ Depset ที่จะผนวกรายการ
map_each callable; or None; ค่าเริ่มต้น = ไม่มี
ฟังก์ชันที่แปลงแต่ละรายการเป็นสตริงหรือสตริงมากกว่า 1 รายการ ซึ่งอาจมีการประมวลผลเพิ่มเติมก่อนที่จะต่อท้าย หากไม่ได้ระบุพารามิเตอร์นี้ ระบบจะใช้ Conversion มาตรฐาน

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

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

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

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

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

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

format_each string; or None; ค่าเริ่มต้น = ไม่มี
รูปแบบสตริงที่ไม่บังคับซึ่งใช้กับแต่ละสตริงที่แสดงผลโดยฟังก์ชัน map_each สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ
before_each string; or None; default = ไม่มี
สตริงที่ไม่บังคับซึ่งควรต่อท้ายก่อนอาร์กิวเมนต์แต่ละรายการที่ได้จาก values จะต่อท้าย
omit_if_empty ค่าเริ่มต้น = True
หากเป็น "จริง" หากไม่มีอาร์กิวเมนต์ที่ได้จาก values มาต่อท้าย ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง หากเป็น "เท็จ" ชื่ออาร์กิวเมนต์และ terminate_with (หากมี) จะยังคงต่อท้ายอยู่ไม่ว่าจะมีอาร์กิวเมนต์อื่นๆ หรือไม่ก็ตาม
uniquify default = False
หากเป็น true อาร์กิวเมนต์ที่ซ้ำกันซึ่งได้มาจาก values จะถูกละเว้น เฉพาะรายการแรกของอาร์กิวเมนต์แต่ละรายการเท่านั้นที่จะยังคงอยู่ โดยปกติแล้วจะไม่จำเป็นต้องใช้ฟีเจอร์นี้ เนื่องจาก Depset จะตัดรายการที่ซ้ำออกไปอยู่แล้ว แต่การดำเนินการนี้จะมีประโยชน์หาก map_each ปล่อยสตริงเดียวกันสำหรับหลายรายการ
expand_directories default = True
หากเป็น "จริง" ระบบจะขยายไดเรกทอรีใน values เป็นรายการไฟล์แบบรวม ซึ่งจะเกิดขึ้นก่อนที่ map_each จะมีผล
terminate_with string; or None; default = ไม่มี
สตริงที่ไม่บังคับซึ่งต่อท้ายอาร์กิวเมนต์อื่นๆ ทั้งหมด ระบบจะไม่เพิ่มสตริงนี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีรายการอื่นๆ ต่อท้าย (หาก values ว่างเปล่าหรือระบบจะกรองรายการทั้งหมด)
allow_closure ค่าเริ่มต้น = เท็จ
หากเป็น "จริง" อนุญาตให้ใช้การปิดในพารามิเตอร์ฟังก์ชัน เช่น 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 เป็น True (ค่าเริ่มต้น) จะไม่มีการประมวลผลใดๆ หรือหากไม่มีสตริงที่จะผนวก แต่ omit_if_empty เป็นค่าเท็จ สตริงที่รวมจะเป็นสตริงว่างเปล่า

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
arg_name_or_values ต้องระบุ
หากมีการส่งพารามิเตอร์ตำแหน่ง 2 รายการ ระบบจะตีความว่าเป็นชื่ออาร์กิวเมนต์ ระบบจะเพิ่มชื่ออาร์กิวเมนต์ก่อนวันที่ values โดยไม่ประมวลผล ระบบจะไม่เพิ่มอาร์กิวเมนต์นี้หาก omit_if_empty เป็นจริง (ค่าเริ่มต้น) และไม่มีสตริงที่มาจาก values มารวมเข้าด้วยกัน (ซึ่งอาจเกิดขึ้นหาก values ว่างเปล่าหรือกรองรายการทั้งหมดออก) หากส่งผ่านพารามิเตอร์ตำแหน่งเพียง 1 รายการ ระบบจะตีความว่าเป็น values (ดูด้านล่าง)
values sequence; or depset; ค่าเริ่มต้น = ไม่มีการเชื่อมโยง
รายการ, Tuple หรือ Depset ที่จะเข้าร่วม
join_with ต้องระบุ
สตริงตัวคั่นที่ใช้เพื่อรวมสตริงที่ได้รับจากการใช้ map_each และ format_each ในลักษณะเดียวกับ string.join()
map_each callable; or None; default = ไม่มี
เหมือนกับ add_all
format_each string; or None; default = ไม่มี
เหมือนกับ add_all
format_joined string; or None; ค่าเริ่มต้น = ไม่มี
รูปแบบสตริงรูปแบบที่ไม่บังคับซึ่งใช้กับสตริงที่ผนวก สตริงรูปแบบต้องมีตัวยึดตำแหน่ง "%s" 1 รายการ
omit_if_empty ค่าเริ่มต้น = จริง
หากเป็น "จริง" หากไม่มีสตริงที่ต้องรวมเข้าด้วยกัน (อาจเป็นเพราะ values ว่างเปล่าหรือทุกรายการถูกกรองออก) ระบบจะระงับการประมวลผลเพิ่มเติมทั้งหมดและบรรทัดคำสั่งจะไม่เปลี่ยนแปลง ถ้าเป็น "เท็จ" แม้ว่าจะไม่มีสตริงใดๆ ที่จะมารวมเข้าด้วยกัน จะมีการเพิ่มอาร์กิวเมนต์ 2 ตัวต่อท้าย นั่นคือชื่ออาร์กิวเมนต์ตามด้วยสตริงว่าง (ซึ่งเป็นการรวมเชิงตรรกะของสตริงที่เป็น 0)
uniquify default = False
เหมือนกับ add_all
expand_directories default = True
เหมือนกับ add_all
allow_closure default = False
เหมือนกับ add_all

set_param_file_format

Args Args.set_param_file_format(format)

ตั้งค่ารูปแบบไฟล์ของพารามิเตอร์ หากใช้

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
format ต้องระบุ
ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
  • "multiline": แต่ละรายการ (ชื่ออาร์กิวเมนต์หรือค่า) จะเขียนแบบคำต่อคำลงในไฟล์ param โดยมีอักขระขึ้นบรรทัดใหม่ตามหลัง
  • "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 default = False
ระบุว่าจะกระจายอาร์กิวเมนต์ไปยังไฟล์พารามิเตอร์เสมอหรือไม่ หากเป็น "เท็จ" Bazel จะตัดสินว่าจะต้องแยกอาร์กิวเมนต์ตามระบบและความยาวอาร์กิวเมนต์หรือไม่