กฎ

7.3 · 7.2 · 7.1 · 7.0 · 6.5

กฎจะกำหนดชุดการดำเนินการที่ Bazel ดำเนินการกับข้อมูลอินพุตเพื่อสร้างชุดเอาต์พุต ซึ่งจะอ้างอิงในผู้ให้บริการที่แสดงผลโดยฟังก์ชันการใช้งานของกฎ เช่น กฎไบนารีของ C++ อาจมีลักษณะดังนี้

1. รับชุดไฟล์ต้นฉบับ .cpp ไฟล์ (อินพุต)
2. เรียกใช้ g++ ในไฟล์ต้นฉบับ (การดำเนินการ)
3. แสดงผลผู้ให้บริการ DefaultInfo ที่มีเอาต์พุตที่เรียกใช้งานได้และไฟล์อื่นๆ เพื่อทำให้พร้อมใช้งานเมื่อรันไทม์
4. แสดงผลผู้ให้บริการ CcInfo พร้อมข้อมูลเฉพาะ C++ ที่รวบรวมจากเป้าหมายและการอ้างอิง

จากมุมมองของ Bazel นั้น g++ และไลบรารี C++ มาตรฐานเป็นอินพุตของกฎนี้เช่นกัน ในฐานะผู้เขียนกฎ คุณต้องพิจารณาไม่เพียงอินพุตที่ผู้ใช้ระบุให้กับกฎเท่านั้น แต่ยังต้องพิจารณาเครื่องมือและไลบรารีทั้งหมดที่จําเป็นต่อการดำเนินการด้วย

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

Bazel มีกฎบางอย่างในตัว กฎเนทีฟเหล่านี้ เช่น cc_library และ java_binary จะให้การสนับสนุนหลักบางอย่างสำหรับบางภาษา การกำหนดกฎเองจะช่วยให้คุณเพิ่มการรองรับภาษาและเครื่องมือที่คล้ายกันที่ Bazel ไม่ได้รองรับโดยค่าเริ่มต้น

Bazel มีโมเดลการขยายสำหรับการเขียนกฎโดยใช้ภาษา Starlark กฎเหล่านี้เขียนขึ้นในไฟล์ .bzl ซึ่งจะโหลดจากไฟล์ BUILD ได้โดยตรง

เมื่อกําหนดกฎของคุณเอง คุณสามารถเลือกแอตทริบิวต์ที่รองรับและวิธีสร้างเอาต์พุต

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

การสร้างกฎ

ในไฟล์ .bzl ให้ใช้ฟังก์ชันกฎเพื่อกำหนดกฎใหม่และจัดเก็บผลลัพธ์ไว้ในตัวแปรร่วม การเรียก rule จะระบุแอตทริบิวต์และฟังก์ชันการติดตั้งใช้งาน ดังนี้

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "deps": attr.label_list(),
        ...
    },
)

ซึ่งจะกําหนดประเภทกฎชื่อ example_library

การเรียกใช้ rule จะต้องระบุด้วยว่ากฎสร้างเอาต์พุตที่เรียกใช้งานได้ (มี executable=True) หรือเป็นไฟล์ที่เรียกใช้ได้สำหรับทดสอบโดยเฉพาะ (มี test=True) หากเป็นอย่างหลัง กฎจะเป็นกฎทดสอบ และชื่อกฎต้องลงท้ายด้วย _test

การสร้างอินสแตนซ์เป้าหมาย

คุณจะโหลดและเรียกใช้กฎใน BUILD ไฟล์ได้ดังนี้

load('//some/pkg:rules.bzl', 'example_library')

example_library(
    name = "example_target",
    deps = [":another_target"],
    ...
)

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

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

Attributes

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

แอตทริบิวต์เฉพาะกฎ เช่น srcs หรือ deps จะกำหนดโดยการส่งแมปจากชื่อแอตทริบิวต์ไปยังสคีมา (สร้างโดยใช้โมดูล attr) ไปยังพารามิเตอร์ attrs ของ rule แอตทริบิวต์ทั่วไป เช่น name และ visibility จะเพิ่มลงในกฎทั้งหมดโดยปริยาย ระบบจะเพิ่มแอตทริบิวต์เพิ่มเติมลงในกฎที่เรียกใช้ได้และกฎทดสอบโดยปริยาย แอตทริบิวต์ที่เพิ่มลงในกฎโดยนัยจะรวมอยู่ในพจนานุกรมที่ส่งไปยัง attrs ไม่ได้

แอตทริบิวต์การขึ้นต่อกัน

กฎที่ประมวลผลซอร์สโค้ดมักจะกำหนดแอตทริบิวต์ต่อไปนี้เพื่อจัดการทรัพยากร Dependency ประเภทต่างๆ

• srcs ระบุไฟล์ต้นฉบับที่ประมวลผลโดยการดำเนินการของเป้าหมาย บ่อยครั้ง สคีมาแอตทริบิวต์จะระบุนามสกุลไฟล์ที่คาดไว้สำหรับประเภทไฟล์ต้นทางที่กฎประมวลผล โดยทั่วไป กฎสำหรับภาษาที่มีไฟล์ส่วนหัวจะระบุแอตทริบิวต์ hdrs แยกต่างหากสำหรับส่วนหัวที่ประมวลผลโดยเป้าหมายและผู้ใช้งาน
• deps ระบุทรัพยากร Dependency ของโค้ดสําหรับเป้าหมาย สคีมาแอตทริบิวต์ควรระบุผู้ให้บริการที่ต้องมีทรัพยากร Dependency เหล่านั้น (เช่น cc_library มี CcInfo)
• data ระบุไฟล์ที่จะพร้อมใช้งานเมื่อรันไทม์สำหรับไฟล์ที่เรียกใช้งานได้ซึ่งขึ้นอยู่กับเป้าหมาย ซึ่งควรอนุญาตให้ระบุไฟล์ใดก็ได้

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = [".example"]),
        "hdrs": attr.label_list(allow_files = [".header"]),
        "deps": attr.label_list(providers = [ExampleInfo]),
        "data": attr.label_list(allow_files = True),
        ...
    },
)

ต่อไปนี้คือตัวอย่างของแอตทริบิวต์การขึ้นต่อกัน แอตทริบิวต์ที่ระบุ ป้ายกำกับอินพุต (ที่กำหนดไว้ด้วย attr.label_list, attr.label หรือ attr.label_keyed_string_dict) จะระบุทรัพยากร Dependency บางประเภท ระหว่างเป้าหมายและเป้าหมายที่มีป้ายกำกับ (หรือออบเจ็กต์ Label ที่เกี่ยวข้อง) แสดงอยู่ในแอตทริบิวต์นั้นเมื่อกำหนดเป้าหมาย ที่เก็บ รวมถึงเส้นทางสำหรับป้ายกำกับเหล่านี้จะได้รับการแก้ไขโดยสัมพันธ์กับเป้าหมายที่กำหนด

example_library(
    name = "my_target",
    deps = [":other_target"],
)

example_library(
    name = "other_target",
    ...
)

ในตัวอย่างนี้ other_target เป็นทรัพยากร Dependency ของ my_target ระบบจึงวิเคราะห์ other_target ก่อน เพราะเป็นข้อผิดพลาดหากมีวงจรในกราฟการขึ้นต่อกันของเป้าหมาย

แอตทริบิวต์ส่วนตัวและการอ้างอิงโดยนัย

แอตทริบิวต์ทรัพยากร Dependency ที่มีค่าเริ่มต้นจะสร้างการขึ้นต่อกันแบบไม่เจาะจงปลายทาง ข้อมูลนี้เป็นการระบุโดยนัยเนื่องจากเป็นส่วนหนึ่งของกราฟเป้าหมายที่ผู้ใช้ไม่ได้ระบุไว้ในไฟล์ BUILD การขึ้นต่อกันโดยนัยมีประโยชน์สำหรับการฮาร์ดโค้ดความสัมพันธ์ระหว่างกฎกับเครื่องมือ (ทรัพยากร Dependency ของบิลด์ เช่น คอมไพเลอร์) เนื่องจากส่วนใหญ่ผู้ใช้ไม่สนใจระบุว่ากฎดังกล่าวใช้เครื่องมือใด ในฟังก์ชันการใช้งานของกฎ ระบบจะถือว่าค่านี้เหมือนกับการอ้างอิงอื่นๆ

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

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        ...
        "_compiler": attr.label(
            default = Label("//tools:example_compiler"),
            allow_single_file = True,
            executable = True,
            cfg = "exec",
        ),
    },
)

ในตัวอย่างนี้ เป้าหมายทุกรายการของประเภท example_library มีการขึ้นต่อกันโดยนัยในคอมไพเลอร์ //tools:example_compiler การดำเนินการนี้จะอนุญาตให้ฟังก์ชันการใช้งานของ example_library สร้างการดำเนินการที่จะเรียกใช้คอมไพเลอร์ แม้ว่าผู้ใช้จะไม่ได้ส่งป้ายกำกับเป็นอินพุตก็ตาม เนื่องจาก _compiler เป็นแอตทริบิวต์ส่วนตัว ctx.attr._compiler จึงจะชี้ไปยัง //tools:example_compiler เสมอในเป้าหมายทั้งหมดของกฎประเภทนี้ หรือจะตั้งชื่อแอตทริบิวต์ compiler โดยไม่มีขีดล่างและใช้ค่าเริ่มต้นก็ได้ วิธีนี้จะช่วยให้ผู้ใช้แทนที่คอมไพเลอร์อื่นได้หากจำเป็น แต่ต้องไม่รับรู้เกี่ยวกับป้ายกำกับของคอมไพเลอร์

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

แอตทริบิวต์เอาต์พุต

แอตทริบิวต์เอาต์พุต เช่น attr.output และ attr.output_list ประกาศไฟล์เอาต์พุตที่เป้าหมายสร้างขึ้น ซึ่งแตกต่างจากแอตทริบิวต์ Dependency ใน 2 ลักษณะ ดังนี้

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

โดยปกติแล้ว แอตทริบิวต์เอาต์พุตจะใช้ก็ต่อเมื่อกฎต้องสร้างเอาต์พุตที่มีชื่อที่ผู้ใช้กำหนด ซึ่งไม่สามารถอิงตามชื่อเป้าหมายได้ หากกฎมีแอตทริบิวต์เอาต์พุต 1 รายการ โดยทั่วไปชื่อของกฎจะเป็น out หรือ outs

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

ฟังก์ชันการใช้งาน

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

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

ฟังก์ชันการใช้งานจะใช้พารามิเตอร์เพียง 1 รายการเท่านั้น ซึ่งก็คือบริบทของกฎที่มีชื่อตามธรรมเนียมว่า ctx ซึ่งจะแสดงรายการผู้ให้บริการ

เป้าหมาย

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

ctx.attr มีช่องที่สอดคล้องกับชื่อของแอตทริบิวต์การขึ้นต่อกันแต่ละรายการ ซึ่งมีออบเจ็กต์ Target รายการที่แสดงถึงการขึ้นต่อกันโดยตรงแต่ละรายการผ่านแอตทริบิวต์นั้น สำหรับแอตทริบิวต์ label_list รายการนี้คือ Targets สำหรับแอตทริบิวต์ label จะเป็น Target หรือ None รายการเดียว

ฟังก์ชันการใช้งานของเป้าหมายจะแสดงผลรายการออบเจ็กต์ผู้ให้บริการ ดังนี้

return [ExampleInfo(headers = depset(...))]

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

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

def _example_library_impl(ctx):
    ...
    transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]

สําหรับรูปแบบเดิมที่แสดงผล struct จากฟังก์ชันการติดตั้งใช้งานของเป้าหมายแทนรายการออบเจ็กต์ผู้ให้บริการ ให้ทําดังนี้

return struct(example_info = struct(headers = depset(...)))

ดูผู้ให้บริการได้จากช่องที่เกี่ยวข้องของออบเจ็กต์ Target ดังนี้

transitive_headers = [hdr.example_info.headers for hdr in ctx.attr.hdrs]

เราไม่แนะนำให้ใช้รูปแบบนี้อย่างยิ่งและควรย้ายข้อมูลออกจากสไตล์นี้

ไฟล์

ไฟล์จะแสดงด้วยออบเจ็กต์ File เนื่องจาก Bazel ไม่ได้ดำเนินการ I/O ของไฟล์ในระหว่างระยะการวิเคราะห์ คุณจึงใช้ออบเจ็กต์เหล่านี้เพื่ออ่านหรือเขียนเนื้อหาไฟล์โดยตรงไม่ได้ แต่จะส่งไปยังฟังก์ชันการปล่อยการกระทำ (ดู ctx.actions) เพื่อสร้างส่วนต่างๆ ของกราฟการดำเนินการ

File อาจเป็นไฟล์ต้นฉบับหรือไฟล์ที่สร้างขึ้นก็ได้ ไฟล์ที่สร้างขึ้นแต่ละไฟล์ต้องเป็นเอาต์พุตของการดำเนินการ 1 รายการเท่านั้น ไฟล์ต้นฉบับไม่สามารถเป็นเอาต์พุต ของการทำงานใดๆ ได้

สําหรับแอตทริบิวต์การพึ่งพาแต่ละรายการ ช่องที่เกี่ยวข้องของ ctx.files จะมีรายการเอาต์พุตเริ่มต้นของการพึ่งพาทั้งหมดผ่านแอตทริบิวต์นั้น

def _example_library_impl(ctx):
    ...
    headers = depset(ctx.files.hdrs, transitive=transitive_headers)
    srcs = ctx.files.srcs
    ...

ctx.file มี File หรือ None รายการเดียวสำหรับแอตทริบิวต์ Dependency ที่กำหนดข้อกำหนดเป็น allow_single_file=True ctx.executable จะทํางานเหมือนกับ ctx.file แต่จะประกอบด้วยเฉพาะช่องสําหรับแอตทริบิวต์ Dependency ที่ตั้งค่าข้อกําหนดเป็น executable=True

การประกาศเอาต์พุต

ในระหว่างขั้นตอนการวิเคราะห์ ฟังก์ชันการใช้งานของกฎจะสร้างเอาต์พุตได้ เนื่องจากต้องทราบป้ายกำกับทั้งหมดในระยะการโหลดเอาต์พุตเพิ่มเติมเหล่านี้จึงไม่มีป้ายกำกับ คุณสร้างออบเจ็กต์ File สำหรับเอาต์พุตได้โดยใช้ ctx.actions.declare_file และ ctx.actions.declare_directory โดยทั่วไปแล้ว ชื่อเอาต์พุตจะอิงตามชื่อของเป้าหมาย ctx.label.name

def _example_library_impl(ctx):
  ...
  output_file = ctx.actions.declare_file(ctx.label.name + ".output")
  ...

สำหรับเอาต์พุตที่ประกาศล่วงหน้า เช่น เอาต์พุตที่สร้างขึ้นสำหรับแอตทริบิวต์เอาต์พุต จะดึงออบเจ็กต์ File มาจากช่องที่เกี่ยวข้องของ ctx.outputs แทนได้

การทำงาน

การดำเนินการอธิบายวิธีสร้างชุดเอาต์พุตจากชุดอินพุต เช่น "เรียกใช้ gcc ใน hello.c and get Hello.o" เมื่อสร้างการดำเนินการแล้ว Bazel จะไม่เรียกใช้คำสั่งทันที โดยจะบันทึกไว้ในกราฟของความสัมพันธ์ เนื่องจากการดำเนินการหนึ่งๆ อาจขึ้นอยู่กับเอาต์พุตของการดำเนินการอื่น เช่น ใน C จะต้องเรียก Linker หลังคอมไพเลอร์

ฟังก์ชันเอนกประสงค์ที่สร้างการดำเนินการจะกำหนดไว้ใน ctx.actions

• ctx.actions.run เพื่อเรียกใช้ไฟล์ปฏิบัติการ
• ctx.actions.run_shell เพื่อเรียกใช้คำสั่งเชลล์
• ctx.actions.write เพื่อเขียนสตริงลงในไฟล์
• ctx.actions.expand_template เพื่อ generate ไฟล์จากเทมเพลต

ctx.actions.args ใช้เพื่อรวบรวมอาร์กิวเมนต์สําหรับการดําเนินการได้อย่างมีประสิทธิภาพ ซึ่งจะหลีกเลี่ยงการยุบชุดข้อมูลย่อยจนกว่าจะถึงเวลาดำเนินการ

def _example_library_impl(ctx):
    ...

    transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
    headers = depset(ctx.files.hdrs, transitive=transitive_headers)
    srcs = ctx.files.srcs
    inputs = depset(srcs, transitive=[headers])
    output_file = ctx.actions.declare_file(ctx.label.name + ".output")

    args = ctx.actions.args()
    args.add_joined("-h", headers, join_with=",")
    args.add_joined("-s", srcs, join_with=",")
    args.add("-o", output_file)

    ctx.actions.run(
        mnemonic = "ExampleCompile",
        executable = ctx.executable._compiler,
        arguments = [args],
        inputs = inputs,
        outputs = [output_file],
    )
    ...

การดำเนินการจะนํารายการหรือชุดไฟล์อินพุตไปสร้างรายการไฟล์เอาต์พุต (ที่ไม่ใช่ไฟล์ว่าง) คุณต้องทราบชุดไฟล์อินพุตและเอาต์พุตในระยะการวิเคราะห์ ซึ่งอาจขึ้นอยู่กับค่าของแอตทริบิวต์ รวมถึงผู้ให้บริการจากข้อกําหนด แต่ต้องไม่ขึ้นอยู่กับผลลัพธ์ของการดําเนินการ ตัวอย่างเช่น หากการดำเนินการเรียกใช้คำสั่ง unzip คุณต้องระบุว่าไฟล์ใดที่ต้องการไฟล์ที่สูงเกินจริง (ก่อนเรียกใช้การคลายการบีบอัด) การดำเนินการที่สร้างไฟล์ภายในจํานวนไม่คงที่สามารถรวมไฟล์เหล่านั้นไว้ในไฟล์เดียวได้ (เช่น zip, tar หรือรูปแบบไฟล์เก็บถาวรอื่นๆ)

การดำเนินการต้องป้อนข้อมูลทั้งหมด เราอนุญาตให้ใช้อินพุตรายการที่ไม่ได้ใช้ แต่ ไม่มีประสิทธิภาพ

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

การดำเนินการจะคล้ายกับฟังก์ชันบริสุทธิ์ กล่าวคือ ควรใช้เฉพาะอินพุตที่ระบุไว้ และหลีกเลี่ยงการเข้าถึงข้อมูลคอมพิวเตอร์ ชื่อผู้ใช้ นาฬิกา เครือข่าย หรืออุปกรณ์ I/O (ยกเว้นการอ่านอินพุตและเขียนเอาต์พุต) ซึ่งมีความสำคัญเนื่องจากเอาต์พุตจะมีการแคชและนำมาใช้ซ้ำ

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

ผู้ให้บริการ

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

เนื่องจากฟังก์ชันการใช้งานของกฎจะอ่านได้เฉพาะผู้ให้บริการจากทรัพยากร Dependency ทันทีของเป้าหมายที่ยืนยันได้เท่านั้น กฎจึงต้องส่งต่อข้อมูลใดๆ จากทรัพยากร Dependency ของเป้าหมายที่ผู้บริโภคเป้าหมายต้องทราบ โดยทั่วไปด้วยการสะสมข้อมูลดังกล่าวไว้ใน depset

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

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

เอาต์พุตเริ่มต้น

เอาต์พุตเริ่มต้นของเป้าหมายคือเอาต์พุตที่ระบบขอโดยค่าเริ่มต้นเมื่อมีการขอบิลด์เป้าหมายในบรรทัดคำสั่ง เช่น เป้าหมาย //pkg:foo ของ java_library มี foo.jar เป็นเอาต์พุตเริ่มต้น จึงสร้างด้วยคำสั่ง bazel build //pkg:foo

เอาต์พุตเริ่มต้นจะระบุด้วยพารามิเตอร์ files ของ DefaultInfo ดังนี้

def _example_library_impl(ctx):
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        ...
    ]

หากการใช้งานกฎไม่ได้แสดงผล DefaultInfo หรือไม่ได้ระบุพารามิเตอร์ files DefaultInfo.files จะแสดงผลเป็นเอาต์พุตที่ประกาศไว้ล่วงหน้าทั้งหมดโดยค่าเริ่มต้น (โดยทั่วไปคือเอาต์พุตที่สร้างโดยแอตทริบิวต์เอาต์พุต)

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

การเรียกใช้ไฟล์

ไฟล์รันไทม์คือชุดไฟล์ที่เป้าหมายใช้ขณะรันไทม์ (ไม่ใช่ขณะสร้าง) ในระหว่างระยะการดําเนินการ Bazel จะสร้างลําดับชั้นไดเรกทอรีที่มีลิงก์สัญลักษณ์ซึ่งชี้ไปยังไฟล์รันไทม์ กระบวนการนี้เก็บพักสภาพแวดล้อมของไบนารีเพื่อให้เข้าถึงไฟล์รันไฟล์ในระหว่างรันไทม์ได้

คุณสามารถเพิ่มไฟล์เรียกใช้ด้วยตนเองระหว่างการสร้างกฎ คุณสร้างออบเจ็กต์ runfiles ได้ด้วยเมธอด runfiles ในบริบทของกฎ ctx.runfiles และส่งผ่านไปยังพารามิเตอร์ runfiles ใน DefaultInfo ระบบจะเพิ่มเอาต์พุตไฟล์ปฏิบัติการของกฎปฏิบัติการลงในการเรียกใช้ไฟล์โดยปริยาย

กฎบางข้อจะระบุแอตทริบิวต์ ซึ่งโดยทั่วไปจะตั้งชื่อว่า data ซึ่งจะมีการเพิ่มเอาต์พุตลงในการเรียกใช้ไฟล์ของเป้าหมาย คุณควรรวมไฟล์ Runfile จาก data และจากแอตทริบิวต์ที่อาจมีโค้ดสำหรับการดำเนินการขั้นสุดท้าย โดยทั่วไปคือ srcs (ซึ่งอาจมีเป้าหมาย filegroup ที่มี data ที่เชื่อมโยง) และ deps

def _example_library_impl(ctx):
    ...
    runfiles = ctx.runfiles(files = ctx.files.data)
    transitive_runfiles = []
    for runfiles_attr in (
        ctx.attr.srcs,
        ctx.attr.hdrs,
        ctx.attr.deps,
        ctx.attr.data,
    ):
        for target in runfiles_attr:
            transitive_runfiles.append(target[DefaultInfo].default_runfiles)
    runfiles = runfiles.merge_all(transitive_runfiles)
    return [
        DefaultInfo(..., runfiles = runfiles),
        ...
    ]

ผู้ให้บริการที่กําหนดเอง

คุณจะกำหนดผู้ให้บริการได้โดยใช้ฟังก์ชัน provider เพื่อแสดงข้อมูลเฉพาะของกฎ ดังนี้

ExampleInfo = provider(
    "Info needed to compile/link Example code.",
    fields={
        "headers": "depset of header Files from transitive dependencies.",
        "files_to_link": "depset of Files from compilation.",
    })

จากนั้นฟังก์ชันการใช้งานกฎจะสร้างและแสดงผลอินสแตนซ์ของผู้ให้บริการ ดังนี้

def _example_library_impl(ctx):
  ...
  return [
      ...
      ExampleInfo(
          headers = headers,
          files_to_link = depset(
              [output_file],
              transitive = [
                  dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
              ],
          ),
      )
  ]

เริ่มต้นใช้งานผู้ให้บริการที่กำหนดเอง

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

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

ในกรณีนี้ เมื่อมีการเรียกสัญลักษณ์ผู้ให้บริการ แทนที่จะส่งคืนอินสแตนซ์ใหม่โดยตรง ระบบจะส่งต่ออาร์กิวเมนต์ไปตาม Callback init ค่าที่แสดงผลของ callback ต้องเป็นพจนานุกรมที่แมปชื่อฟิลด์ (สตริง) กับค่า ซึ่งจะใช้เพื่อเริ่มต้นฟิลด์ของอินสแตนซ์ใหม่ โปรดทราบว่า Callback อาจมีลายเซ็นและหากอาร์กิวเมนต์ไม่ตรงกับลายเซ็น ระบบจะรายงานข้อผิดพลาดเสมือนว่ามีการเรียกใช้ Callback โดยตรง

ในทางตรงกันข้าม เครื่องมือสร้างแบบดิบจะข้ามการเรียกกลับ init

ตัวอย่างต่อไปนี้ใช้ init เพื่อประมวลผลก่อนและตรวจสอบอาร์กิวเมนต์

# //pkg:exampleinfo.bzl

_core_headers = [...]  # private constant representing standard library files

# It's possible to define an init accepting positional arguments, but
# keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
    if not files_to_link and not allow_empty_files_to_link:
        fail("files_to_link may not be empty")
    all_headers = depset(_core_headers, transitive = headers)
    return {'files_to_link': files_to_link, 'headers': all_headers}

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init)

export ExampleInfo

จากนั้น การใช้กฎอาจสร้างตัวอย่างผู้ให้บริการดังนี้

    ExampleInfo(
        files_to_link=my_files_to_link,  # may not be empty
        headers = my_headers,  # will automatically include the core headers
    )

เครื่องมือสร้างแบบดิบสามารถใช้เพื่อกำหนดฟังก์ชันการสร้างแบบสาธารณะทางเลือกซึ่งไม่ผ่านตรรกะ init เช่น ใน exampleinfo.bzl เราสามารถนิยามได้ว่า

def make_barebones_exampleinfo(headers):
    """Returns an ExampleInfo with no files_to_link and only the specified headers."""
    return _new_exampleinfo(files_to_link = depset(), headers = all_headers)

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

การใช้งานอีกอย่างหนึ่งสำหรับ init คือการป้องกันไม่ให้ผู้ใช้เรียกสัญลักษณ์ผู้ให้บริการไปเลยและบังคับให้ใช้ฟังก์ชันเริ่มต้นแทน ดังนี้

def _exampleinfo_init_banned(*args, **kwargs):
    fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init_banned)

def make_exampleinfo(...):
    ...
    return _new_exampleinfo(...)

กฎที่ดำเนินการได้และกฎการทดสอบ

กฎปฏิบัติการจะกำหนดเป้าหมายที่คำสั่ง bazel run เรียกใช้ได้ กฎการทดสอบคือกฎปฏิบัติการชนิดพิเศษ ซึ่งเป้าหมายจะเรียกใช้ได้ด้วยคำสั่ง bazel test เช่นกัน กฎดำเนินการและกฎทดสอบสร้างขึ้นโดยการตั้งค่าอาร์กิวเมนต์ executable หรือ test ที่เกี่ยวข้องเป็น True ในการเรียก rule ดังนี้

example_binary = rule(
   implementation = _example_binary_impl,
   executable = True,
   ...
)

example_test = rule(
   implementation = _example_binary_impl,
   test = True,
   ...
)

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

กฎทั้ง 2 ประเภทต้องสร้างไฟล์เอาต์พุตที่เรียกใช้งานได้ (ซึ่งอาจประกาศไว้ล่วงหน้าหรือไม่ก็ได้) ซึ่งจะเรียกใช้โดยคำสั่ง run หรือ test หากต้องการบอก Bazel ว่าให้ใช้เอาต์พุตของกฎใดเป็นไฟล์ปฏิบัติการนี้ ให้ส่งเป็นexecutableอาร์กิวเมนต์ของผู้ให้บริการ DefaultInfo ที่แสดงผล ระบบจะเพิ่ม executable ลงในเอาต์พุตเริ่มต้นของกฎ (คุณจึงไม่จำเป็นต้องส่งพารามิเตอร์นั้นไปยังทั้ง executable และ files) และยังเพิ่มลงในrunfilesโดยปริยายด้วย

def _example_binary_impl(ctx):
    executable = ctx.actions.declare_file(ctx.label.name)
    ...
    return [
        DefaultInfo(executable = executable, ...),
        ...
    ]

การดำเนินการที่สร้างไฟล์นี้ต้องตั้งค่าบิตปฏิบัติการในไฟล์ สําหรับการดําเนินการ ctx.actions.run หรือ ctx.actions.run_shell การดำเนินการนี้ควรทำโดยเครื่องมือพื้นฐานที่เรียกใช้โดยการดำเนินการ สำหรับการดำเนินการ ctx.actions.write ให้ส่งผ่าน is_executable=True

กฎที่เรียกใช้ได้จะมีเอาต์พุต ctx.outputs.executable พิเศษที่ประกาศไว้ล่วงหน้าตามลักษณะการทำงานเดิม ไฟล์นี้จะใช้เป็นไฟล์ที่ดำเนินการได้เริ่มต้นหากคุณไม่ได้ระบุไฟล์โดยใช้ DefaultInfo และจะต้องไม่ใช้ไฟล์นี้ในกรณีอื่น เราไม่แนะนำให้ใช้กลไกเอาต์พุตนี้เนื่องจากไม่รองรับการปรับแต่งชื่อไฟล์ที่เรียกใช้งานได้ ณ เวลาวิเคราะห์

ดูตัวอย่างกฎที่เรียกใช้ได้และกฎทดสอบ

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

def example_test(size="small", **kwargs):
  _example_test(size=size, **kwargs)

_example_test = rule(
 ...
)

ตำแหน่งของไฟล์เรียกใช้

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

# Given launcher_path and runfile_file:
runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (
    runfiles_root, workspace_name, runfile_path)

เส้นทางไปยัง File ในไดเรกทอรี runfiles จะสอดคล้องกับ File.short_path

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

หัวข้อขั้นสูง

การขอไฟล์เอาต์พุต

เป้าหมายเดียวมีไฟล์เอาต์พุตได้หลายไฟล์ เมื่อเรียกใช้คำสั่ง bazel build ระบบจะถือว่าเอาต์พุตบางส่วนของเป้าหมายที่ส่งไปยังคำสั่งนั้นขอ Bazel จะสร้างเฉพาะไฟล์ที่ขอเหล่านี้และไฟล์ที่ไฟล์ดังกล่าวต้องอาศัยโดยตรงหรือโดยอ้อม (ในแง่ของกราฟการดำเนินการ Bazel จะดำเนินการเฉพาะการดำเนินการที่เข้าถึงได้ในฐานะทรัพยากร Dependency แบบเปลี่ยนผ่านของไฟล์ที่ขอ)

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

นอกจากเอาต์พุตเริ่มต้นแล้ว ยังมีกลุ่มเอาต์พุตซึ่งเป็นคอลเล็กชันของไฟล์เอาต์พุตที่อาจขอร่วมกันด้วย โดยสามารถขอข้อมูลเหล่านี้ได้โดยใช้ --output_groups เช่น หาก //pkg:mytarget เป้าหมายเป็นกฎประเภทที่มีกลุ่มเอาต์พุต debug_files ระบบจะสร้างไฟล์เหล่านี้ได้โดยการรัน bazel build //pkg:mytarget --output_groups=debug_files เนื่องจากเอาต์พุตที่ไม่ได้ประกาศไว้ล่วงหน้าจะไม่มีป้ายกำกับ คุณจึงขอเอาต์พุตดังกล่าวได้โดยการปรากฏในเอาต์พุตเริ่มต้นหรือกลุ่มเอาต์พุตเท่านั้น

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

def _example_library_impl(ctx):
    ...
    debug_file = ctx.actions.declare_file(name + ".pdb")
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        OutputGroupInfo(
            debug_files = depset([debug_file]),
            all_files = depset([output_file, debug_file]),
        ),
        ...
    ]

และต่างจากผู้ให้บริการส่วนใหญ่ตรงที่สามารถแสดง OutputGroupInfo จากทั้ง aspect และเป้าหมายของกฎที่ใช้กับลักษณะนั้น ตราบใดที่ไม่ได้กำหนดกลุ่มเอาต์พุตเดียวกัน ในกรณีนี้ ระบบจะรวมผู้ให้บริการ ที่ได้เข้าด้วยกัน

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

การกำหนดค่า

สมมติว่าคุณต้องการสร้างไบนารี C++ สำหรับสถาปัตยกรรมอื่น การสร้างอาจมีความซับซ้อนและมีหลายขั้นตอน ไบนารีระดับกลางบางรายการ เช่น คอมไพเลอร์และโปรแกรมสร้างโค้ด ต้องทำงานบนแพลตฟอร์มการดำเนินการ (ซึ่งอาจเป็นโฮสต์ของคุณหรือโอเปอเรเตอร์ระยะไกล) ต้องสร้างไบนารีบางรายการ เช่น เอาต์พุตสุดท้าย สำหรับสถาปัตยกรรมเป้าหมาย

ด้วยเหตุนี้ Bazel จึงมีแนวคิด "การกำหนดค่า" และการเปลี่ยน เป้าหมายที่อยู่บนสุด (เป้าหมายที่ขอในบรรทัดคำสั่ง) จะสร้างขึ้นในการกําหนดค่า "target" ส่วนเครื่องมือที่ควรทํางานบนแพลตฟอร์มการดําเนินการจะสร้างขึ้นในการกําหนดค่า "exec" กฎอาจสร้างการดำเนินการที่แตกต่างกันตามการกำหนดค่า เช่น เปลี่ยนสถาปัตยกรรม CPU ที่ส่งไปยังคอมไพเลอร์ ในบางกรณี คุณอาจต้องใช้คลังเดียวกันสำหรับการกําหนดค่าที่แตกต่างกัน หากเกิดกรณีเช่นนี้ เราจะวิเคราะห์และสร้างขึ้นหลายครั้ง

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

สําหรับแอตทริบิวต์การพึ่งพาแต่ละรายการ คุณสามารถใช้ cfg เพื่อตัดสินใจว่าควรสร้างการพึ่งพาในการกําหนดค่าเดียวกันหรือเปลี่ยนไปใช้การกําหนดค่า exec หากแอตทริบิวต์การขึ้นต่อกันมี Flag executable=True คุณต้องตั้งค่า cfg อย่างชัดเจน เพื่อป้องกันการสร้างเครื่องมือสำหรับการกำหนดค่าที่ไม่ถูกต้องโดยไม่ตั้งใจ ดูตัวอย่าง

โดยทั่วไปแล้ว แหล่งที่มา ไลบรารีที่เกี่ยวข้อง และไฟล์ปฏิบัติการที่ต้องใช้รันไทม์จะใช้การกำหนดค่าเดียวกันได้

เครื่องมือที่ดำเนินการเป็นส่วนหนึ่งของบิลด์ (เช่น คอมไพเลอร์หรือโปรแกรมสร้างโค้ด) ควรสร้างขึ้นเพื่อการกำหนดค่าปฏิบัติการ ในกรณีนี้ ให้ระบุ cfg="exec" ในแอตทริบิวต์

มิเช่นนั้น คุณควรสร้างไฟล์ปฏิบัติการที่ใช้ในรันไทม์ (เช่น เป็นส่วนหนึ่งของการทดสอบ) สำหรับการกำหนดค่าเป้าหมาย ในกรณีนี้ ให้ระบุ cfg="target" ในแอตทริบิวต์

cfg="target" ไม่ได้ทําอะไรเลย เป็นเพียงค่าที่สะดวกเพื่อช่วยให้ผู้ออกแบบกฎระบุความตั้งใจของตนอย่างชัดเจน เมื่อ executable=False ซึ่งหมายความว่า cfg ไม่บังคับ ให้ตั้งค่านี้เฉพาะในกรณีที่ช่วยให้อ่านได้ง่ายจริงๆ

คุณยังใช้ cfg=my_transition เพื่อใช้การเปลี่ยนที่ผู้ใช้กําหนด ได้ด้วย ซึ่งช่วยให้ผู้เขียนกฎมีความยืดหยุ่นมากในการเปลี่ยนแปลงการกําหนดค่า ด้วยการทำให้กราฟบิลด์มีขนาดใหญ่ขึ้นและเข้าใจได้ง่ายขึ้น

หมายเหตุ: ในอดีต Bazel ไม่มีแนวคิดเรื่องแพลตฟอร์มการดำเนินการ จึงถือว่าการทำงานของบิลด์ทั้งหมดทำงานในเครื่องโฮสต์แทน Bazel เวอร์ชันก่อน 6.0 ได้สร้างการกำหนดค่า "โฮสต์" ที่แยกต่างหากเพื่อแสดงข้อมูลนี้ หากคุณเห็นการอ้างอิงถึง "โฮสต์" ในโค้ดหรือเอกสารประกอบเก่า รายการนี้หมายถึงโฮสต์ดังกล่าว เราขอแนะนำให้ใช้ Bazel 6.0 ขึ้นไปเพื่อหลีกเลี่ยงค่าใช้จ่ายเพิ่มเติมนี้

ข้อมูลโค้ดการกําหนดค่า

กฎอาจเข้าถึงส่วนย่อยของการกำหนดค่า เช่น cpp, java และ jvm อย่างไรก็ตาม คุณต้องประกาศส่วนย่อยที่จำเป็นทั้งหมดเพื่อหลีกเลี่ยงข้อผิดพลาดในการเข้าถึง ดังนี้

def _impl(ctx):
    # Using ctx.fragments.cpp leads to an error since it was not declared.
    x = ctx.fragments.java
    ...

my_rule = rule(
    implementation = _impl,
    fragments = ["java"],      # Required fragments of the target configuration
    host_fragments = ["java"], # Required fragments of the host configuration
    ...
)

ลิงก์สัญลักษณ์ของ Runfile

โดยทั่วไป เส้นทางแบบสัมพัทธ์ของไฟล์ในต้นไม้ runfiles จะเหมือนกับเส้นทางแบบสัมพัทธ์ของไฟล์นั้นในต้นไม้ต้นทางหรือต้นไม้เอาต์พุตที่สร้างขึ้น หากค่าเหล่านี้ต้องแตกต่างกันด้วยเหตุผลบางอย่าง ให้ระบุอาร์กิวเมนต์ root_symlinks หรือ symlinks root_symlinks คือพจนานุกรมที่จับคู่เส้นทางกับไฟล์ โดยเส้นทางจะสัมพันธ์กับรูทของไดเรกทอรี runfiles พจนานุกรม symlinks จะเหมือนกัน แต่เส้นทางจะมีชื่อของเวิร์กスペースหลักอยู่ข้างหน้าโดยนัย (ไม่ใช่ชื่อของที่เก็บซึ่งมีเป้าหมายปัจจุบัน)

    ...
    runfiles = ctx.runfiles(
        root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
        symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
    )
    # Creates something like:
    # sometarget.runfiles/
    #     some/
    #         path/
    #             here.foo -> some_data_file2
    #     <workspace_name>/
    #         some/
    #             path/
    #                 here.bar -> some_data_file3

หากใช้ symlinks หรือ root_symlinks โปรดระมัดระวังอย่าแมปไฟล์ 2 ไฟล์ที่ต่างกันกับเส้นทางเดียวกันในโครงสร้างการเรียกใช้ไฟล์ ซึ่งจะทำให้บิลด์ทำงานไม่สำเร็จ พร้อมทั้งแสดงข้อผิดพลาดในการอธิบายความขัดแย้ง หากต้องการแก้ไข คุณจะต้องแก้ไขอาร์กิวเมนต์ ctx.runfiles เพื่อนำข้อขัดแย้งออก ระบบจะทำการตรวจสอบนี้กับเป้าหมายที่ใช้กฎของคุณ รวมถึงเป้าหมายทุกประเภทที่ขึ้นอยู่กับเป้าหมายเหล่านั้น ซึ่งมีความเสี่ยงอย่างยิ่งหากเครื่องมืออื่นมีแนวโน้มที่จะใช้เครื่องมือของคุณแบบทรานซิชัน โดยชื่อลิงก์สัญลักษณ์ต้องไม่ซ้ำกันในทุกการเรียกใช้ไฟล์ของเครื่องมือและการอ้างอิงทั้งหมด

ความครอบคลุมของโค้ด

เมื่อเรียกใช้คําสั่ง coverage บิลด์อาจต้องเพิ่มเครื่องมือวัดการครอบคลุมสําหรับเป้าหมายบางรายการ นอกจากนี้ บิลด์ยังจะรวบรวมรายการไฟล์ต้นฉบับที่มีการวัดคุมด้วย ชุดย่อยของเป้าหมายที่ได้รับการพิจารณาจะควบคุมโดยแฟล็ก --instrumentation_filter จะยกเว้นเป้าหมายทดสอบไว้ เว้นแต่จะระบุ --instrument_test_targets ไว้

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

# Are this rule's sources instrumented?
if ctx.coverage_instrumented():
  # Do something to turn on coverage for this compile action

ตรรกะที่จำเป็นต้องเปิดอยู่เสมอในโหมดการครอบคลุม (ไม่ว่าจะมีเครื่องมือวัดแหล่งที่มาของเป้าหมายโดยเฉพาะหรือไม่) สามารถกำหนดเงื่อนไขได้โดยใช้ ctx.configuration.coverage_enabled

หากกฎรวมแหล่งที่มาจากทรัพยากร Dependency โดยตรงก่อนการคอมไพล์ (เช่น ไฟล์ส่วนหัว) กฎอาจต้องเปิดการวัดคุมเวลาคอมไพล์ด้วยในกรณีที่ควรใช้ทรัพยากรของทรัพยากร Dependency ด้วย

# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
    (ctx.coverage_instrumented() or
     any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
    # Do something to turn on coverage for this compile action

นอกจากนี้ กฎควรให้ข้อมูลเกี่ยวกับแอตทริบิวต์ที่เกี่ยวข้องสำหรับการครอบคลุมด้วยผู้ให้บริการ InstrumentedFilesInfo ซึ่งสร้างขึ้นโดยใช้ coverage_common.instrumented_files_info พารามิเตอร์ dependency_attributes ของ instrumented_files_info ควรแสดงรายการแอตทริบิวต์การอ้างอิงรันไทม์ทั้งหมด รวมถึงการอ้างอิงโค้ด เช่น deps และการอ้างอิงข้อมูล เช่น data พารามิเตอร์ source_attributes ควรแสดงรายการแอตทริบิวต์ไฟล์ต้นทางของกฎ หากอาจเพิ่มเครื่องมือวัดการครอบคลุม

def _example_library_impl(ctx):
    ...
    return [
        ...
        coverage_common.instrumented_files_info(
            ctx,
            dependency_attributes = ["deps", "data"],
            # Omitted if coverage is not supported for this rule:
            source_attributes = ["srcs", "hdrs"],
        )
        ...
    ]

หากระบบไม่แสดงผล InstrumentedFilesInfo ระบบจะสร้าง InstrumentedFilesInfo เริ่มต้นขึ้นโดยมีค่าแอตทริบิวต์ความเกี่ยวข้องที่ไม่ใช่เครื่องมือแต่ละรายการ (ซึ่งไม่ได้ตั้งค่า cfg เป็น "host" หรือ "exec" ในสคีมาแอตทริบิวต์) ใน dependency_attributes (ลักษณะการทำงานนี้ไม่เหมาะ เนื่องจากจะใส่แอตทริบิวต์อย่าง srcs ใน dependency_attributes แทน source_attributes แต่จะช่วยหลีกเลี่ยงการกำหนดค่าการครอบคลุมที่ชัดเจนสำหรับกฎทั้งหมดในเชนการพึ่งพา)

การดำเนินการตรวจสอบ

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

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

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

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

วิธีนี้ใช้งานได้เนื่องจาก Bazel จะเรียกใช้การดำเนินการตรวจสอบทุกครั้งที่เรียกใช้การดำเนินการคอมไพล์ แต่มีข้อเสียที่สำคัญดังนี้

1. การดำเนินการตรวจสอบอยู่ในเส้นทางวิกฤติของบิลด์ เนื่องจาก Bazel คิดว่าต้องมีเอาต์พุตว่างจึงจะเรียกใช้การดำเนินการคอมไพล์ได้ จึงจะเรียกใช้การดำเนินการตรวจสอบก่อน แม้ว่าการดำเนินการคอมไพล์จะไม่สนใจอินพุตก็ตาม ซึ่งจะลดการทำงานแบบขนานและทำให้บิลด์ช้าลง

2. หากการดําเนินการอื่นๆ ในบิลด์อาจทํางานแทนการดําเนินการคอมไพล์ ก็จะต้องเพิ่มเอาต์พุตว่างของการดําเนินการตรวจสอบไปยังการดําเนินการเหล่านั้นด้วย (เช่น เอาต์พุต jar แหล่งที่มาของ java_library) การดำเนินการนี้ยังเป็นปัญหาหากมีการเพิ่มการดำเนินการใหม่ที่อาจทำงานแทนการดำเนินการคอมไพล์ในภายหลัง และไม่ได้ออกผลการตรวจสอบที่ว่างเปล่าไว้โดยไม่ตั้งใจ

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

กลุ่มเอาต์พุตของการตรวจสอบ

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

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

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

การตรวจสอบความถูกต้องของเป้าหมายจะไม่ทำงานใน 3 กรณีต่อไปนี้

• เมื่อใช้เป้าหมายเป็นเครื่องมือ
• เมื่อเป้าหมายเป็นข้อกําหนดโดยนัย (เช่น แอตทริบิวต์ที่ขึ้นต้นด้วย "_")
• เมื่อสร้างเป้าหมายในการกําหนดค่าโฮสต์หรือ exec

โดยสมมติว่าเป้าหมายเหล่านี้มีบิลด์และการทดสอบแยกต่างหากซึ่งจะเปิดเผยความล้มเหลวในการตรวจสอบ

การใช้กลุ่มเอาต์พุตของการตรวจสอบความถูกต้อง

กลุ่มเอาต์พุตการตรวจสอบมีชื่อว่า _validation และใช้เหมือนกับกลุ่มเอาต์พุตอื่นๆ ดังนี้

def _rule_with_validation_impl(ctx):

  ctx.actions.write(ctx.outputs.main, "main output\n")

  ctx.actions.write(ctx.outputs.implicit, "implicit output\n")

  validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
  ctx.actions.run(
      outputs = [validation_output],
      executable = ctx.executable._validation_tool,
      arguments = [validation_output.path])

  return [
    DefaultInfo(files = depset([ctx.outputs.main])),
    OutputGroupInfo(_validation = depset([validation_output])),
  ]


rule_with_validation = rule(
  implementation = _rule_with_validation_impl,
  outputs = {
    "main": "%{name}.main",
    "implicit": "%{name}.implicit",
  },
  attrs = {
    "_validation_tool": attr.label(
        default = Label("//validation_actions:validation_tool"),
        executable = True,
        cfg = "exec"),
  }
)

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

โดยปกติแล้ว ผลลัพธ์ของการดำเนินการตรวจสอบควรส่งไปยังกลุ่มผลลัพธ์การตรวจสอบเท่านั้น และไม่ควรเพิ่มลงในอินพุตของการดำเนินการอื่นๆ เนื่องจากอาจทำให้ประสิทธิภาพการทำงานแบบขนานลดลง อย่างไรก็ตาม โปรดทราบว่าขณะนี้ Bazel ยังไม่มีการตรวจสอบพิเศษเพื่อบังคับใช้ ดังนั้น คุณควรทดสอบว่าจะไม่มีการเพิ่มเอาต์พุตการดำเนินการตรวจสอบลงในอินพุตของการดำเนินการใดๆ ในการทดสอบกฎของ Starlark เช่น

load("@bazel_skylib//lib:unittest.bzl", "analysistest")

def _validation_outputs_test_impl(ctx):
  env = analysistest.begin(ctx)

  actions = analysistest.target_actions(env)
  target = analysistest.target_under_test(env)
  validation_outputs = target.output_groups._validation.to_list()
  for action in actions:
    for validation_output in validation_outputs:
      if validation_output in action.inputs.to_list():
        analysistest.fail(env,
            "%s is a validation action output, but is an input to action %s" % (
                validation_output, action))

  return analysistest.end(env)

validation_outputs_test = analysistest.make(_validation_outputs_test_impl)

แฟล็กการดำเนินการตรวจสอบ

การดำเนินการตรวจสอบที่ทำงานอยู่จะควบคุมโดย Flag --run_validations บรรทัดคำสั่ง ซึ่งค่าเริ่มต้นคือ "จริง"

ฟีเจอร์ที่เลิกใช้งาน

เอาต์พุตที่ประกาศไว้ล่วงหน้าซึ่งเลิกใช้งานแล้ว

การใช้ผลลัพธ์ที่ประกาศไว้ล่วงหน้ามีวิธีเลิกใช้งาน 2 วิธีดังนี้

• พารามิเตอร์ outputs ของ rule จะระบุการแมประหว่างชื่อแอตทริบิวต์เอาต์พุตกับเทมเพลตสตริงสำหรับสร้างป้ายกำกับเอาต์พุตที่ประกาศไว้ล่วงหน้า ต้องการใช้เอาต์พุตที่ไม่ได้ประกาศล่วงหน้าและเพิ่มเอาต์พุตไปยัง DefaultInfo.files อย่างชัดแจ้ง ใช้ป้ายกำกับของเป้าหมายกฎเป็นอินพุตสำหรับกฎที่ใช้เอาต์พุตแทนป้ายกำกับของเอาต์พุตที่ประกาศล่วงหน้า

• สำหรับกฎปฏิบัติการ ctx.outputs.executable จะหมายถึงเอาต์พุตปฏิบัติการที่ประกาศล่วงหน้าซึ่งมีชื่อเดียวกับเป้าหมายของกฎ คุณควรประกาศเอาต์พุตอย่างชัดแจ้ง เช่น ด้วย ctx.actions.declare_file(ctx.label.name) และตรวจสอบว่าคำสั่งที่สร้างไฟล์ปฏิบัติการกำหนดสิทธิ์เพื่ออนุญาตการดำเนินการ ส่งเอาต์พุตที่เป็นไฟล์ปฏิบัติการไปยังพารามิเตอร์ executable ของ DefaultInfo อย่างชัดเจน

ฟีเจอร์ของ Runfiles ที่ควรหลีกเลี่ยง

ctx.runfiles และประเภท runfiles มีชุดฟีเจอร์ที่ซับซ้อน ฟีเจอร์หลายชุดจะเก็บไว้ตามเดิม คําแนะนําต่อไปนี้จะช่วยลดความซับซ้อน

• หลีกเลี่ยงการใช้โหมด collect_data และ collect_default ของ ctx.runfiles โหมดเหล่านี้จะรวบรวมไฟล์รันไทม์โดยปริยายในขอบเขตของขอบเขตการพึ่งพาที่ฮาร์ดโค้ดไว้บางรายการในลักษณะที่ทำให้เกิดความสับสน แต่ให้เพิ่มไฟล์โดยใช้พารามิเตอร์ files หรือ transitive_files ของ ctx.runfiles หรือผสานในไฟล์การเรียกใช้จากทรัพยากร Dependency ด้วย runfiles = runfiles.merge(dep[DefaultInfo].default_runfiles) แทน

• หลีกเลี่ยงการใช้ data_runfiles และ default_runfiles ของเครื่องมือสร้าง DefaultInfo โปรดระบุ DefaultInfo(runfiles = ...) แทน ความแตกต่างระหว่างไฟล์การเรียกใช้ "เริ่มต้น" และ "ข้อมูล" จะยังคงอยู่ตามเดิม เช่น กฎบางข้อจะใส่เอาต์พุตเริ่มต้นไว้ใน data_runfiles แต่ไม่ใส่ default_runfiles แทนที่จะใช้ data_runfiles กฎควรทั้งคู่รวมเอาต์พุตเริ่มต้นและรวม default_runfiles จากแอตทริบิวต์ที่มีการเรียกใช้ไฟล์ (ซึ่งมักจะเป็น data)

• เมื่อดึงข้อมูล runfiles จาก DefaultInfo (โดยทั่วไปมีไว้สำหรับการผสานไฟล์เรียกใช้ระหว่างกฎปัจจุบันกับรายการที่เกี่ยวข้องเท่านั้น) ให้ใช้ DefaultInfo.default_runfiles ไม่ใช่ DefaultInfo.data_runfiles

การย้ายข้อมูลจากผู้ให้บริการเดิม

ก่อนหน้านี้ ผู้ให้บริการ Bazel คือช่องแบบง่ายในออบเจ็กต์ Target โดยเข้าถึงโดยใช้โอเปอเรเตอร์จุด และสร้างโดยใส่ช่องในสตรูคเจอร์ที่แสดงผลโดยฟังก์ชันการใช้งานของกฎ

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

ขณะนี้ระบบยังคงรองรับผู้ให้บริการเดิมอยู่ กฎจะแสดงทั้งผู้ให้บริการแบบเดิมและแบบใหม่ได้ ดังนี้

def _old_rule_impl(ctx):
  ...
  legacy_data = struct(x="foo", ...)
  modern_data = MyInfo(y="bar", ...)
  # When any legacy providers are returned, the top-level returned value is a
  # struct.
  return struct(
      # One key = value entry for each legacy provider.
      legacy_info = legacy_data,
      ...
      # Additional modern providers:
      providers = [modern_data, ...])

หาก dep คือออบเจ็กต์ Target ที่ได้สําหรับอินสแตนซ์ของกฎนี้ ระบบจะดึงข้อมูลผู้ให้บริการและเนื้อหาของผู้ให้บริการเป็น dep.legacy_info.x และ dep[MyInfo].y

นอกจาก providers แล้ว โครงสร้างที่แสดงผลยังใช้ฟิลด์อื่นๆ อีกหลายฟิลด์ที่มีความหมายพิเศษได้ด้วย (และจึงไม่สร้างผู้ให้บริการเดิมที่เกี่ยวข้อง) ดังนี้

• ช่อง files, runfiles, data_runfiles, default_runfiles และ executable สอดคล้องกับช่องที่มีชื่อเดียวกันของ DefaultInfo ไม่อนุญาตให้ระบุช่องเหล่านี้ แต่ในขณะเดียวกันก็แสดงผลผู้ให้บริการ DefaultInfo ด้วย

• ฟิลด์ output_groups ใช้ค่าสตริงและสอดคล้องกับ OutputGroupInfo

ในการประกาศกฎของ provides และในการประกาศแอตทริบิวต์ทรัพยากร Dependency ใน providers ระบบจะส่งผู้ให้บริการเดิมเข้ามาในรูปแบบสตริงและผู้ให้บริการที่ทันสมัยผ่านสัญลักษณ์ *Info อย่าลืมเปลี่ยนจากสตริงเป็นสัญลักษณ์เมื่อย้ายข้อมูล สําหรับชุดกฎที่ซับซ้อนหรือมีขนาดใหญ่ซึ่งอัปเดตกฎทั้งหมดพร้อมกันได้ยาก คุณอาจทําได้ง่ายขึ้นหากทําตามลําดับขั้นตอนต่อไปนี้

1. แก้ไขกฎที่สร้างผู้ให้บริการรายเดิมเพื่อสร้างทั้งผู้ให้บริการรายเดิมและผู้ให้บริการสมัยใหม่ โดยใช้ไวยากรณ์ข้างต้น สําหรับกฎที่ประกาศว่าแสดงผู้ให้บริการเดิม ให้อัปเดตการประกาศดังกล่าวให้รวมทั้งผู้ให้บริการเดิมและผู้ให้บริการสมัยใหม่

2. แก้ไขกฎที่ใช้ผู้ให้บริการรายเดิมเพื่อใช้ผู้ให้บริการสมัยใหม่แทน หากการประกาศแอตทริบิวต์ใดๆ ต้องใช้ผู้ให้บริการเดิม ให้อัปเดตการประกาศดังกล่าวให้ต้องใช้ผู้ให้บริการสมัยใหม่แทน คุณอาจสลับขั้นตอนนี้กับขั้นตอนที่ 1 โดยให้ผู้บริโภคยอมรับ/กำหนดผู้ให้บริการรายใดรายหนึ่งก็ได้ โดยทดสอบหาผู้ให้บริการเดิมโดยใช้ hasattr(target, 'foo') หรือผู้ให้บริการรายใหม่โดยใช้ FooInfo in target

3. นําผู้ให้บริการเดิมออกจากกฎทั้งหมดอย่างสมบูรณ์