ไฟล์ .bzl

รายงานปัญหา รุ่น Nightly · 8.0 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

เมธอดส่วนกลางที่ใช้ได้ในไฟล์ .bzl ทั้งหมด

สมาชิก

analysis_test_transition

transition analysis_test_transition(settings)

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

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

พารามิเตอร์

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

เฉพาะด้าน

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; ต้องระบุ
ฟังก์ชัน Starlark ที่ใช้แง่มุมนี้ โดยมีพารามิเตอร์ 2 รายการ ได้แก่ Target (เป้าหมายที่จะใช้แง่มุม) และ ctx (บริบทกฎที่สร้างเป้าหมาย) แอตทริบิวต์ของเป้าหมายจะแสดงผ่านช่อง ctx.rule ระบบจะประเมินฟังก์ชันนี้ในระหว่างระยะการวิเคราะห์สําหรับการใช้แง่มุมกับเป้าหมายแต่ละรายการ
attr_aspects ลําดับของ string; ค่าเริ่มต้นคือ []
ชื่อแอตทริบิวต์ โดยแง่มุมจะเผยแพร่ตามข้อกําหนดของทรัพยากรที่ระบุไว้ในแอตทริบิวต์ของเป้าหมายที่มีชื่อเหล่านี้ ค่าที่พบบ่อยที่นี่ ได้แก่ deps และ exports รายการนี้อาจมีสตริง "*" รายการเดียวเพื่อนำไปใช้กับรายการที่เกี่ยวข้องทั้งหมดของเป้าหมาย
toolchains_aspects sequence; ค่าเริ่มต้นคือ []
รายการประเภทเครื่องมือทางเทคนิค ข้อมูลพร็อพเพอร์ตี้จะนำไปใช้กับเครื่องมือทางเทคนิคเป้าหมายที่ตรงกับประเภทเครื่องมือทางเทคนิคเหล่านี้
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]] ไม่ถูกต้อง

ระบบจะแปลงรายการผู้ให้บริการที่ไม่มีการฝังเป็นรายการที่มีรายการผู้ให้บริการรายการเดียวโดยอัตโนมัติ กล่าวคือ [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]] ไม่ถูกต้อง

ระบบจะแปลงรายการผู้ให้บริการที่ไม่มีการฝังเป็นรายการที่มีรายการผู้ให้บริการรายการเดียวโดยอัตโนมัติ กล่าวคือ [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() แสดงผล ยกเว้นผู้ให้บริการเดิมที่แสดงด้วยชื่อสตริงแทน เมื่อใช้เป้าหมายของกฎเป็นข้อกําหนดของเป้าหมายที่ประกาศผู้ให้บริการที่จําเป็น ก็ไม่จำเป็นต้องระบุผู้ให้บริการดังกล่าวที่นี่ เพียงแค่ฟังก์ชันการใช้งานแสดงผลก็เพียงพอแล้ว อย่างไรก็ตาม การกำหนดค่านี้ถือเป็นแนวทางปฏิบัติแนะนำ แม้ว่าจะไม่จำเป็นต้องทำก็ตาม อย่างไรก็ตาม ฟิลด์ required_providers ของแง่มุมจะต้องระบุผู้ให้บริการที่นี่

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

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

เท็จโดยค่าเริ่มต้น
exec_compatible_with ลําดับของ สตริง ค่าเริ่มต้นคือ []
นี่คือรายการข้อจํากัดในแพลตฟอร์มการดําเนินการที่มีผลกับอินสแตนซ์ทั้งหมดของด้านนี้
exec_groups dict หรือ None ค่าเริ่มต้นคือ None
Dict ของชื่อกลุ่มการดําเนินการ (สตริง) เป็น exec_groups หากตั้งค่าไว้ จะช่วยให้แง่มุมทําการบนแพลตฟอร์มการดําเนินการหลายแพลตฟอร์มภายในอินสแตนซ์เดียวได้ ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบเกี่ยวกับกลุ่มการดําเนินการ
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 สตริง ต้องระบุ
ชื่อของข้อมูลโค้ดที่เป็นส่วนย่อยของการกำหนดค่าซึ่งมีค่าที่ผูกในภายหลัง
name สตริง; ต้องระบุ
ชื่อของค่าที่จะรับจากข้อมูลโค้ดที่กําหนดค่า

depset

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

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

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

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

นอกจากนี้ ขณะนี้องค์ประกอบต้องเป็นแบบคงที่ แต่เราจะผ่อนปรนข้อจำกัดนี้ในอนาคต

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

พารามิเตอร์

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

exec_group

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

สร้างกลุ่มการดําเนินการซึ่งสามารถใช้ในการสร้างการดําเนินการสําหรับแพลตฟอร์มการดําเนินการหนึ่งๆ ระหว่างการติดตั้งใช้งานกฎ

พารามิเตอร์

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

exec_transition

transition exec_transition(implementation, inputs, outputs)

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

พารามิเตอร์

พารามิเตอร์ คำอธิบาย
implementation callable; ต้องระบุ
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 rule หรือ macro หรือ string หรือ 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 สตริง หรือ None ค่าเริ่มต้นคือ None
คำอธิบายส่วนขยายของโมดูลที่เครื่องมือสร้างเอกสารประกอบจะดึงข้อมูลได้
environ ลําดับสตริง ค่าเริ่มต้นคือ []
ให้รายการตัวแปรสภาพแวดล้อมที่ส่วนขยายโมดูลนี้ใช้ หากตัวแปรสภาพแวดล้อมในรายการมีการเปลี่ยนแปลง ระบบจะประเมินส่วนขยายอีกครั้ง
os_dependent bool; default is False
Indicates whether this extension is OS-dependent or not
arch_dependent bool; default is False
Indicates whether this extension is architecture-dependent or not

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 ระบบจะแสดงผล tupple ที่มี 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() จะแสดงผล tupple ขององค์ประกอบ 2 รายการ ได้แก่ สัญลักษณ์ผู้ให้บริการปกติและตัวสร้างแบบดิบ

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

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

  • หาก args ไม่ใช่ค่าว่าง ระบบจะแสดงข้อผิดพลาด
  • หากมีการระบุพารามิเตอร์ fields เมื่อเรียก provider() และหาก kwargs มีคีย์ที่ไม่ได้ระบุไว้ใน fields ระบบจะแสดงข้อผิดพลาด
  • ไม่เช่นนั้น c จะแสดงผลอินสแตนซ์ใหม่ที่มีช่องชื่อ k ที่มีค่า v สำหรับรายการ k: v แต่ละรายการใน kwargs
ในกรณีที่ไม่ได้ระบุการเรียกกลับ init การเรียกใช้สัญลักษณ์ 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 ทั่วไปสำหรับการสร้างผู้ให้บริการตามปกติด้วยการอนุญาตให้ใช้อาร์กิวเมนต์ตำแหน่งและตรรกะที่กำหนดเองสำหรับการเตรียมข้อมูลและการตรวจสอบ แต่ไม่ได้เปิดใช้การหลบเลี่ยงรายการ fields ที่อนุญาต

เมื่อระบุ init ผลลัพธ์ของ provider() จะกลายเป็นทูเปิล (P, r) โดยที่ r คือตัวสร้างแบบดิบ อันที่จริง ลักษณะการทํางานของ 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; ต้องระบุ
ฟังก์ชันที่ใช้กฎนี้ ต้องมีพารามิเตอร์เดียว repository_ctx ระบบจะเรียกใช้ฟังก์ชันนี้ในระหว่างระยะการโหลดสําหรับอินสแตนซ์แต่ละรายการของกฎ
attrs dict หรือ None ค่าเริ่มต้นคือ None
พจนานุกรมสำหรับประกาศแอตทริบิวต์ทั้งหมดของกฎที่เก็บ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ (ดูข้อบังคับของ attr) แอตทริบิวต์ที่ขึ้นต้นด้วย _ เป็นแอตทริบิวต์ส่วนตัว และใช้เพื่อเพิ่มการพึ่งพาโดยนัยในป้ายกำกับลงในไฟล์ได้ (กฎของที่เก็บข้อมูลต้องไม่ขึ้นอยู่กับอาร์ติแฟกต์ที่สร้างขึ้น) ระบบจะเพิ่มแอตทริบิวต์ name โดยปริยายและไม่ต้องระบุ

แอตทริบิวต์ที่ประกาศจะแปลง None เป็นค่าเริ่มต้น
local bool; ค่าเริ่มต้นคือ False
ระบุว่ากฎนี้จะดึงข้อมูลทั้งหมดจากระบบในเครื่องและควรได้รับการประเมินใหม่ทุกครั้งที่ดึงข้อมูล
environ ลําดับสตริง ค่าเริ่มต้นคือ []
เลิกใช้งานแล้ว พารามิเตอร์นี้เลิกใช้งานแล้ว ย้ายข้อมูลไปยัง repository_ctx.getenv แทน
แสดงรายการตัวแปรสภาพแวดล้อมที่กฎที่เก็บข้อมูลนี้ใช้ หากตัวแปรสภาพแวดล้อมในรายการนั้นเปลี่ยนแปลง ระบบจะดึงข้อมูลพื้นที่เก็บข้อมูลอีกครั้ง
configure bool; ค่าเริ่มต้นคือ False
ระบุว่าที่เก็บจะตรวจสอบระบบเพื่อวัตถุประสงค์ในการกําหนดค่า
remotable bool; ค่าเริ่มต้นคือ False
ทดลอง พารามิเตอร์นี้ยังอยู่ในขั้นทดลองและอาจมีการเปลี่ยนแปลงได้ทุกเมื่อ โปรดอย่าใช้ข้อมูลนี้ คุณอาจเปิดใช้การดําเนินการนี้เป็นการทดลองได้โดยการตั้งค่า --experimental_repo_remote_exec
เข้ากันได้กับการดำเนินการระยะไกล
doc สตริง หรือ 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; ต้องระบุ
ฟังก์ชัน Starlark ที่ใช้กฎนี้ต้องมีพารามิเตอร์เพียง 1 รายการเท่านั้น ซึ่งก็คือ ctx ระบบจะเรียกใช้ฟังก์ชันนี้ในระหว่างระยะการวิเคราะห์สำหรับอินสแตนซ์ของกฎแต่ละรายการ โดยสามารถเข้าถึงแอตทริบิวต์ที่ผู้ใช้ระบุ โดยต้องสร้างการดำเนินการเพื่อสร้างเอาต์พุตที่ประกาศไว้ทั้งหมด
test bool; ค่าเริ่มต้นคือ unbound
ระบุว่ากฎนี้เป็นกฎทดสอบหรือไม่ กล่าวคือ กฎนี้อาจเป็นเรื่องของคําสั่ง blaze test หรือไม่ ระบบจะถือว่ากฎทดสอบทั้งหมดexecutableโดยอัตโนมัติ คุณจึงไม่จำเป็นต้อง (และไม่แนะนํา) ตั้งค่า executable = True ให้กับกฎทดสอบอย่างชัดเจน ค่าเริ่มต้นคือ False ดูข้อมูลเพิ่มเติมได้ที่ หน้ากฎ
attrs dict; ค่าเริ่มต้นคือ {}
พจนานุกรมเพื่อประกาศแอตทริบิวต์ทั้งหมดของกฎ โดยจะแมปจากชื่อแอตทริบิวต์ไปยังออบเจ็กต์แอตทริบิวต์ (ดูข้อบังคับของ attr) แอตทริบิวต์ที่ขึ้นต้นด้วย _ จะเป็นแอตทริบิวต์ส่วนตัว และสามารถใช้เพื่อเพิ่มการพึ่งพาโดยนัยในป้ายกำกับ ระบบจะเพิ่มแอตทริบิวต์ name โดยปริยายและไม่ต้องระบุ ระบบจะเพิ่มแอตทริบิวต์ visibility, deprecation, tags, testonly และ features โดยปริยายและไม่สามารถลบล้างได้ กฎส่วนใหญ่ใช้แอตทริบิวต์เพียงไม่กี่รายการ ระบบจะจำกัดจำนวนแอตทริบิวต์ที่ประกาศได้เพื่อจำกัดการใช้หน่วยความจํา

แอตทริบิวต์ที่ประกาศจะแปลง None เป็นค่าเริ่มต้น
outputs dict หรือ None หรือ function ค่าเริ่มต้นคือ None
เลิกใช้งานแล้ว พารามิเตอร์นี้เลิกใช้งานแล้วและจะถูกนำออกเร็วๆ นี้ โปรดอย่าใช้ข้อมูลนี้ ปิดใช้กับ --incompatible_no_rule_outputs_param ใช้ Flag นี้เพื่อยืนยันว่าโค้ดของคุณเข้ากันได้กับการนําออกที่กําลังจะเกิดขึ้น
พารามิเตอร์นี้เลิกใช้งานแล้ว ย้ายข้อมูลกฎเพื่อใช้ 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 โปรดอย่าตั้งค่า Flag นี้ เว้นแต่ว่าคุณต้องการใช้เพื่อให้เข้ากันได้กับกฎที่มีอยู่ (เช่น เมื่อสร้างไฟล์ส่วนหัวสำหรับ C++)
fragments ลําดับของ สตริง ค่าเริ่มต้นคือ []
ชื่อรายการของข้อมูลโค้ดการกําหนดค่าที่กฎจําเป็นในการกําหนดค่าเป้าหมาย
host_fragments ลําดับของ สตริง ค่าเริ่มต้นคือ []
รายการชื่อของข้อมูลโค้ดการกําหนดค่าที่กฎจําเป็นในการกําหนดค่าโฮสต์
_skylark_testable bool; ค่าเริ่มต้นคือ False
(ทดลอง)

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

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

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

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

dependency_resolution_rule bool; ค่าเริ่มต้นคือ False
หากตั้งค่า กฎอาจเป็นข้อกำหนดผ่านแอตทริบิวต์ที่ทําเครื่องหมายว่าพร้อมใช้งานใน Materializer ด้วย แอตทริบิวต์ทุกรายการของกฎที่มีการตั้งค่า Flag นี้ต้องทําเครื่องหมายว่าพร้อมใช้งานใน Materializers ด้วย การทำเครื่องหมายนี้เพื่อให้กฎที่ทำเครื่องหมายไว้ไม่สามารถใช้กฎที่ไม่ได้ทำเครื่องหมาย
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
Dict ของชื่อกลุ่มการดําเนินการ (สตริง) เป็น 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; ต้องระบุ
พจนานุกรมที่แมปเงื่อนไขการกําหนดค่ากับค่า คีย์แต่ละรายการคือป้ายกํากับหรือสตริงป้ายกํากับที่ระบุอินสแตนซ์ config_setting หรือ constraint_value ดูเอกสารประกอบเกี่ยวกับมาโครเพื่อดูกรณีที่ควรใช้ป้ายกํากับแทนสตริง
no_match_error สตริง ค่าเริ่มต้นคือ ''
ข้อผิดพลาดที่กำหนดเองซึ่งไม่บังคับเพื่อรายงานหากไม่มีเงื่อนไขที่ตรงกัน

กฎย่อย

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

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

พารามิเตอร์

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

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

  • FilesToRunProvider สำหรับแอตทริบิวต์ป้ายกำกับที่มี executable=True
  • File สำหรับแอตทริบิวต์ป้ายกำกับที่มี allow_single_file=True
  • Target สำหรับแอตทริบิวต์ป้ายกำกับอื่นๆ ทั้งหมด
  • [Target] สำหรับแอตทริบิวต์รายการป้ายกำกับทั้งหมด
toolchains sequence; ค่าเริ่มต้นคือ []
หากตั้งค่าไว้ ชุดเครื่องมือทางเทคนิคที่กฎย่อยนี้กำหนด รายการอาจมีออบเจ็กต์สตริง ป้ายกำกับ หรือ 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]

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