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

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

กฎ

• 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	ชื่อ; กำหนดค่าไม่ได้; ค่าเริ่มต้นคือ None ป้ายกํากับของค่าเริ่มต้นสําหรับการตั้งค่านี้ ซึ่งจะใช้ในกรณีที่ไม่ได้ระบุค่า หากมีแอตทริบิวต์นี้ constraint_value ที่ชี้ไปต้องได้รับการกำหนดไว้ในแพ็กเกจเดียวกับ constraint_setting นี้ หากการตั้งค่าข้อจำกัดมีค่าเริ่มต้น เมื่อใดก็ตามที่แพลตฟอร์มไม่ได้ระบุค่าข้อจำกัดสำหรับการตั้งค่านั้น การตั้งค่านั้นจะเหมือนกับว่าแพลตฟอร์มได้ระบุค่าเริ่มต้นไว้ หรือหากไม่มีค่าเริ่มต้น ระบบจะถือว่าแพลตฟอร์มนั้นไม่ได้ระบุการตั้งค่าข้อจำกัด ในกรณีนี้ แพลตฟอร์มจะไม่จับคู่กับรายการข้อจำกัดใดๆ (เช่น สำหรับ config_setting) ที่กำหนดค่าที่เจาะจงสำหรับการตั้งค่านั้น

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

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

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

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

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 เพื่อระบุรายการ Flag ที่ระบบจะเพิ่มลงในการกำหนดค่าทุกครั้งที่มีการใช้แพลตฟอร์มเป็นแพลตฟอร์มเป้าหมาย (เช่น เป็นค่าของ Flag --platforms)

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

ตัวอย่าง

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

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

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

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

ตัวอย่างเช่น เมื่อใช้แพลตฟอร์มต่อไปนี้ การเรียกใช้ 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",
    ],
)

ด้วยเหตุนี้ เราจึงไม่แนะนำให้ใช้ Flag ที่ซ้ำกันในแอตทริบิวต์ 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" }

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

Attributes
name	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสําหรับเป้าหมายนี้
constraint_values	รายการป้ายกํากับ ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ [] ชุดค่าผสมของตัวเลือกข้อจำกัดที่แพลตฟอร์มนี้ประกอบด้วย สภาพแวดล้อมต้องมีค่าในรายการนี้เป็นอย่างน้อยเพื่อให้แพลตฟอร์มใช้งานได้ constraint_value แต่ละรายการในรายการนี้ต้องเป็นconstraint_setting ที่แตกต่างกัน ตัวอย่างเช่น คุณไม่สามารถกำหนดแพลตฟอร์มที่กำหนดให้สถาปัตยกรรม CPU ต้องเป็นทั้ง @platforms//cpu:x86_64 และ @platforms//cpu:arm
exec_properties	พจนานุกรม: สตริง -> สตริง nonconfigurable ค่าเริ่มต้นคือ {} แผนที่สตริงที่ส่งผลต่อวิธีดำเนินการจากระยะไกล Bazel จะไม่พยายามตีความค่านี้ โดยระบบจะถือว่าค่านี้เป็นข้อมูลที่มองไม่เห็นซึ่งส่งต่อผ่านช่อง Platform ของโปรโตคอลการเรียกใช้จากระยะไกล ซึ่งรวมถึงข้อมูลจากแอตทริบิวต์ exec_properties ของแพลตฟอร์มหลัก หากแพลตฟอร์มย่อยและแพลตฟอร์มหลักกำหนดคีย์เดียวกัน ระบบจะเก็บค่าของแพลตฟอร์มย่อยไว้ ระบบจะนำคีย์ที่เชื่อมโยงกับค่าที่เป็นสตริงว่างออกจากพจนานุกรม แอตทริบิวต์นี้มาแทนที่remote_execution_propertiesที่เลิกใช้งานอย่างสมบูรณ์
flags	รายการสตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ [] รายการ Flag ที่เปิดใช้เมื่อใช้แพลตฟอร์มนี้เป็นแพลตฟอร์มเป้าหมายในการกําหนดค่า อนุญาตให้ใช้เฉพาะ Flag ที่ตั้งค่าได้ในทรานซิชัน
parents	รายการป้ายกํากับ ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ [] ป้ายกํากับของเป้าหมาย platform ที่แพลตฟอร์มนี้ควรรับค่ามา แม้ว่าแอตทริบิวต์จะใช้ลิสต์ แต่ควรมีแพลตฟอร์มไม่เกิน 1 รายการ คุณจะดู constraint_settings ที่ไม่ได้ตั้งค่าในแพลตฟอร์มนี้โดยตรงได้ในแพลตฟอร์มหลัก ดูรายละเอียดได้ที่ส่วนการสืบทอดแพลตฟอร์ม
remote_execution_properties	สตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ "" เลิกใช้งานแล้ว โปรดใช้แอตทริบิวต์ exec_properties แทน สตริงที่ใช้กำหนดค่าแพลตฟอร์มการเรียกใช้ระยะไกล บิลด์จริงจะไม่พยายามตีความข้อมูลนี้ แต่จะถือว่าข้อมูลนี้เป็นข้อมูลที่มองไม่เห็นซึ่ง SpawnRunner ที่เฉพาะเจาะจงสามารถใช้ได้ ซึ่งอาจรวมถึงข้อมูลจากแอตทริบิวต์ "remote_execution_properties" ของแพลตฟอร์มหลัก โดยใช้มาโคร "{PARENT_REMOTE_EXECUTION_PROPERTIES}" ดูรายละเอียดได้ที่ส่วนการสืบทอดแพลตฟอร์ม
required_settings	รายการป้ายกํากับ ค่าเริ่มต้นคือ [] รายการ config_setting ที่กำหนดค่าเป้าหมายต้องเป็นไปตามข้อกำหนดเพื่อให้ใช้แพลตฟอร์มนี้เป็นแพลตฟอร์มการดำเนินการระหว่างการแก้ไขเครื่องมือได้ การตั้งค่าที่จําเป็นจะไม่รับค่ามาจากแพลตฟอร์มหลัก

Toolchain

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

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

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

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

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

toolchain_type

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

toolchain_type(name, compatible_with, deprecation, features, 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"]
)

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

Attributes
name	ชื่อ ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้