อาร์กส์

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

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

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

Args สร้างขึ้นโดยการเรียกใช้ ctx.actions.args() โดยส่งเป็นพารามิเตอร์ arguments ของ ctx.actions.run() หรือ ctx.actions.run_shell() ได้ การเปลี่ยนแปลงแต่ละครั้งของออบเจ็กต์ Args จะต่อท้ายค่าไปยังบรรทัดคำสั่งสุดท้าย

ฟีเจอร์ map_each ช่วยให้คุณปรับแต่งวิธีแปลงรายการเป็นสตริงได้ หากคุณไม่ได้ระบุฟังก์ชัน map_each Conversion มาตรฐานจะเป็นดังนี้

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

# 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],
  ...
)

สมาชิก

• เพิ่ม
• add_all
• add_joined
• set_param_file_format
• use_param_file

เพิ่ม

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

พารามิเตอร์

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

พารามิเตอร์

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 เป็นเท็จ สตริงที่รวมจะเป็นสตริงว่าง

พารามิเตอร์

set_param_file_format

Args Args.set_param_file_format(format)

พารามิเตอร์

use_param_file

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

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

พารามิเตอร์