กฎแพลตฟอร์มและเชนเครื่องมือ

รายงานปัญหา ดูแหล่งที่มา

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

กฎ

• constraint_setting
• constraint_value
• แพลตฟอร์ม
• Toolchain
• toolchain_type

constraint_setting

ดูแหล่งที่มาของกฎ

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

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

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

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

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

constraint_value

ดูแหล่งที่มาของกฎ

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

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

ตัวอย่าง

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

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

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

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

Attributes
name	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
constraint_setting	ป้ายกำกับ ไม่สามารถกำหนดค่าได้ ต้องระบุ constraint_setting ที่มี constraint_value นี้เป็นตัวเลือกที่เป็นไปได้

platform

ดูแหล่งที่มาของกฎ

platform(name, constraint_values, deprecation, distribs, 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	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
constraint_values	รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ [] ชุดค่าผสมของตัวเลือกข้อจำกัดที่มีอยู่ในแพลตฟอร์มนี้ สภาพแวดล้อมต้องมีค่าอย่างน้อย 1 ค่าในรายการนี้ เพื่อให้แพลตฟอร์มนำไปใช้กับสภาพแวดล้อมหนึ่งๆ ได้ constraint_value แต่ละรายการในรายการนี้ต้องเป็นสำหรับ constraint_setting ที่แตกต่างกัน เช่น คุณจะกำหนดแพลตฟอร์มที่ต้องใช้สถาปัตยกรรม CPU เป็นทั้ง @platforms//cpu:x86_64 และ @platforms//cpu:arm ไม่ได้
exec_properties	พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ {} แมปของสตริงที่มีผลต่อวิธีดำเนินการจากระยะไกล Bazel จะไม่พยายามตีความข้อมูลนี้ โดยจะถือว่าเป็นข้อมูลทึบแสงที่ส่งต่อผ่านช่องแพลตฟอร์มของโปรโตคอลการดำเนินการระยะไกล ซึ่งรวมถึงข้อมูลจากแอตทริบิวต์ exec_properties ของแพลตฟอร์มหลัก หากแพลตฟอร์มย่อยและแพลตฟอร์มหลักกำหนดคีย์เดียวกัน ค่าของรายการย่อยจะยังคงอยู่ ระบบจะนำคีย์ทั้งหมดที่เชื่อมโยงกับค่าที่เป็นสตริงว่างออกจากพจนานุกรม แอตทริบิวต์นี้ใช้แทน remote_execution_properties ที่เลิกใช้งานแล้วโดยสมบูรณ์
parents	รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ [] ป้ายกำกับของเป้าหมาย platform ที่แพลตฟอร์มนี้ควรรับค่ามา แม้ว่าแอตทริบิวต์จะใช้ลิสต์รายการ แต่ไม่ควรมีแพลตฟอร์มมากกว่า 1 แพลตฟอร์ม ส่วนข้อจำกัดด้านการตั้งค่าใดๆ ที่ไม่ได้ตั้งค่าในแพลตฟอร์มนี้โดยตรงจะอยู่ในแพลตฟอร์มหลัก ดูรายละเอียดได้ในส่วนการรับช่วงแพลตฟอร์ม
remote_execution_properties	สตริง nonconfigurable ค่าเริ่มต้นคือ "" เลิกใช้งานแล้ว โปรดใช้แอตทริบิวต์ exec_properties แทน สตริงที่ใช้เพื่อกำหนดค่าแพลตฟอร์มการดำเนินการระยะไกล บิลด์จริงจะไม่พยายามตีความข้อมูลนี้ จะถือว่าเป็นข้อมูลทึบแสงที่ SpawnRunner ที่เจาะจงนำไปใช้ได้ ซึ่งอาจรวมถึงข้อมูลจากแอตทริบิวต์ "remote_execution_properties" ของแพลตฟอร์มระดับบนสุดโดยใช้มาโคร "{PARENT_REMOTE_EXECUTION_PROPERTIES}" ดูรายละเอียดได้ในส่วนการรับช่วงแพลตฟอร์ม

Toolchain

ดูแหล่งที่มาของกฎ

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

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

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

Attributes
name	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้
exec_compatible_with	รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ [] รายการ constraint_value ที่แพลตฟอร์มการดำเนินการต้องมีคุณสมบัติตรงตาม เพื่อให้เลือก Toolchain นี้สำหรับอาคารเป้าหมายในแพลตฟอร์มนั้นได้
target_compatible_with	รายการป้ายกำกับ nonconfigurable ค่าเริ่มต้นคือ [] รายการ constraint_value ที่แพลตฟอร์มเป้าหมายต้องปฏิบัติตามเพื่อให้เลือก Toolchain นี้สำหรับอาคารเป้าหมายสำหรับแพลตฟอร์มนั้นได้
target_settings	รายการป้ายกำกับ ค่าเริ่มต้นคือ [] รายการ config_setting ที่ต้องเป็นไปตามการกำหนดค่าเป้าหมาย เพื่อให้ระบบเลือก Toolchain นี้ระหว่างการแปลง Toolchain
toolchain	ชื่อ ต้องระบุ เป้าหมายที่แสดงถึงเครื่องมือหรือชุดเครื่องมือจริงที่พร้อมใช้งานเมื่อเลือก Toolchain นี้
toolchain_type	ป้ายกำกับ ไม่สามารถกำหนดค่าได้ ต้องระบุ ป้ายกำกับของเป้าหมาย toolchain_type ที่แสดงถึงบทบาทที่เครื่องมือเชนนี้แสดง

toolchain_type

ดูแหล่งที่มาของกฎ

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

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

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

ตัวอย่าง

แอตทริบิวต์นี้กำหนดประเภท Toolchain สำหรับกฎที่กำหนดเอง

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	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้