Aturan Platform dan Toolchain

Kumpulan aturan ini ada untuk memungkinkan Anda membuat model platform hardware tertentu yang di-build 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 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 memperkenalkan 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 yang mewakili arsitektur CPU.

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

Argumen

platform

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

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

Contoh

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

Flag Platform

Platform dapat menggunakan atribut flags untuk menentukan daftar flag yang akan ditambahkan ke konfigurasi setiap kali platform digunakan sebagai platform target (yaitu, sebagai nilai flag --platforms).

Flag yang ditetapkan dari platform secara efektif memiliki prioritas tertinggi dan menimpa nilai sebelumnya untuk flag tersebut, dari command line, file rc, atau transisi.

Contoh

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

Tindakan ini menentukan platform bernama foo. Jika ini adalah platform target (baik karena pengguna menentukan --platforms//:foo, karena transisi menetapkan flag //command_line_option:platforms ke ["//:foo"], atau karena //:foo digunakan sebagai platform eksekusi), flag yang diberikan akan ditetapkan dalam konfigurasi.

Platform dan Flag yang Dapat Diulang

Beberapa flag akan mengakumulasi nilai saat diulang, seperti --features, --copt, flag Starlark apa pun yang dibuat sebagai config.string(repeatable = True). Flag ini tidak kompatibel dengan menetapkan flag dari platform: sebagai gantinya, semua nilai sebelumnya akan dihapus dan ditimpa dengan nilai dari platform.

Sebagai contoh, dengan platform berikut, pemanggilan build --platforms=//:repeat_demo --features feature_a --features feature_b akan berakhir dengan nilai flag --feature menjadi ["feature_c", "feature_d"], yang menghapus fitur yang ditetapkan di command line.

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

Oleh karena itu, sebaiknya jangan gunakan flag yang dapat diulang dalam atribut flags.

Pewarisan Platform

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

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

Platform mewarisi atribut exec_properties dari platform induk. Entri kamus di exec_properties dari 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 tidak akan ditetapkan.

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 jika ada platform induk:

1. Jika remote_execution_property tidak ditetapkan di platform turunan, remote_execution_properties induk 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 secara bertahap, penggabungan remote_execution_properties dan exec_properties dalam rantai pewarisan yang sama tidak diizinkan. Lebih memilih 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 nilainya 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

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