ไฟล์ .bzl

ต่อคืน · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7
เมธอดส่วนกลางที่ใช้ได้ในไฟล์ .bzl ทั้งหมด

สมาชิก

analysis_test_transition

transition analysis_test_transition(settings)

สร้างการเปลี่ยนการกำหนดค่าที่จะใช้กับทรัพยากร Dependency ของกฎการวิเคราะห์-การทดสอบ การเปลี่ยนนี้จะใช้ได้กับแอตทริบิวต์ของกฎที่มี analysis_test = True เท่านั้น กฎดังกล่าวมีความสามารถที่จำกัด (เช่น ขนาดของแผนผังการอ้างอิงจะถูกจำกัด) ดังนั้นการเปลี่ยนฉากที่สร้างขึ้นโดยใช้ฟังก์ชันนี้จึงมีขอบเขตที่จำกัดเมื่อเทียบกับการเปลี่ยนฉากที่สร้างขึ้นโดยใช้ transition()

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

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
settings dict; required
พจนานุกรมที่มีข้อมูลเกี่ยวกับการตั้งค่าการกำหนดค่าซึ่งควรตั้งค่าโดยการเปลี่ยนการกำหนดค่านี้ คีย์คือป้ายกำกับการตั้งค่าบิลด์ และค่าคือค่าใหม่หลังการเปลี่ยนผ่าน การตั้งค่าอื่นๆ ทั้งหมดจะไม่มีการเปลี่ยนแปลง ใช้เพื่อประกาศการตั้งค่าการกำหนดค่าที่เฉพาะเจาะจงซึ่งการทดสอบการวิเคราะห์กำหนดให้ตั้งค่าเพื่อให้ผ่าน

เฉพาะด้าน

Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])

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

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation function; required
ฟังก์ชัน Starlark ที่ใช้แง่มุมนี้ โดยมีพารามิเตอร์ 2 รายการ ได้แก่ Target (เป้าหมายที่จะใช้แง่มุม) และ ctx (บริบทของกฎที่สร้างเป้าหมายจาก) แอตทริบิวต์ของเป้าหมายจะพร้อมใช้งานผ่านช่อง ctx.rule ระบบจะประเมินฟังก์ชันนี้ในระหว่างระยะการวิเคราะห์สําหรับการใช้แง่มุมแต่ละอย่างกับเป้าหมาย
attr_aspects ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อแอตทริบิวต์ แง่มุมจะแพร่กระจายไปตามการขึ้นต่อกันที่ระบุไว้ในแอตทริบิวต์ของเป้าหมายที่มีชื่อเหล่านี้ ค่าที่พบบ่อยในที่นี้ ได้แก่ deps และ exports รายการยังอาจมีสตริงเดียว "*" เพื่อเผยแพร่ตามการขึ้นต่อกันทั้งหมดของเป้าหมาย
toolchains_aspects sequence; ค่าเริ่มต้นคือ []
รายการประเภทเชนเครื่องมือ แง่มุมจะแพร่กระจายไปยัง Toolchain เป้าหมายที่ตรงกับประเภท Toolchain เหล่านี้
attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมที่ประกาศแอตทริบิวต์ทั้งหมดของลักษณะ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ เช่น attr.label หรือ attr.string (ดูโมดูล attr) แอตทริบิวต์ของแง่มุมพร้อมใช้งานกับฟังก์ชันการติดตั้งใช้งานเป็นฟิลด์ของพารามิเตอร์ ctx

แอตทริบิวต์โดยนัยที่ขึ้นต้นด้วย _ ต้องมีค่าเริ่มต้นและมีประเภทเป็น label หรือ label_list

แอตทริบิวต์ที่ชัดเจนต้องมีประเภท string และต้องใช้ข้อจำกัด values แอตทริบิวต์ที่ชัดเจนจะจำกัดแง่มุมให้ใช้ได้เฉพาะกับกฎที่มีแอตทริบิวต์ที่มีชื่อ ประเภท และค่าที่ถูกต้องเดียวกันตามข้อจำกัด

แอตทริบิวต์ที่ประกาศจะแปลง None เป็นค่าเริ่มต้น
required_providers sequence; ค่าเริ่มต้นคือ []
แอตทริบิวต์นี้ช่วยให้แง่มุมจำกัดการเผยแพร่เฉพาะเป้าหมายที่มีกฎโฆษณาผู้ให้บริการที่จำเป็น ค่าต้องเป็นรายการที่มีผู้ให้บริการแต่ละรายหรือรายการของผู้ให้บริการ แต่ไม่ใช่ทั้ง 2 อย่าง เช่น [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] เป็นค่าที่ถูกต้อง แต่ [FooInfo, BarInfo, [BazInfo, QuxInfo]] ไม่ถูกต้อง

ระบบจะแปลงรายการผู้ให้บริการที่ไม่ได้ซ้อนกันเป็นรายการที่มีรายการผู้ให้บริการ 1 รายการโดยอัตโนมัติ กล่าวคือ ระบบจะแปลง [FooInfo, BarInfo] เป็น [[FooInfo, BarInfo]] โดยอัตโนมัติ

หากต้องการให้เป้าหมายของกฎบางอย่าง (เช่น some_rule) ปรากฏต่อแง่มุมหนึ่ง some_rule ต้องโฆษณาผู้ให้บริการทั้งหมดจากรายการผู้ให้บริการที่จำเป็นอย่างน้อย 1 รายการ ตัวอย่างเช่น หาก required_providers ของแง่มุมเป็น [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] แง่มุมนี้จะเห็นเป้าหมาย some_rule ก็ต่อเมื่อ some_rule ระบุ FooInfo หรือ BarInfo หรือทั้ง BazInfo และ QuxInfo

required_aspect_providers sequence; ค่าเริ่มต้นคือ []
แอตทริบิวต์นี้ช่วยให้แง่มุมนี้ตรวจสอบแง่มุมอื่นๆ ได้ ค่าต้องเป็นรายการที่มีผู้ให้บริการแต่ละรายหรือรายการของผู้ให้บริการ แต่ไม่ใช่ทั้ง 2 อย่าง เช่น [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] เป็นค่าที่ถูกต้อง แต่ [FooInfo, BarInfo, [BazInfo, QuxInfo]] ไม่ถูกต้อง

ระบบจะแปลงรายการผู้ให้บริการที่ไม่ได้ซ้อนกันเป็นรายการที่มีรายการผู้ให้บริการ 1 รายการโดยอัตโนมัติ กล่าวคือ ระบบจะแปลง [FooInfo, BarInfo] เป็น [[FooInfo, BarInfo]] โดยอัตโนมัติ

หากต้องการให้แง่มุมอื่น (เช่น other_aspect) มองเห็นแง่มุมนี้ other_aspect ต้องระบุผู้ให้บริการทั้งหมดจากรายการอย่างน้อย 1 รายการ ในตัวอย่างของ [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] มุมมองนี้จะเห็น other_aspect ก็ต่อเมื่อ other_aspect ระบุ FooInfo หรือ BarInfo หรือทั้ง BazInfo และ QuxInfo

provides sequence ค่าเริ่มต้นคือ []
รายการผู้ให้บริการที่ฟังก์ชันการติดตั้งใช้งานต้องส่งคืน

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

แต่ละองค์ประกอบของรายการคือออบเจ็กต์ *Info ที่ provider() ส่งคืน ยกเว้นว่าผู้ให้บริการเดิมจะแสดงด้วยชื่อสตริงแทน เมื่อใช้เป้าหมายของกฎเป็นทรัพยากร Dependency สำหรับเป้าหมายที่ประกาศผู้ให้บริการที่จำเป็น คุณไม่จำเป็นต้องระบุผู้ให้บริการที่นี่ เพียงแค่ฟังก์ชันการติดตั้งใช้งานแสดงผลก็เพียงพอแล้ว อย่างไรก็ตาม เราขอแนะนำให้ระบุแม้ว่าจะไม่จำเป็นก็ตาม อย่างไรก็ตาม ฟิลด์ required_providers ของลักษณะกำหนดให้ต้องระบุผู้ให้บริการที่นี่

requires ลำดับของAspect ค่าเริ่มต้นคือ []
รายการของ Aspect ที่ต้องเผยแพร่ก่อน Aspect นี้
fragments ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อของส่วนการกำหนดค่าที่แง่มุมต้องการในการกำหนดค่าเป้าหมาย
host_fragments ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อของส่วนการกำหนดค่าที่แง่มุมต้องการในการกำหนดค่าโฮสต์
toolchains sequence; ค่าเริ่มต้นคือ []
หากตั้งค่าไว้ ชุดเครื่องมือที่แง่มุมนี้ต้องการ รายการอาจมีออบเจ็กต์ String, Label หรือ StarlarkToolchainTypeApi ในการผสมผสานใดก็ได้ ระบบจะค้นหา Toolchain โดยการตรวจสอบแพลตฟอร์มปัจจุบัน และจะส่งให้กับการติดตั้งใช้งาน Aspect ผ่าน ctx.toolchain
incompatible_use_toolchain_transition bool; ค่าเริ่มต้นคือ False
เลิกใช้งานแล้ว ไม่ได้ใช้แล้วและควรนำออก
doc สตริง หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของ Aspect ที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้
apply_to_generating_rules bool; ค่าเริ่มต้นคือ False
หากเป็นจริง เมื่อใช้กับไฟล์เอาต์พุต ลักษณะจะใช้กับกฎการสร้างของไฟล์เอาต์พุตแทน

ตัวอย่างเช่น สมมติว่า Aspect เผยแพร่แบบทรานซิทีฟผ่านแอตทริบิวต์ `deps` และใช้กับเป้าหมาย `alpha` สมมติว่า `alpha` มี `deps = [':beta_output']` โดยที่ `beta_output` เป็นเอาต์พุตที่ประกาศของเป้าหมาย `beta` สมมติว่า `beta` มีเป้าหมาย `charlie` เป็นหนึ่งใน `deps` หาก `apply_to_generating_rules=True` สำหรับ Aspect แสดงว่า Aspect จะเผยแพร่ผ่าน `alpha`, `beta` และ `charlie` หากเป็น False แสดงว่า Aspect จะเผยแพร่ไปยัง `alpha` เท่านั้น

โดยค่าเริ่มต้นจะเป็นเท็จ
exec_compatible_with ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการข้อจำกัดในแพลตฟอร์มการดำเนินการที่มีผลกับอินสแตนซ์ทั้งหมดของแง่มุมนี้
exec_groups dict หรือ None ค่าเริ่มต้นคือ None
พจนานุกรมของชื่อกลุ่มการดำเนินการ (สตริง) ไปยัง exec_groups หากตั้งค่าไว้ จะอนุญาตให้ Aspect เรียกใช้การดำเนินการในแพลตฟอร์มการดำเนินการหลายแพลตฟอร์มภายในอินสแตนซ์เดียว ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบเกี่ยวกับกลุ่มการดำเนินการ
subrules ลำดับของกฎย่อย ค่าเริ่มต้นคือ []
การทดลอง: รายการกฎย่อยที่ใช้โดยแง่มุมนี้

configuration_field

LateBoundDefault configuration_field(fragment, name)

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

ตัวอย่างการใช้งาน

การกำหนดแอตทริบิวต์ของกฎ 

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

การเข้าถึงในการใช้กฎ: 

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
fragment string; required
ชื่อของส่วนการกำหนดค่าที่มีค่าที่ผูกภายหลัง
name string; required
ชื่อของค่าที่จะรับจากส่วนการกำหนดค่า

depset

depset depset(direct=None, order="default", *, transitive=None)

สร้าง depset พารามิเตอร์ direct คือรายการองค์ประกอบโดยตรงของ depset และพารามิเตอร์ transitive คือรายการ depset ที่องค์ประกอบจะกลายเป็นองค์ประกอบโดยอ้อมของ depset ที่สร้างขึ้น ลำดับที่องค์ประกอบจะแสดงเมื่อแปลงชุดทรัพยากร Dependency เป็นรายการจะระบุโดยพารามิเตอร์ order ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมของ Depset

องค์ประกอบทั้งหมด (โดยตรงและโดยอ้อม) ของชุดการพึ่งพาต้องเป็นประเภทเดียวกันตามที่ได้รับจากนิพจน์ type(x)

เนื่องจากระบบใช้ชุดที่อิงตามแฮชเพื่อกำจัดรายการที่ซ้ำกันระหว่างการวนซ้ำ องค์ประกอบทั้งหมดของ DepSet จึงควรแฮชได้ อย่างไรก็ตาม ปัจจุบันระบบไม่ได้ตรวจสอบตัวแปรนี้อย่างสม่ำเสมอในตัวสร้างทั้งหมด ใช้แฟล็ก --incompatible_always_check_depset_elements เพื่อเปิดใช้การตรวจสอบที่สอดคล้องกัน ซึ่งจะเป็นลักษณะการทำงานเริ่มต้นในรุ่นต่อๆ ไป ดูปัญหา 10313

นอกจากนี้ ปัจจุบันองค์ประกอบต้องเปลี่ยนแปลงไม่ได้ แต่ข้อจำกัดนี้จะผ่อนปรนในอนาคต

ลำดับของ Depset ที่สร้างขึ้นควรเข้ากันได้กับลำดับของ Depset transitive "default" ใช้ร่วมกับคำสั่งซื้ออื่นๆ ได้ แต่คำสั่งซื้ออื่นๆ จะใช้ร่วมกันเองได้เท่านั้น

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
direct sequence หรือ None ค่าเริ่มต้นคือ None
รายการองค์ประกอบ direct ของ depset
order string; ค่าเริ่มต้นคือ "default"
กลยุทธ์การข้ามสำหรับ depset ใหม่ ดูค่าที่เป็นไปได้ที่นี่
transitive ลำดับของ depset หรือ None ค่าเริ่มต้นคือ None
รายการ depset ที่องค์ประกอบจะกลายเป็นองค์ประกอบทางอ้อมของ depset

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[])

สร้างกลุ่มการดำเนินการซึ่งใช้สร้างการดำเนินการสำหรับแพลตฟอร์มการดำเนินการที่เฉพาะเจาะจงได้ในระหว่างการใช้กฎ

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
toolchains sequence; ค่าเริ่มต้นคือ []
ชุดเครื่องมือที่กลุ่มการดำเนินการนี้ต้องการ รายการอาจมีออบเจ็กต์ String, Label หรือ StarlarkToolchainTypeApi ในการผสมผสานใดก็ได้
exec_compatible_with ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการข้อจำกัดบนแพลตฟอร์มการดำเนินการ

exec_transition

transition exec_transition(implementation, inputs, outputs)

transition() เวอร์ชันเฉพาะที่ใช้เพื่อกำหนดการเปลี่ยนเส้นทาง exec ดูแนวทางปฏิบัติแนะนำได้ในเอกสารประกอบ (หรือการใช้งาน) ใช้ได้จาก Bazel Builtins เท่านั้น

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation callable; required
inputs ลำดับของสตริง ต้องระบุ
outputs ลำดับของสตริง ต้องระบุ

มาโคร

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

กำหนดมาโครเชิงสัญลักษณ์ ซึ่งอาจเรียกใช้ในไฟล์ BUILD หรือมาโคร (เดิมหรือเชิงสัญลักษณ์) เพื่อกำหนดเป้าหมาย ซึ่งอาจมีหลายเป้าหมาย

ต้องกำหนดค่าที่แสดงผลโดย macro(...) ให้กับตัวแปรส่วนกลางในไฟล์ .bzl ชื่อของตัวแปรส่วนกลางจะเป็นชื่อของสัญลักษณ์มาโคร

ดูคำแนะนำแบบละเอียดเกี่ยวกับวิธีใช้มาโครสัญลักษณ์ได้ที่มาโคร

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation function; required
ฟังก์ชัน Starlark ที่ใช้มาโครนี้ ระบบจะส่งค่าของแอตทริบิวต์ของมาโครไปยัง ฟังก์ชันการใช้งานเป็นอาร์กิวเมนต์คีย์เวิร์ด ฟังก์ชันการใช้งานต้องมีพารามิเตอร์ที่มีชื่ออย่างน้อย 2 รายการ ได้แก่ name และ visibility และหากมาโครรับช่วงแอตทริบิวต์ (ดู inherit_attrs ด้านล่าง) มาโครต้องมีพารามิเตอร์คีย์เวิร์ดที่เหลือ **kwargs

ตามธรรมเนียมแล้ว ฟังก์ชันการติดตั้งใช้งานควรมีพารามิเตอร์ที่มีชื่อสำหรับแอตทริบิวต์ใดๆ ที่มาโครต้องตรวจสอบ แก้ไข หรือส่งไปยังเป้าหมายที่ไม่ใช่ "หลัก" ในขณะที่แอตทริบิวต์ "กลุ่ม" ที่สืบทอดมา ซึ่งจะส่งไปยังเป้าหมาย "หลัก" โดยไม่มีการเปลี่ยนแปลงจะส่งเป็น **kwargs

ฟังก์ชันการติดตั้งใช้งานต้องไม่แสดงผลค่า แต่ฟังก์ชันการใช้งานจะประกาศเป้าหมายโดยการเรียกสัญลักษณ์กฎหรือมาโครแทน

ชื่อของเป้าหมายหรือมาโครสัญลักษณ์ภายในที่ประกาศโดยมาโครสัญลักษณ์ (รวมถึงฟังก์ชัน Starlark ที่ฟังก์ชันการใช้งานของมาโครเรียกแบบทรานซิทีฟ) ต้องเท่ากับ name (ซึ่งเรียกว่าเป้าหมาย "หลัก") หรือขึ้นต้นด้วย name ตามด้วยอักขระคั่น ("_", "-" หรือ ".") และคำต่อท้ายสตริง (อนุญาตให้ประกาศเป้าหมายที่ละเมิดรูปแบบการตั้งชื่อนี้ได้ แต่จะสร้าง กำหนดค่า หรือขึ้นอยู่กับเป้าหมายดังกล่าวไม่ได้)

โดยค่าเริ่มต้น เป้าหมายที่ประกาศโดยมาโครสัญลักษณ์ (รวมถึงฟังก์ชัน Starlark ใดๆ ที่ฟังก์ชันการใช้งานของมาโครเรียกใช้แบบทรานซิทีฟ) จะมองเห็นได้เฉพาะในแพ็กเกจที่มีไฟล์ .bzl ที่กำหนดมาโคร หากต้องการประกาศเป้าหมายที่มองเห็นได้ภายนอก รวมถึงผู้เรียกใช้ มาโครสัญลักษณ์ ฟังก์ชันการติดตั้งใช้งานต้องตั้งค่า visibility อย่างเหมาะสม โดยปกติแล้วคือการส่ง visibility = visibility ไปยังสัญลักษณ์กฎหรือมาโครที่เรียกใช้

API ต่อไปนี้ไม่พร้อมใช้งานภายในฟังก์ชันการติดตั้งใช้งานมาโครและฟังก์ชัน Starlark ใดๆ ที่เรียกใช้แบบทรานซิทีฟ

attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมของแอตทริบิวต์ที่มาโครนี้รองรับ ซึ่งคล้ายกับ rule.attrs คีย์คือชื่อแอตทริบิวต์ และค่าคือออบเจ็กต์แอตทริบิวต์ เช่น attr.label_list(...) (ดูโมดูล attr ) หรือ None None หมายถึงมาโครไม่มีแอตทริบิวต์ชื่อนั้น แม้ว่ามาโครจะรับค่าแอตทริบิวต์ผ่าน inherit_attrs (ดูด้านล่าง)

แอตทริบิวต์พิเศษ name ได้รับการประกาศล่วงหน้าแล้วและต้องไม่รวมอยู่ในพจนานุกรม ชื่อแอตทริบิวต์ visibility เป็นชื่อที่สงวนไว้และต้องไม่รวมอยู่ใน พจนานุกรม

แอตทริบิวต์ที่ชื่อขึ้นต้นด้วย _ เป็นแอตทริบิวต์ส่วนตัว ซึ่งจะส่งที่เว็บไซต์การเรียกของกฎไม่ได้ คุณกำหนดค่าเริ่มต้นให้กับแอตทริบิวต์ดังกล่าวได้ (เช่น ใน attr.label(default="//pkg:foo")) เพื่อสร้างการอ้างอิงโดยนัยในป้ายกำกับ

เราจำกัดจำนวนแอตทริบิวต์ที่ประกาศได้เพื่อจำกัดการใช้หน่วยความจำ

inherit_attrs กฎ หรือ มาโคร หรือ สตริง หรือ None ค่าเริ่มต้นคือ None
สัญลักษณ์กฎ สัญลักษณ์มาโคร หรือชื่อของรายการแอตทริบิวต์ทั่วไปในตัว (ดูด้านล่าง) ซึ่งมาโครควรรับค่าแอตทริบิวต์

หากตั้งค่า inherit_attrs เป็นสตริง "common" มาโครจะรับช่วง คำจำกัดความแอตทริบิวต์กฎทั่วไป ที่ใช้โดยกฎ Starlark ทั้งหมด

โปรดทราบว่าหากไม่ได้กำหนดค่าที่แสดงผลของ rule() หรือ macro() ให้กับตัวแปรส่วนกลางในไฟล์ .bzl ค่าดังกล่าวจะไม่ได้ลงทะเบียนเป็นสัญลักษณ์กฎหรือมาโคร และด้วยเหตุนี้จึงใช้กับ inherit_attrs ไม่ได้

กลไกการรับค่าจะทำงานดังนี้

  1. แอตทริบิวต์พิเศษ name และ visibility จะไม่ได้รับการสืบทอด
  2. แอตทริบิวต์ที่ซ่อนอยู่ (แอตทริบิวต์ที่มีชื่อขึ้นต้นด้วย "_") จะไม่ได้รับการสืบทอด
  3. แอตทริบิวต์ที่มีชื่อกำหนดไว้แล้วในattrsพจนานุกรมจะไม่ได้รับการสืบทอด (รายการในattrsจะมีลำดับความสำคัญสูงกว่า โปรดทราบว่าอาจตั้งค่ารายการเป็น Noneเพื่อให้แน่ใจว่าจะไม่มีการกำหนดแอตทริบิวต์ที่มีชื่อนั้นในมาโคร)
  4. แอตทริบิวต์อื่นๆ ทั้งหมดจะรับค่ามาจากกฎหรือมาโคร และจะผสานรวมเข้ากับ attrs dict อย่างมีประสิทธิภาพ

เมื่อมีการรับค่าแอตทริบิวต์ที่ไม่บังคับ ค่าเริ่มต้นของแอตทริบิวต์จะถูกเขียนทับ เป็น None ไม่ว่าค่าที่ระบุในกฎหรือมาโครเดิมจะเป็นอะไรก็ตาม ซึ่งจะช่วยให้มั่นใจได้ว่าเมื่อมาโครส่งต่อค่าของแอตทริบิวต์ไปยังอินสแตนซ์ของกฎหรือมาโครที่ห่อหุ้มไว้ เช่น โดยการส่ง **kwargs ที่ไม่ได้แก้ไข ค่าที่ไม่มีในการเรียกมาโครด้านนอกจะไม่มีในการเรียกกฎหรือมาโครด้านในด้วย (เนื่องจากการส่ง None ไปยังแอตทริบิวต์จะถือว่าเหมือนกับการละเว้นแอตทริบิวต์) ขั้นตอนนี้มีความสําคัญเนื่องจากการละเว้นแอตทริบิวต์มีความหมายแตกต่างเล็กน้อยจากการส่งค่าเริ่มต้นที่เห็นได้ชัด โดยเฉพาะอย่างยิ่ง ระบบจะไม่แสดงแอตทริบิวต์ที่ละเว้นในรูปแบบเอาต์พุตบางรูปแบบของ bazel query และค่าเริ่มต้นที่คำนวณจะทำงานเมื่อมีการละเว้นค่าเท่านั้น หากมาโครต้องตรวจสอบหรือแก้ไขแอตทริบิวต์ที่รับค่ามา เช่น เพื่อเพิ่มค่าลงในแอตทริบิวต์ tags ที่รับค่ามา คุณต้องตรวจสอบว่าได้จัดการกรณี None ในฟังก์ชันการใช้งานของมาโคร

เช่น มาโครต่อไปนี้จะรับช่วงแอตทริบิวต์ทั้งหมดจาก native.cc_library ยกเว้น cxxopts (ซึ่งนำออกจากรายการแอตทริบิวต์) และ copts (ซึ่งกำหนดคำจำกัดความใหม่) นอกจากนี้ ยังตรวจสอบNone ค่าเริ่มต้นของแอตทริบิวต์ tags ที่รับค่ามาก่อนที่จะเพิ่มแท็กเพิ่มเติมด้วย 

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

หากตั้งค่า inherit_attrs ฟังก์ชันการติดตั้งใช้งานของมาโครต้องมีพารามิเตอร์คีย์เวิร์ดที่เหลือ**kwargs

ตามธรรมเนียมแล้ว มาโครควรส่งแอตทริบิวต์ที่รับช่วงมาซึ่งไม่ได้มีการลบล้างไปยังสัญลักษณ์กฎหรือมาโคร "หลัก" ที่มาโครกำลังห่อหุ้มอยู่โดยไม่มีการเปลี่ยนแปลง โดยปกติแล้ว แอตทริบิวต์ที่รับค่ามาส่วนใหญ่จะไม่มีพารามิเตอร์ในรายการพารามิเตอร์ของฟังก์ชันการติดตั้งใช้งาน และจะส่งผ่านทาง **kwargs โดยตรง ฟังก์ชันการใช้งานอาจสะดวกที่จะมีพารามิเตอร์ที่ชัดเจน สำหรับแอตทริบิวต์ที่รับค่ามาบางอย่าง (โดยทั่วไปคือ tags และ testonly) หากมาโครต้องส่งแอตทริบิวต์เหล่านั้นไปยังเป้าหมายทั้ง "หลัก" และที่ไม่ใช่ "หลัก" แต่หากมาโครต้องตรวจสอบหรือจัดการแอตทริบิวต์เหล่านั้นด้วย คุณต้องระมัดระวัง ในการจัดการค่าเริ่มต้น None ของแอตทริบิวต์ที่รับค่ามาซึ่งไม่บังคับ

finalizer bool ค่าเริ่มต้นคือ False
ไม่ว่ามาโครนี้จะเป็นตัวสรุปกฎหรือไม่ ซึ่งเป็นมาโครที่ระบบจะประเมินเมื่อสิ้นสุดการโหลดแพ็กเกจ ไม่ว่ามาโครจะอยู่ที่ใดในไฟล์ BUILD หลังจากที่กำหนดเป้าหมายที่ไม่ใช่ตัวสรุปทั้งหมดแล้ว

ไม่เหมือนกับมาโครสัญลักษณ์ทั่วไป ตัวสรุปกฎอาจเรียกใช้ native.existing_rule() และ native.existing_rules() เพื่อค้นหา ชุดเป้าหมายกฎที่ไม่ใช่ตัวสรุปที่กำหนดไว้ในแพ็กเกจปัจจุบัน โปรดทราบว่า native.existing_rule() และ native.existing_rules() ไม่สามารถเข้าถึง เป้าหมายที่กำหนดโดยตัวสรุปกฎใดๆ รวมถึงตัวสรุปกฎนี้

doc สตริง หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของมาโครที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

สร้างส่วนขยายโมดูลใหม่ จัดเก็บไว้ในค่าส่วนกลางเพื่อให้ส่งออกและใช้ในไฟล์ MODULE.bazel ได้ด้วย use_extension

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation callable; required
ฟังก์ชันที่ใช้ส่วนขยายโมดูลนี้ ต้องใช้พารามิเตอร์เดียวคือ module_ctx ฟังก์ชันนี้จะเรียกใช้ 1 ครั้งเมื่อเริ่มต้นการสร้างเพื่อกำหนดชุดที่เก็บที่พร้อมใช้งาน
tag_classes dict; ค่าเริ่มต้นคือ {}
พจนานุกรมเพื่อประกาศคลาสแท็กทั้งหมดที่ส่วนขยายใช้ โดยจะแมปจากชื่อของคลาสแท็กไปยังออบเจ็กต์ tag_class
doc string หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของส่วนขยายโมดูลที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้
environ ลำดับของสตริง ค่าเริ่มต้นคือ []
ระบุรายการตัวแปรสภาพแวดล้อมที่ส่วนขยายโมดูลนี้ขึ้นอยู่กับ หากตัวแปรสภาพแวดล้อมในรายการนั้นมีการเปลี่ยนแปลง ระบบจะประเมินส่วนขยายอีกครั้ง
os_dependent bool; ค่าเริ่มต้นคือ False
ระบุว่าส่วนขยายนี้ขึ้นอยู่กับระบบปฏิบัติการหรือไม่
arch_dependent bool; ค่าเริ่มต้นคือ False
ระบุว่าส่วนขยายนี้ขึ้นอยู่กับสถาปัตยกรรมหรือไม่

provider

unknown provider(doc=None, *, fields=None, init=None)

กำหนดสัญลักษณ์ผู้ให้บริการ ต้องจัดเก็บผลลัพธ์ของฟังก์ชันนี้ในค่าส่วนกลาง ผู้ให้บริการอาจได้รับการสร้างอินสแตนซ์โดยการเรียกใช้ หรือใช้โดยตรงเป็นคีย์สําหรับการดึงอินสแตนซ์ของผู้ให้บริการนั้นจากเป้าหมาย ตัวอย่าง:
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

ดูคำแนะนำแบบละเอียดเกี่ยวกับวิธีใช้ผู้ให้บริการได้ที่กฎ (ผู้ให้บริการ)

แสดงผลค่าที่เรียกใช้ได้ Provider หากไม่ได้ระบุ init

หากระบุ init จะแสดงผลทูเพิลของ 2 องค์ประกอบ ได้แก่ ค่าที่เรียกใช้ได้ของ Provider และค่าที่เรียกใช้ได้ของตัวสร้างดิบ ดูรายละเอียดได้ที่ กฎ (การเริ่มต้นที่กำหนดเองของผู้ให้บริการที่กำหนดเอง) และการอภิปรายเกี่ยวกับพารามิเตอร์ init ด้านล่าง

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
doc สตริง หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของผู้ให้บริการที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้
fields ลำดับของสตริง หรือ dict หรือ None ค่าเริ่มต้นคือ None
หากระบุ จะจำกัดชุดฟิลด์ที่อนุญาต
ค่าที่เป็นไปได้มีดังนี้
  • รายการช่อง:
    provider(fields = ['a', 'b'])

  • ชื่อฟิลด์พจนานุกรม -> เอกสารประกอบ:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
ไม่จำเป็นต้องกรอกข้อมูลครบทุกช่อง
init callable หรือ None; ค่าเริ่มต้นคือ None
การเรียกกลับที่ไม่บังคับสำหรับการประมวลผลล่วงหน้าและการตรวจสอบค่าฟิลด์ของผู้ให้บริการในระหว่างการเริ่มต้น หากระบุ init provider() จะแสดงผลทูเพิลที่มี 2 องค์ประกอบ ได้แก่ สัญลักษณ์ของผู้ให้บริการปกติและตัวสร้างดิบ

คำอธิบายที่แม่นยำมีดังนี้ โปรดดูกฎ (การเริ่มต้นผู้ให้บริการที่กำหนดเอง) เพื่อดูการสนทนาและกรณีการใช้งานที่เข้าใจง่าย

ให้ P เป็นสัญลักษณ์ของผู้ให้บริการที่สร้างขึ้นโดยการเรียก provider() ในเชิงแนวคิด ระบบจะสร้างอินสแตนซ์ของ P โดยการเรียกฟังก์ชันตัวสร้างเริ่มต้น c(*args, **kwargs) ซึ่งจะทำสิ่งต่อไปนี้

  • หาก args ไม่ว่าง ระบบจะแสดงข้อผิดพลาด
  • หากมีการระบุพารามิเตอร์ fields เมื่อมีการเรียกใช้ provider() และหาก kwargs มีคีย์ที่ไม่ได้แสดงใน fields จะเกิดข้อผิดพลาดขึ้น
  • ไม่เช่นนั้น c จะแสดงผลอินสแตนซ์ใหม่ซึ่งมีฟิลด์ชื่อ k ที่มีค่า v สำหรับแต่ละรายการ k: v ใน kwargs
ในกรณีที่initไม่ได้ระบุCallback การเรียกใช้สัญลักษณ์ P เองจะทำหน้าที่เป็นการเรียกใช้ฟังก์ชันตัวสร้างเริ่มต้น c กล่าวคือ P(*args, **kwargs) จะแสดงผล c(*args, **kwargs) ตัวอย่างเช่น
MyInfo = provider()
m = MyInfo(foo = 1)
จะทำให้ m เป็นอินสแตนซ์ MyInfo ที่มี m.foo == 1 โดยตรง

แต่ในกรณีที่ระบุ init ไว้ การเรียกใช้ P(*args, **kwargs) จะทำตามขั้นตอนต่อไปนี้แทน

  1. ระบบจะเรียกใช้ฟังก์ชันเรียกกลับเป็น init(*args, **kwargs) ซึ่งก็คือมีอาร์กิวเมนต์ตำแหน่งและคีย์เวิร์ดเหมือนกับที่ส่งไปยัง P ทุกประการ
  2. ค่าที่ฟังก์ชัน init แสดงผลควรเป็นพจนานุกรม d ซึ่งมีคีย์เป็นสตริงชื่อฟิลด์ ไม่เช่นนั้นจะเกิดข้อผิดพลาด
  3. ระบบจะสร้างอินสแตนซ์ใหม่ของ P ราวกับว่าเป็นการเรียกตัวสร้างเริ่มต้นที่มีรายการของ d เป็นอาร์กิวเมนต์คีย์เวิร์ด ดังใน c(**d)

หมายเหตุ: ขั้นตอนข้างต้นหมายความว่าจะเกิดข้อผิดพลาดหาก *args หรือ **kwargs ไม่ตรงกับลายเซ็นของ init หรือการประเมินเนื้อหาของ init ล้มเหลว (อาจตั้งใจผ่านการเรียกใช้ fail()) หรือหากค่าที่ส่งคืนของ init ไม่ใช่พจนานุกรมที่มีสคีมาที่คาดไว้

ด้วยวิธีนี้ init Callback จะสร้างผู้ให้บริการทั่วไปโดยอนุญาตให้ใช้การอ้างอิงตำแหน่งและตรรกะที่กำหนดเองสำหรับการประมวลผลล่วงหน้าและการตรวจสอบ แต่ไม่ได้เปิดใช้การหลีกเลี่ยงรายการ fields ที่อนุญาต

เมื่อระบุ init ค่าที่แสดงผลของ provider() จะกลายเป็นทูเพิล (P, r) โดยที่ r คือ raw constructor ในความเป็นจริงแล้ว ลักษณะการทำงานของ r ก็เหมือนกับฟังก์ชันตัวสร้างเริ่มต้น c ที่กล่าวถึงข้างต้น โดยปกติแล้ว r จะเชื่อมโยงกับตัวแปรที่มีชื่อขึ้นต้นด้วยขีดล่าง เพื่อให้เฉพาะไฟล์ .bzl ปัจจุบันเท่านั้นที่มีสิทธิ์เข้าถึงโดยตรง

MyInfo, _new_myinfo = provider(init = ...)

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)

สร้างกฎที่เก็บใหม่ จัดเก็บไว้ในค่าส่วนกลางเพื่อให้โหลดและเรียกใช้จากฟังก์ชันการติดตั้งใช้งาน module_extension() หรือใช้โดย use_repo_rule() ได้

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation callable; required
ฟังก์ชันที่ใช้กฎนี้ ต้องมีพารามิเตอร์เดียวคือ repository_ctx ระบบจะเรียกใช้ฟังก์ชันในระหว่างระยะการโหลดสำหรับอินสแตนซ์ของกฎแต่ละรายการ
attrs dict หรือ None ค่าเริ่มต้นคือ None
พจนานุกรมเพื่อประกาศแอตทริบิวต์ทั้งหมดของกฎที่เก็บ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ (ดูโมดูล attr) แอตทริบิวต์ที่ขึ้นต้นด้วย _ เป็นแอตทริบิวต์ส่วนตัว และใช้เพื่อเพิ่มการอ้างอิงโดยนัยในป้ายกำกับไปยังไฟล์ได้ (กฎของที่เก็บไม่สามารถขึ้นอยู่กับอาร์ติแฟกต์ที่สร้างขึ้น) ระบบจะเพิ่มแอตทริบิวต์ name โดยนัยและต้องไม่มีการระบุ

แอตทริบิวต์ที่ประกาศจะแปลง None เป็นค่าเริ่มต้น
local bool; ค่าเริ่มต้นคือ False
ระบุว่ากฎนี้จะดึงข้อมูลทุกอย่างจากระบบในเครื่องและควรได้รับการประเมินใหม่ทุกครั้งที่ดึงข้อมูล
environ ลำดับของสตริง ค่าเริ่มต้นคือ []
เลิกใช้งานแล้ว พารามิเตอร์นี้เลิกใช้งานแล้ว โปรดเปลี่ยนไปใช้ repository_ctx.getenv แทน
แสดงรายการตัวแปรสภาพแวดล้อมที่กฎของที่เก็บนี้ขึ้นอยู่กับ หากตัวแปรสภาพแวดล้อมในรายการนั้นมีการเปลี่ยนแปลง ระบบจะดึงข้อมูลที่เก็บอีกครั้ง
configure bool; ค่าเริ่มต้นคือ False
ระบุว่าที่เก็บจะตรวจสอบระบบเพื่อวัตถุประสงค์ในการกำหนดค่า
remotable bool; ค่าเริ่มต้นคือ False
เวอร์ชันทดลอง พารามิเตอร์นี้ยังอยู่ในขั้นทดลองและอาจมีการเปลี่ยนแปลงได้ทุกเมื่อ โปรดอย่าใช้ API นี้ อาจเปิดใช้ในเวอร์ชันทดลองได้โดยการตั้งค่า --experimental_repo_remote_exec
ใช้งานร่วมกับการดำเนินการจากระยะไกลได้
doc string หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของกฎที่เก็บที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้

กฎ

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

สร้างกฎใหม่ ซึ่งเรียกใช้ได้จากไฟล์ BUILD หรือมาโครเพื่อสร้างเป้าหมาย

ต้องกำหนดกฎให้กับตัวแปรส่วนกลางในไฟล์ .bzl โดยชื่อของตัวแปรส่วนกลางคือชื่อของกฎ

กฎทดสอบต้องมีชื่อที่ลงท้ายด้วย _test ส่วนกฎอื่นๆ ทั้งหมดต้องไม่มีคำต่อท้ายนี้ (ข้อจำกัดนี้มีผลกับกฎเท่านั้น ไม่ใช่เป้าหมายของกฎ)

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation function; required
ฟังก์ชัน Starlark ที่ใช้กฎนี้ต้องมีพารามิเตอร์ 1 รายการเท่านั้นคือ ctx ระบบจะเรียกใช้ฟังก์ชันในระหว่างขั้นตอนการวิเคราะห์สำหรับกฎแต่ละอินสแตนซ์ เข้าถึงแอตทริบิวต์ที่ผู้ใช้ระบุได้ โดยต้องสร้างการดำเนินการเพื่อสร้างเอาต์พุตที่ประกาศไว้ทั้งหมด
test bool; ค่าเริ่มต้นคือ unbound
ไม่ว่ากฎนี้จะเป็นกฎทดสอบหรือไม่ นั่นคือ ไม่ว่ากฎนี้อาจเป็นเรื่องของคำสั่ง blaze test หรือไม่ กฎการทดสอบทั้งหมดจะถือว่าเรียกใช้ได้โดยอัตโนมัติ คุณจึงไม่จำเป็น (และไม่ควร) ตั้งค่า executable = True อย่างชัดเจนสำหรับกฎการทดสอบ ค่าเริ่มต้นคือ False ดูข้อมูลเพิ่มเติมได้ที่ หน้ากฎ
attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมเพื่อประกาศแอตทริบิวต์ทั้งหมดของกฎ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ (ดูโมดูล attr) แอตทริบิวต์ที่ขึ้นต้นด้วย _ เป็นแอตทริบิวต์ส่วนตัว และใช้เพื่อเพิ่มการอ้างอิงโดยนัยในป้ายกำกับได้ ระบบจะเพิ่มแอตทริบิวต์ name โดยนัยและต้องไม่มีการระบุ ระบบจะเพิ่มแอตทริบิวต์ visibility, deprecation, tags, testonly และ features โดยอัตโนมัติและจะลบล้างไม่ได้ กฎส่วนใหญ่ต้องการแอตทริบิวต์เพียงไม่กี่รายการ เราจำกัดจำนวนแอตทริบิวต์ที่ประกาศได้เพื่อจำกัดการใช้หน่วยความจำ

แอตทริบิวต์ที่ประกาศจะแปลง None เป็นค่าเริ่มต้น
outputs dict หรือ None หรือ function ค่าเริ่มต้นคือ None
เลิกใช้งานแล้ว พารามิเตอร์นี้เลิกใช้งานแล้วและจะถูกนำออกเร็วๆ นี้ โปรดอย่าใช้ API นี้ ระบบจะปิด เมื่อใช้ Flag --incompatible_no_rule_outputs_param ใช้ Flag นี้เพื่อยืนยันว่าโค้ดของคุณทำงานได้โดยไม่พึ่งพา API ที่กำลังจะถูกนำออก
พารามิเตอร์นี้เลิกใช้งานแล้ว ย้ายข้อมูลกฎเพื่อใช้ OutputGroupInfo หรือ attr.output แทน

สคีมาสําหรับกําหนดเอาต์พุตที่ประกาศไว้ล่วงหน้า ผู้ใช้ไม่ได้ระบุป้ายกำกับสำหรับไฟล์เหล่านี้ ซึ่งแตกต่างจากแอตทริบิวต์ output และ output_list ดูข้อมูลเพิ่มเติมเกี่ยวกับเอาต์พุตที่ประกาศล่วงหน้าได้ในหน้ากฎ

ค่าของอาร์กิวเมนต์นี้อาจเป็นพจนานุกรมหรือฟังก์ชัน Callback ที่สร้างพจนานุกรม Callback ทำงานคล้ายกับแอตทริบิวต์การอ้างอิงที่คำนวณแล้ว โดยชื่อพารามิเตอร์ของฟังก์ชันจะตรงกับแอตทริบิวต์ของกฎ เช่น หากคุณส่ง outputs = _my_func พร้อมคำจำกัดความ def _my_func(srcs, deps): ... ฟังก์ชันจะมีสิทธิ์เข้าถึงแอตทริบิวต์ srcs และ deps ไม่ว่าจะระบุพจนานุกรมโดยตรงหรือผ่านฟังก์ชัน ระบบจะตีความพจนานุกรมดังนี้

แต่ละรายการในพจนานุกรมจะสร้างเอาต์พุตที่ประกาศไว้ล่วงหน้า โดยที่คีย์คือตัวระบุ และค่าคือเทมเพลตสตริงที่กำหนดป้ายกำกับของเอาต์พุต ในฟังก์ชันการใช้งานของกฎ ตัวระบุจะกลายเป็นชื่อฟิลด์ที่ใช้เพื่อเข้าถึง File ของเอาต์พุตใน ctx.outputs ป้ายกำกับของเอาต์พุตมีแพ็กเกจเดียวกับกฎ และส่วนหลังจากแพ็กเกจจะสร้างขึ้นโดยแทนที่ตัวยึดตำแหน่งแต่ละรายการในรูปแบบ "%{ATTR}" ด้วยสตริงที่สร้างจากค่าของแอตทริบิวต์ ATTR

  • ระบบจะแทนที่แอตทริบิวต์ประเภทสตริงตามตัวอักษร
  • แอตทริบิวต์ประเภทป้ายกำกับจะกลายเป็นส่วนหนึ่งของป้ายกำกับหลังจากแพ็กเกจ โดยไม่รวมนามสกุลไฟล์ เช่น ป้ายกำกับ "//pkg:a/b.c" จะกลายเป็น "a/b"
  • แอตทริบิวต์ที่พิมพ์เอาต์พุตจะกลายเป็นส่วนหนึ่งของป้ายกำกับหลังจากแพ็กเกจ รวมถึงนามสกุลไฟล์ (สำหรับตัวอย่างด้านบนคือ "a/b.c")
  • แอตทริบิวต์ประเภทรายการทั้งหมด (เช่น attr.label_list) ที่ใช้ในตัวยึดตำแหน่งจะต้องมีองค์ประกอบเดียวเท่านั้น Conversion ของแคมเปญจะเหมือนกับเวอร์ชันที่ไม่ได้อยู่ในรายการ (attr.label)
  • แอตทริบิวต์ประเภทอื่นๆ อาจไม่ปรากฏในตัวยึดตำแหน่ง
  • ตัวยึดตำแหน่งพิเศษที่ไม่ใช่แอตทริบิวต์ %{dirname} และ %{basename} จะขยายเป็นส่วนต่างๆ ของป้ายกำกับของกฎ โดยไม่รวมแพ็กเกจ เช่น ใน "//pkg:a/b.c", dirname คือ a และ basename คือ b.c

ในทางปฏิบัติ ตัวยึดตำแหน่งการแทนที่ที่พบบ่อยที่สุดคือ "%{name}" ตัวอย่างเช่น สำหรับเป้าหมายที่ชื่อ "foo" พจนานุกรมเอาต์พุต {"bin": "%{name}.exe"} จะประกาศเอาต์พุตที่ชื่อ foo.exe ไว้ล่วงหน้า ซึ่งเข้าถึงได้ในฟังก์ชันการใช้งานเป็น ctx.outputs.bin

executable bool ค่าเริ่มต้นคือ unbound
ไม่ว่ากฎนี้จะถือว่าเป็นไฟล์ที่เรียกใช้งานได้หรือไม่ นั่นคือ ไม่ว่ากฎนี้อาจเป็นหัวข้อของคำสั่ง blaze run หรือไม่ โดยค่าเริ่มต้นจะเป็น False ดูข้อมูลเพิ่มเติมได้ที่ หน้ากฎ
output_to_genfiles bool; ค่าเริ่มต้นคือ False
หากเป็นจริง ระบบจะสร้างไฟล์ในไดเรกทอรี genfiles แทนไดเรกทอรี bin อย่าตั้งค่าสถานะนี้ เว้นแต่คุณจำเป็นต้องใช้เพื่อความเข้ากันได้กับกฎที่มีอยู่ (เช่น เมื่อสร้างไฟล์ส่วนหัวสำหรับ C++)
fragments ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อของส่วนการกำหนดค่าที่กฎกำหนดในการกำหนดค่าเป้าหมาย
host_fragments ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อของส่วนการกำหนดค่าที่กฎกำหนดในการกำหนดค่าโฮสต์
_skylark_testable bool; ค่าเริ่มต้นคือ False
(ทดลอง)

หากเป็นจริง กฎนี้จะแสดงการดำเนินการเพื่อให้กฎที่ขึ้นอยู่กับกฎนี้ตรวจสอบผ่านผู้ให้บริการ Actions ผู้ให้บริการยังพร้อมให้บริการกับกฎเองด้วยการเรียกใช้ ctx.created_actions()

ซึ่งควรใช้เพื่อทดสอบลักษณะการทำงานของกฎ Starlark ในเวลาวิเคราะห์เท่านั้น เราอาจนำฟีเจอร์นี้ออกในอนาคต
toolchains sequence; ค่าเริ่มต้นคือ []
หากตั้งค่าไว้ ชุดเครื่องมือที่กฎนี้ต้องการ รายการอาจมีออบเจ็กต์ String, Label หรือ StarlarkToolchainTypeApi ในการผสมผสานใดก็ได้ ระบบจะค้นหา Toolchain โดยการตรวจสอบแพลตฟอร์มปัจจุบัน และส่งให้การติดตั้งใช้งานกฎผ่าน ctx.toolchain
incompatible_use_toolchain_transition bool; ค่าเริ่มต้นคือ False
เลิกใช้งานแล้ว ไม่ได้ใช้แล้วและควรนำออก
doc string หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของกฎที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้
provides sequence ค่าเริ่มต้นคือ []
รายการผู้ให้บริการที่ฟังก์ชันการติดตั้งใช้งานต้องส่งคืน

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

แต่ละองค์ประกอบของรายการคือออบเจ็กต์ *Info ที่ provider() ส่งคืน ยกเว้นว่าผู้ให้บริการเดิมจะแสดงด้วยชื่อสตริงแทน เมื่อใช้เป้าหมายของกฎเป็นทรัพยากร Dependency สำหรับเป้าหมายที่ประกาศผู้ให้บริการที่จำเป็น คุณไม่จำเป็นต้องระบุผู้ให้บริการที่นี่ เพียงแค่ฟังก์ชันการติดตั้งใช้งานแสดงผลก็เพียงพอแล้ว อย่างไรก็ตาม เราขอแนะนำให้ระบุแม้ว่าจะไม่จำเป็นก็ตาม อย่างไรก็ตาม ฟิลด์ required_providers ของลักษณะกำหนดให้ต้องระบุผู้ให้บริการที่นี่

dependency_resolution_rule bool; ค่าเริ่มต้นคือ False
หากตั้งค่าไว้ กฎจะเป็นการอ้างอิงผ่านแอตทริบิวต์ที่ทำเครื่องหมายว่าพร้อมใช้งานใน Materializer ด้วย แอตทริบิวต์ทั้งหมดของกฎที่มีการตั้งค่าแฟล็กนี้ต้องทำเครื่องหมายว่าพร้อมใช้งานใน Materializer ด้วย เพื่อให้กฎที่ทำเครื่องหมายไว้ไม่ขึ้นอยู่กับกฎที่ไม่ได้ทำเครื่องหมายไว้
exec_compatible_with ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการข้อจำกัดในแพลตฟอร์มการดำเนินการซึ่งใช้กับเป้าหมายทั้งหมดของประเภทกฎนี้
analysis_test bool; ค่าเริ่มต้นคือ False
หากเป็นจริง ระบบจะถือว่ากฎนี้เป็นการทดสอบการวิเคราะห์

หมายเหตุ: กฎการทดสอบการวิเคราะห์ได้รับการกำหนดโดยใช้โครงสร้างพื้นฐานที่ระบุไว้ในไลบรารี Starlark หลักเป็นหลัก ดูคำแนะนำได้ที่การทดสอบ

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

  • เป้าหมายของกฎนี้จะจำกัดจำนวนการอ้างอิงแบบทรานซิทีฟที่อาจมี
  • ระบบจะถือว่ากฎนี้เป็นกฎทดสอบ (ราวกับว่ามีการตั้งค่า test=True) ซึ่งจะแทนที่ค่าของ test
  • ฟังก์ชันการติดตั้งใช้งานกฎอาจไม่ลงทะเบียนการดำเนินการ แต่ต้องลงทะเบียนผลการทดสอบว่าผ่าน/ไม่ผ่านโดยระบุ AnalysisTestResultInfo
build_setting BuildSetting หรือ None ค่าเริ่มต้นคือ None
หากตั้งค่าไว้ จะอธิบายว่ากฎนี้เป็น build setting ประเภทใด ดูโมดูล config หากตั้งค่านี้ ระบบจะเพิ่มแอตทริบิวต์ที่ต้องระบุชื่อ "build_setting_default" ลงในกฎนี้โดยอัตโนมัติ โดยมีประเภทที่สอดคล้องกับค่าที่ส่งในที่นี้
cfg ค่าเริ่มต้นคือ None
หากตั้งค่าไว้ จะชี้ไปที่การเปลี่ยนการกำหนดค่าที่กฎจะใช้กับการกำหนดค่าของตัวเองก่อนการวิเคราะห์
exec_groups dict หรือ None ค่าเริ่มต้นคือ None
พจนานุกรมของชื่อกลุ่มการดำเนินการ (สตริง) ไปยัง exec_groups หากตั้งค่าไว้ จะอนุญาตให้กฎเรียกใช้การดำเนินการในแพลตฟอร์มการดำเนินการหลายรายการภายในเป้าหมายเดียว ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบเกี่ยวกับกลุ่มการดำเนินการ
initializer ค่าเริ่มต้นคือ None
เวอร์ชันทดลอง: ฟังก์ชัน Stalark ที่เริ่มต้นแอตทริบิวต์ของกฎ

ระบบจะเรียกใช้ฟังก์ชันเมื่อโหลดอินสแตนซ์ของกฎแต่ละรายการ โดยจะเรียกใช้ด้วย name และค่าของแอตทริบิวต์สาธารณะที่กำหนดโดยกฎ (ไม่ใช่แอตทริบิวต์ทั่วไป เช่น tags)

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

ระบบจะประเมินค่าเริ่มต้นก่อนค่าเริ่มต้นที่ระบุไว้ในคำจำกัดความของแอตทริบิวต์ ดังนั้น หากพารามิเตอร์ในลายเซ็นของตัวเริ่มต้นมีค่าเริ่มต้น ค่าดังกล่าวจะเขียนทับค่าเริ่มต้นจากคำจำกัดความของแอตทริบิวต์ (ยกเว้นในกรณีที่ส่งคืน None)

ในทำนองเดียวกัน หากพารามิเตอร์ในลายเซ็นของตัวเริ่มต้นไม่มีค่าเริ่มต้น พารามิเตอร์นั้นจะกลายเป็นพารามิเตอร์ที่ต้องระบุ ในกรณีดังกล่าว คุณควรละเว้นการตั้งค่าเริ่มต้น/การตั้งค่าที่บังคับในคำจำกัดความแอตทริบิวต์

แนวทางปฏิบัติแนะนำคือใช้ **kwargs สำหรับแอตทริบิวต์ที่ไม่ได้จัดการ

ในกรณีของกฎที่ขยาย ระบบจะเรียกใช้ตัวเริ่มต้นทั้งหมดโดยเริ่มจากองค์ประกอบย่อยไปยังองค์ประกอบระดับบน ระบบจะส่งเฉพาะแอตทริบิวต์สาธารณะที่ตัวเริ่มต้นแต่ละรายการรู้จัก

parent ค่าเริ่มต้นคือ None
ทดลอง: กฎ Stalark ที่ขยาย เมื่อตั้งค่า ระบบจะผสานรวมแอตทริบิวต์สาธารณะและผู้ให้บริการที่โฆษณา กฎจะตรงกับ executable และ test จากระดับบนสุด ระบบจะผสานค่าของ fragments, toolchains, exec_compatible_with และ exec_groups ระบบอาจไม่ตั้งค่าพารามิเตอร์เดิมหรือพารามิเตอร์ที่เลิกใช้งานแล้ว การเปลี่ยนการกำหนดค่าขาเข้า cfg ของระดับบนจะมีผลหลังจากการกำหนดค่าขาเข้าของกฎนี้
extendable bool หรือ Label หรือ string หรือ None ค่าเริ่มต้นคือ None
ทดลอง: ป้ายกำกับของรายการที่อนุญาตซึ่งกำหนดกฎที่ขยายกฎนี้ได้ นอกจากนี้ยังตั้งค่าเป็น True/False เพื่ออนุญาต/ไม่อนุญาตให้ขยายเวลาเสมอได้ด้วย Bazel จะอนุญาตส่วนขยายเสมอโดยค่าเริ่มต้น
subrules ลำดับของกฎย่อย ค่าเริ่มต้นคือ []
การทดลอง: รายการกฎย่อยที่กฎนี้ใช้

เลือก

unknown select(x, no_match_error='')

select() คือฟังก์ชันตัวช่วยที่ทำให้แอตทริบิวต์กฎกำหนดค่าได้ ดูรายละเอียดได้ที่สร้างสารานุกรม

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
x dict; required
Dict ที่แมปเงื่อนไขการกำหนดค่ากับค่า แต่ละคีย์คือป้ายกำกับหรือสตริงป้ายกำกับที่ระบุอินสแตนซ์ config_setting หรือ constraint_value ดูเอกสารประกอบเกี่ยวกับมาโครเพื่อดูว่าเมื่อใดควรใช้ป้ายกำกับแทนสตริง
no_match_error สตริง ค่าเริ่มต้นคือ ''
ข้อผิดพลาดที่กำหนดเองที่ไม่บังคับเพื่อรายงานหากไม่มีเงื่อนไขใดตรงกัน

กฎย่อย

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

สร้างอินสแตนซ์ใหม่ของกฎย่อย ต้องจัดเก็บผลลัพธ์ของฟังก์ชันนี้ไว้ในตัวแปรส่วนกลางก่อนจึงจะใช้งานได้

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation ฟังก์ชัน ต้องระบุ
ฟังก์ชัน Starlark ที่ใช้กฎย่อยนี้
attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมเพื่อประกาศแอตทริบิวต์ (ส่วนตัว) ทั้งหมดของกฎย่อย

กฎย่อยจะมีได้เฉพาะแอตทริบิวต์ส่วนตัวที่เป็นประเภทป้ายกำกับ (เช่น ป้ายกำกับหรือรายการป้ายกำกับ) Bazel จะส่งค่าที่แก้ไขแล้วซึ่งสอดคล้องกับป้ายกำกับเหล่านี้ไปยังฟังก์ชันการใช้งานของกฎย่อยโดยอัตโนมัติเป็นอาร์กิวเมนต์ที่มีชื่อ (ดังนั้นฟังก์ชันการใช้งานจึงต้องยอมรับพารามิเตอร์ที่มีชื่อซึ่งตรงกับชื่อแอตทริบิวต์) ประเภทของค่าเหล่านี้จะเป็นดังนี้

  • FilesToRunProvider สำหรับแอตทริบิวต์ป้ายกำกับที่มี executable=True
  • File สำหรับแอตทริบิวต์ป้ายกำกับที่มี allow_single_file=True
  • Target สำหรับแอตทริบิวต์ป้ายกำกับอื่นๆ ทั้งหมด
  • [Target] สำหรับแอตทริบิวต์รายการป้ายกำกับทั้งหมด
toolchains sequence; ค่าเริ่มต้นคือ []
หากตั้งค่าไว้ ชุดเครื่องมือที่กฎย่อยนี้ต้องการ รายการอาจมีออบเจ็กต์ String, Label หรือ StarlarkToolchainTypeApi ในการผสมผสานใดก็ได้ ระบบจะค้นหา Toolchain โดยตรวจสอบแพลตฟอร์มปัจจุบันและส่งให้การติดตั้งใช้งานกฎย่อยผ่าน ctx.toolchains โปรดทราบว่าต้องเปิดใช้ AEG ในกฎการใช้งานหากตั้งค่าพารามิเตอร์นี้ หากยังไม่ได้ย้ายข้อมูลไปยัง AEG โปรดดู https://bazel.build/extending/auto-exec-groups#migration-aegs
fragments ลำดับของสตริง ค่าเริ่มต้นคือ []
รายการชื่อของส่วนการกำหนดค่าที่กฎย่อยต้องการในการกำหนดค่าเป้าหมาย
subrules ลำดับของกฎย่อย ค่าเริ่มต้นคือ []
รายการกฎย่อยอื่นๆ ที่กฎย่อยนี้ต้องการ

tag_class

tag_class tag_class(attrs={}, *, doc=None)

สร้างออบเจ็กต์ tag_class ใหม่ ซึ่งกําหนดสคีมาแอตทริบิวต์สําหรับคลาสของแท็ก ซึ่งเป็นออบเจ็กต์ข้อมูลที่ใช้ได้โดยส่วนขยายโมดูล

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมเพื่อประกาศแอตทริบิวต์ทั้งหมดของคลาสแท็กนี้ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ (ดูโมดูล attr)

โปรดทราบว่าแอตทริบิวต์ที่ประกาศจะไม่แปลง None เป็นค่าเริ่มต้น ซึ่งแตกต่างจาก rule(), aspect() และ repository_rule() หากต้องการใช้ค่าเริ่มต้น ผู้โทรต้องเว้นแอตทริบิวต์ไว้ทั้งหมด
doc สตริง หรือ None ค่าเริ่มต้นคือ None
คำอธิบายของคลาสแท็กที่เครื่องมือสร้างเอกสารสามารถดึงข้อมูลได้

การเปิดเผย

None visibility(value)

ตั้งค่าระดับการเข้าถึงการโหลดของโมดูล .bzl ที่กำลังเริ่มต้น

ระดับการเข้าถึงการโหลดของโมดูลจะควบคุมว่าไฟล์ BUILD และ .bzl อื่นๆ จะโหลดโมดูลนั้นได้หรือไม่ (ซึ่งแตกต่างจากระดับการเข้าถึงเป้าหมายของไฟล์ต้นฉบับ .bzl ที่เกี่ยวข้อง ซึ่งควบคุมว่าไฟล์จะปรากฏเป็นการขึ้นต่อกันของเป้าหมายอื่นๆ ได้หรือไม่) การโหลดการมองเห็นจะทำงานที่ระดับแพ็กเกจ กล่าวคือ หากต้องการโหลดโมดูล ไฟล์ที่ทำการโหลดจะต้องอยู่ในแพ็กเกจที่ได้รับสิทธิ์การมองเห็นโมดูล ระบบจะโหลดโมดูลภายในแพ็กเกจของโมดูลเองได้เสมอ ไม่ว่าการมองเห็นจะเป็นอย่างไรก็ตาม

visibility() จะเรียกได้เพียงครั้งเดียวต่อไฟล์ .bzl และที่ระดับบนสุดเท่านั้น ไม่ใช่ภายในฟังก์ชัน รูปแบบที่แนะนำคือการวางการเรียกนี้ไว้ใต้คำสั่ง load() โดยตรงและวางตรรกะสั้นๆ ที่จำเป็นต่อการกำหนดอาร์กิวเมนต์

หากตั้งค่า Flag --check_bzl_visibility เป็น "เท็จ" การละเมิดระดับการมองเห็นการโหลดจะแสดงคำเตือนแต่จะไม่ทำให้บิลด์ล้มเหลว

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
value ต้องระบุ
รายการสตริงข้อมูลจำเพาะของแพ็กเกจ หรือสตริงข้อมูลจำเพาะของแพ็กเกจเดียว

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

  • "//foo": แพ็กเกจ //foo
  • "//foo/...": แพ็กเกจ //foo และแพ็กเกจย่อยทั้งหมด
  • "public" หรือ "private": แพ็กเกจทั้งหมดหรือไม่แสดงแพ็กเกจเลย

ไม่อนุญาตให้ใช้ไวยากรณ์ "@" โดยจะมีการตีความข้อกำหนดทั้งหมดที่เกี่ยวข้องกับที่เก็บของโมดูลปัจจุบัน

หาก value เป็นรายการสตริง ชุดแพ็กเกจที่ได้รับสิทธิ์เข้าถึงโมดูลนี้คือการรวมแพ็กเกจที่แสดงโดยข้อกำหนดแต่ละรายการ (รายการที่ว่างเปล่าจะมีผลเหมือนกับ private) หาก value เป็นสตริงเดียว ระบบจะถือว่าสตริงนั้นเป็นรายการแบบเอกพจน์ [value]

โปรดทราบว่าแฟล็ก --incompatible_package_group_has_public_syntax และ --incompatible_fix_package_group_reporoot_syntax จะไม่มีผลต่ออาร์กิวเมนต์นี้ ค่า "public" และ "private" จะพร้อมใช้งานเสมอ และระบบจะตีความ "//..." เป็น "แพ็กเกจทั้งหมดในที่เก็บปัจจุบัน" เสมอ