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

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

กฎ

• 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 ที่ไม่ชัดเจน

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

constraint_value

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

ตัวอย่าง

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

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

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

platform

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

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

ตัวอย่าง

ซึ่งกำหนดแพลตฟอร์มที่อธิบายสภาพแวดล้อมที่เรียกใช้ Linux บน ARM

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

ธงแพลตฟอร์ม

แพลตฟอร์มอาจใช้แอตทริบิวต์ flags เพื่อระบุรายการแฟล็กที่จะเพิ่ม ในการกำหนดค่าเมื่อใดก็ตามที่มีการใช้แพลตฟอร์มเป็นแพลตฟอร์มเป้าหมาย (เช่น เป็นค่าของ แฟล็ก --platforms)

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

ตัวอย่าง

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

ซึ่งจะกำหนดแพลตฟอร์มชื่อ foo เมื่อแพลตฟอร์มนี้เป็นแพลตฟอร์มเป้าหมาย (ไม่ว่าจะเป็นเพราะผู้ใช้ระบุ --platforms//:foo เพราะการเปลี่ยนผ่านตั้งค่าสถานะ //command_line_option:platforms เป็น ["//:foo"] หรือเพราะใช้ //:foo เป็นแพลตฟอร์มการดำเนินการ) ระบบจะตั้งค่าสถานะที่ระบุในการกำหนดค่า

แพลตฟอร์มและธงที่ทำซ้ำได้

ธงบางรายการจะสะสมค่าเมื่อมีการทำซ้ำ เช่น --features, --copt, ธง Starlark ใดๆ ที่สร้างเป็น config.string(repeatable = True) โดยค่าสถานะเหล่านี้จะใช้ร่วมกับการตั้งค่าสถานะจากแพลตฟอร์มไม่ได้ แต่ระบบจะนำค่าก่อนหน้าทั้งหมดออกและเขียนทับด้วยค่าจากแพลตฟอร์มแทน

ตัวอย่างเช่น เมื่อพิจารณาแพลตฟอร์มต่อไปนี้ การเรียกใช้ build --platforms=//:repeat_demo --features feature_a --features feature_b จะมีค่าของ แฟล็ก --feature เป็น ["feature_c", "feature_d"] ซึ่งจะนำฟีเจอร์ที่ ตั้งค่าไว้ในบรรทัดคำสั่งออก

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

ด้วยเหตุนี้ เราจึงไม่แนะนำให้ใช้แฟล็กที่ทำซ้ำได้ในแอตทริบิวต์ flags

การรับค่าของแพลตฟอร์ม

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

เมื่อตรวจสอบค่าของการตั้งค่าข้อจํากัดในแพลตฟอร์ม ระบบจะตรวจสอบค่าที่ตั้งค่าโดยตรงก่อน (ผ่านแอตทริบิวต์ 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" }

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

Toolchain

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

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

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

toolchain_type

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

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

ดูรายละเอียดเพิ่มเติมได้ในหน้าชุดเครื่องมือ

ตัวอย่าง

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

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"]
)

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