Aturan Platform dan Toolchain

Ada seperangkat aturan untuk memungkinkan Anda membuat model platform hardware tertentu yang Anda bangun dan menentukan alat spesifik yang mungkin diperlukan untuk mengompilasi kode bagi platform tersebut. Pengguna harus memahami konsep yang dijelaskan di sini.

Aturan

• constraint_setting
• constraint_value
• platform
• Toolchain
• toolchain_type

constraint_setting

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

Aturan ini digunakan untuk memperkenalkan jenis batasan baru yang nilainya dapat ditentukan oleh platform. Misalnya, Anda dapat menentukan constraint_setting bernama "glibc_version" untuk mewakili kemampuan platform agar dapat menginstal versi library glibc yang berbeda. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Setiap constraint_setting memiliki kumpulan constraint_value terkait yang dapat diperluas. Biasanya ini ditentukan dalam paket yang sama, tetapi terkadang paket yang berbeda akan memasukkan nilai baru untuk setelan yang ada. Misalnya, setelan @platforms//cpu:cpu yang telah ditentukan sebelumnya dapat diperluas dengan nilai kustom untuk menentukan platform yang menargetkan arsitektur CPU yang tidak jelas.

Argumen

constraint_value

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

Contoh

Berikut ini membuat kemungkinan nilai baru untuk constraint_value yang telah ditentukan sebelumnya yang mewakili arsitektur CPU.

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

Argumen

platform

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

Aturan ini menentukan platform baru, yaitu kumpulan pilihan batasan bernama (seperti arsitektur CPU atau versi compiler) yang menjelaskan lingkungan tempat bagian build dapat dijalankan. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Contoh

Ini mendefinisikan platform yang menjelaskan lingkungan apa pun yang menjalankan Linux di ARM.

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

Pewarisan Platform

Platform dapat menggunakan atribut parents untuk menentukan platform lain yang akan mewarisi nilai batasan. Meskipun atribut parents mengambil daftar, saat ini tidak lebih dari satu nilai yang didukung, dan menetapkan beberapa induk merupakan error.

Saat memeriksa nilai setelan batasan di platform, pertama-tama nilai yang ditetapkan secara langsung (melalui atribut constraint_values) akan diperiksa, lalu nilai batasan pada induk. Hal ini terus berlanjut secara berulang ke rantai platform induk. Dengan cara ini, setiap nilai yang ditetapkan langsung pada platform akan menggantikan nilai yang ditetapkan pada induknya.

Platform mewarisi atribut exec_properties dari platform induk. Entri kamus dalam exec_properties platform induk dan turunan akan digabungkan. Jika kunci yang sama muncul di exec_properties induk dan turunan, nilai turunan akan digunakan. Jika platform turunan menetapkan string kosong sebagai nilai, properti terkait akan dibatalkan penetapannya.

Platform juga dapat mewarisi atribut remote_execution_properties (tidak digunakan lagi) dari platform induk. Catatan: kode baru harus menggunakan exec_properties. Logika yang dijelaskan di bawah dipertahankan agar kompatibel dengan perilaku lama, tetapi akan dihapus pada masa mendatang. Logika untuk menetapkan remote_execution_platform adalah sebagai berikut saat ada platform induk:

1. Jika remote_execution_property tidak ditetapkan di platform turunan, remote_execution_properties induk akan digunakan.
2. Jika remote_execution_property disetel pada platform turunan, dan berisi string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, makro tersebut akan diganti dengan konten atribut remote_execution_property induk.
3. Jika remote_execution_property ditetapkan di platform turunan, dan tidak berisi makro, remote_execution_property turunan akan digunakan tanpa perubahan.

Karena remote_execution_properties tidak digunakan lagi dan akan dihentikan, pencampuran remote_execution_properties dan exec_properties dalam rantai pewarisan yang sama tidak diizinkan. Lebih suka menggunakan exec_properties daripada remote_execution_properties yang tidak digunakan lagi.

Contoh: Nilai Batasan

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

Dalam contoh ini, platform turunan memiliki properti berikut:

• child_a memiliki nilai batasan @platforms//os:linux (diwarisi dari induk) dan @platforms//cpu:x86_64 (ditetapkan langsung di platform).
• child_b mewarisi semua nilai batasan dari induk, dan tidak menetapkan nilai sendiri.

Contoh: Properti eksekusi

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

Dalam contoh ini, platform turunan memiliki properti berikut:

• child_a mewarisi "exec_properties" induk dan tidak menetapkannya sendiri.
• child_b mewarisi exec_properties induk dan mengganti nilai k1. exec_properties-nya akan menjadi: { "k1": "child", "k2": "v2" }.
• child_c mewarisi exec_properties induk dan menghapus k1. exec_properties-nya akan menjadi: { "k2": "v2" }.
• child_d mewarisi exec_properties induk dan menambahkan properti baru. exec_properties-nya akan menjadi: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumen

toolchain

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

Aturan ini mendeklarasikan jenis dan batasan toolchain tertentu sehingga dapat dipilih selama resolusi toolchain. Lihat halaman Toolchain untuk detail selengkapnya.

Argumen

toolchain_type

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

Aturan ini menentukan jenis toolchain baru -- target sederhana yang mewakili class alat yang menjalankan peran yang sama untuk platform yang berbeda.

Lihat halaman Toolchain untuk mengetahui detail selengkapnya.

Contoh

Kode ini menentukan jenis toolchain untuk aturan kustom.

toolchain_type(
    name = "bar_toolchain_type",
)

Ini dapat digunakan dalam file 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"]
)

Argumen