Aturan Platform dan Toolchain

Kumpulan aturan ini ada untuk memungkinkan Anda memodelkan platform hardware tertentu yang Anda buat dan menentukan alat tertentu yang mungkin Anda perlukan untuk mengompilasi kode untuk 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 dapat menentukan nilai platform. Misalnya, Anda dapat menentukan constraint_setting bernama "glibc_version" untuk mewakili kemampuan platform agar memiliki versi library glibc yang berbeda yang diinstal. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Setiap constraint_setting memiliki kumpulan constraint_value terkait yang dapat diperluas. Biasanya, batasan ini ditentukan dalam paket yang sama, tetapi terkadang paket yang berbeda akan memperkenalkan nilai baru untuk setelan yang ada. Misalnya, setelan yang telah ditentukan sebelumnya @platforms//cpu:cpu 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 nilai baru yang mungkin 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 -- kumpulan pilihan batasan bernama (seperti arsitektur CPU atau versi pengompilasi) yang menjelaskan lingkungan tempat bagian build dapat berjalan. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Contoh

Hal ini menentukan 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 hanya satu nilai yang didukung, dan menentukan beberapa induk adalah error.

Saat memeriksa nilai setelan batasan di platform, nilai yang ditetapkan secara langsung (melalui atribut constraint_values) akan diperiksa terlebih dahulu, lalu nilai batasan pada induk. Hal ini terus berlanjut secara rekursif ke rantai platform induk. Dengan cara ini, nilai apa pun yang ditetapkan langsung di platform akan menggantikan nilai yang ditetapkan pada induk.

Platform mewarisi atribut exec_properties dari platform induk. Entri kamus di 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 menentukan string kosong sebagai nilai, properti yang sesuai akan tidak ditetapkan.

Platform juga dapat mewarisi atribut (tidak digunakan lagi) remote_execution_properties 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 jika ada platform induk:

1. Jika remote_execution_property tidak ditetapkan di platform turunan, indukremote_execution_properties akan digunakan.
2. Jika remote_execution_property ditetapkan di 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, penggabungan remote_execution_properties dan exec_properties dalam rantai pewarisan yang sama tidak diizinkan. Sebaiknya gunakan exec_properties daripada yang tidak digunakan lagi remote_execution_properties.

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 batasan 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 menetapkan properti 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 membatalkan setelan 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 mengetahui 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 melayani peran yang sama untuk platform yang berbeda.

Lihat halaman Toolchain untuk mengetahui detail selengkapnya.

Contoh

Hal ini menentukan jenis toolchain untuk aturan kustom.

toolchain_type(
    name = "bar_toolchain_type",
)

Hal 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