กฎแพลตฟอร์ม

กฎ

• constraint_setting
• constraint_value
• แพลตฟอร์ม
• เครื่องมือเชน
• toolchain_type

constraint_setting

constraint_setting(name, default_constraint_value, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)

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

constraint_setting แต่ละรายการมีชุด constraint_value ที่เชื่อมโยงที่ขยายได้ โดยปกติจะมีการกำหนดเหล่านี้ในแพ็กเกจเดียวกัน แต่บางครั้งแพ็กเกจอื่นจะแนะนำค่าใหม่สำหรับการตั้งค่าที่มีอยู่ เช่น การตั้งค่า @platforms//cpu:cpu ที่กำหนดไว้ล่วงหน้าสามารถขยายได้ด้วยค่าที่กำหนดเองเพื่อกำหนดแพลตฟอร์มที่กำหนดเป้าหมายสถาปัตยกรรม CPU ที่ไม่ชัดเจน

อาร์กิวเมนต์

Attributes
name	Name; required ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
default_constraint_value	Name; optional; nonconfigurable ป้ายกำกับของค่าเริ่มต้นสำหรับการตั้งค่านี้ ซึ่งจะนำมาใช้หากไม่มีการระบุค่า หากมีแอตทริบิวต์นี้อยู่ คุณต้องกำหนด constraint_value ที่ชี้ไปยังแพ็กเกจเดียวกับ constraint_setting นี้ หากการตั้งค่าข้อจํากัดมีค่าเริ่มต้น เมื่อใดก็ตามที่แพลตฟอร์มไม่มีค่าข้อจํากัดสําหรับการตั้งค่านั้น การตั้งค่าดังกล่าวจะเหมือนกับการที่แพลตฟอร์มระบุค่าเริ่มต้นไว้ มิเช่นนั้น หากไม่มีค่าเริ่มต้น ระบบจะถือว่าการตั้งค่าข้อจำกัดนั้นไม่ได้ระบุโดยแพลตฟอร์มนั้น ในกรณีนี้ แพลตฟอร์มจะไม่จับคู่กับรายการข้อจำกัดใดๆ (เช่น สำหรับ config_setting) ที่ต้องใช้ค่าที่เจาะจงสำหรับการตั้งค่านั้น

constraint_value

constraint_value(name, constraint_setting, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)

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

ตัวอย่าง

ตัวอย่างต่อไปนี้สร้างค่าใหม่ที่เป็นไปได้สำหรับ constraint_value ซึ่งแสดงถึงสถาปัตยกรรม CPU ที่กำหนดไว้ล่วงหน้า

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

จากนั้นแพลตฟอร์มจะประกาศได้ว่ามีสถาปัตยกรรม mips เป็นอีกทางเลือกหนึ่งนอกเหนือจาก x86_64, arm และอื่นๆ

อาร์กิวเมนต์

Attributes
name	Name; required ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
constraint_setting	Label; required; nonconfigurable constraint_setting ซึ่ง constraint_value นี้เป็นตัวเลือกที่เป็นไปได้

platform

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

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

ตัวอย่าง

แอตทริบิวต์นี้ระบุแพลตฟอร์มที่อธิบายสภาพแวดล้อมที่ใช้งาน Linux บน ARM

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

การรับช่วงแพลตฟอร์ม

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

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

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

นอกจากนี้ แพลตฟอร์มยังรับค่าแอตทริบิวต์ remote_execution_properties (เลิกใช้งานแล้ว) จากแพลตฟอร์มหลักได้ด้วย หมายเหตุ: รหัสใหม่ควรใช้ exec_properties แทน ตรรกะที่อธิบายไว้ด้านล่างจะยังคงใช้ได้กับลักษณะการทำงานเดิม แต่จะมีการนําออกในอนาคต ตรรกะสําหรับการตั้งค่า remote_execution_platform จะเป็นดังนี้เมื่อมีแพลตฟอร์มระดับบนสุด

1. หากไม่ได้ตั้งค่า remote_execution_property ในแพลตฟอร์มย่อย ระบบจะใช้ remote_execution_properties ของผู้เผยแพร่โฆษณาหลัก
2. หากตั้งค่า remote_execution_property ในแพลตฟอร์มย่อยและมีสตริงตามตัวอักษร {PARENT_REMOTE_EXECUTION_PROPERTIES} มาโครดังกล่าวจะถูกแทนที่ด้วยเนื้อหาของแอตทริบิวต์ remote_execution_property ของระดับบนสุด
3. หากตั้งค่า remote_execution_property ในแพลตฟอร์มย่อยและไม่มีมาโคร ระบบจะใช้ remote_execution_property ของผู้เผยแพร่โฆษณาย่อยต่อไป

เนื่องจาก remote_execution_properties เลิกใช้งานแล้วและจะทยอยเลิกใช้งาน โดยจะไม่อนุญาตให้ผสม remote_execution_properties และ exec_properties ในเชนการรับช่วงค่าเดียวกัน ต้องการใช้ exec_properties มากกว่า remote_execution_properties ที่เลิกใช้งานแล้ว

ตัวอย่าง: ค่าจำกัด

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

ในตัวอย่างนี้ แพลตฟอร์มย่อยมีพร็อพเพอร์ตี้ต่อไปนี้

• child_a มีค่าข้อจํากัด @platforms//os:linux (รับค่ามาจากระดับบนสุด) และ @platforms//cpu:x86_64 (ตั้งค่าในแพลตฟอร์มโดยตรง)
• child_b รับค่าข้อจำกัดทั้งหมดจากระดับบนสุดและไม่ได้ตั้งค่าของตนเอง

ตัวอย่าง: พร็อพเพอร์ตี้การดำเนินการ

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

ในตัวอย่างนี้ แพลตฟอร์มย่อยมีพร็อพเพอร์ตี้ต่อไปนี้

• child_a รับค่า "exec_properties" ระดับบนสุดและไม่ได้ตั้งค่าของตนเอง
• child_b รับค่า exec_properties ระดับบนสุดและลบล้างค่าของ k1 exec_properties จะเป็น { "k1": "child", "k2": "v2" }
• child_c จะรับค่า exec_properties ของผู้ปกครองและเลิกตั้งค่า k1 exec_properties จะเป็น { "k2": "v2" }
• child_d รับค่า exec_properties ของระดับบนสุดและเพิ่มพร็อพเพอร์ตี้ใหม่ exec_properties จะเป็น { "k1": "v1", "k2": "v2", "k3": "v3" }

อาร์กิวเมนต์

Attributes
name	Name; required ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
constraint_values	List of labels; optional ชุดค่าผสมของตัวเลือกข้อจำกัดที่มีอยู่ในแพลตฟอร์มนี้ หากต้องการให้แพลตฟอร์มนำไปใช้กับสภาพแวดล้อมที่กำหนด สภาพแวดล้อมดังกล่าวต้องมีค่าอย่างน้อย 1 ค่าในรายการนี้ constraint_value แต่ละรายการในรายการนี้ต้องเป็น URL สำหรับ constraint_setting ที่แตกต่างกัน ตัวอย่างเช่น คุณไม่สามารถกำหนดแพลตฟอร์มที่ต้องใช้สถาปัตยกรรม CPU เป็นทั้ง @platforms//cpu:x86_64 และ @platforms//cpu:arm
exec_properties	Dictionary: String -> String; optional แผนที่สตริงที่มีผลต่อวิธีการเรียกใช้การดำเนินการจากระยะไกล Bazel ไม่ได้พยายามตีความกรณีนี้ โดยจะถือว่าเป็นข้อมูลทึบแสงที่ส่งต่อผ่านช่องแพลตฟอร์มของโปรโตคอลการดำเนินการระยะไกล ซึ่งรวมถึงข้อมูลจากแอตทริบิวต์ exec_properties ของแพลตฟอร์มหลัก หากแพลตฟอร์มย่อยและแพลตฟอร์มหลักกำหนดคีย์เดียวกัน ระบบจะเก็บค่าของบุตรหลานไว้ ระบบจะนำคีย์ที่เชื่อมโยงกับค่าที่เป็นสตริงว่างออกจากพจนานุกรม แอตทริบิวต์นี้จะแทนที่ remote_execution_properties ที่เลิกใช้งานแล้วอย่างสมบูรณ์
parents	List of labels; optional ป้ายกำกับของเป้าหมาย platform ที่แพลตฟอร์มนี้ควรรับค่ามา แม้ว่าแอตทริบิวต์จะมีรายการ แต่ไม่ควรมีแพลตฟอร์มมากกว่า 1 รายการ การตั้งค่า restricted_settings ที่ไม่ได้ตั้งค่าโดยตรงบนแพลตฟอร์มนี้จะอยู่ในแพลตฟอร์มหลัก โปรดดูรายละเอียดในส่วนการรับช่วงแพลตฟอร์ม
remote_execution_properties	String; optional เลิกใช้งานแล้ว โปรดใช้แอตทริบิวต์ exec_properties แทน สตริงที่ใช้กำหนดค่าแพลตฟอร์มการดำเนินการระยะไกล บิลด์จริงจะไม่พยายามตีความข้อมูลนี้ โดยระบบจะถือว่าเป็นข้อมูลทึบแสงที่ SpawnRunner ที่เจาะจงจะใช้ได้ ซึ่งอาจรวมถึงข้อมูลจากแอตทริบิวต์ "remote_execution_properties" ของแพลตฟอร์มหลักโดยใช้มาโคร "{PARENT_REMOTE_EXECUTION_PROPERTIES}" ดูรายละเอียดได้จากส่วนการรับช่วงแพลตฟอร์ม

Toolchain

toolchain(name, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

กฎนี้จะประกาศประเภทและข้อจำกัดของ Toolchain ที่เจาะจงเพื่อให้คุณเลือกระหว่างความละเอียดของ Toolchain ได้ ดูรายละเอียดเพิ่มเติมในหน้า Toolchains

อาร์กิวเมนต์

Attributes
name	Name; required ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
exec_compatible_with	List of labels; optional; nonconfigurable รายการ constraint_value ที่แพลตฟอร์มการดำเนินการต้องตอบสนอง ระบบจึงจะเลือก Toolchain นี้สำหรับอาคารเป้าหมายบนแพลตฟอร์มนั้น
target_compatible_with	List of labels; optional; nonconfigurable รายการ constraint_value ที่แพลตฟอร์มเป้าหมายต้องพอใจ ระบบจึงจะเลือกชุดเครื่องมือนี้สำหรับอาคารเป้าหมายสำหรับแพลตฟอร์มนั้น
target_settings	List of labels; optional รายการ config_setting ที่การกำหนดค่าเป้าหมายต้องทำเพื่อให้เลือกห่วงโซ่เครื่องมือนี้ในระหว่างการแก้ปัญหา Toolchain ได้
toolchain	Name; required เป้าหมายที่แสดงถึงเครื่องมือจริงหรือชุดเครื่องมือที่พร้อมให้ใช้งานเมื่อเลือกชุดเครื่องมือนี้
toolchain_type	Label; required; nonconfigurable ป้ายกำกับของเป้าหมาย toolchain_type ที่แสดงถึงบทบาทที่เชนเครื่องมือนี้แสดง

toolchain_type

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

กฎนี้กำหนด Toolchain ประเภทใหม่ ซึ่งเป็นเป้าหมายอย่างง่ายที่แสดงถึงคลาสของเครื่องมือที่มีบทบาทเดียวกันสำหรับแพลตฟอร์มต่างๆ

ดูรายละเอียดเพิ่มเติมในหน้า Toolchains

ตัวอย่าง

ซึ่งจะกำหนดประเภทเชนเครื่องมือสำหรับกฎที่กำหนดเอง

toolchain_type(
    name = "bar_toolchain_type",
)

สามารถใช้ในไฟล์ bzl ได้

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

อาร์กิวเมนต์

Attributes
name	Name; required ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้