Aturan Platform dan Toolchain

Ada seperangkat aturan yang memungkinkan Anda membuat model platform hardware tertentu membangun dan menentukan alat spesifik yang mungkin Anda perlukan untuk mengompilasi kode bagi platform tersebut. Pengguna harus sudah 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 bagi platform untuk menginstal versi library glibc yang berbeda. Untuk mengetahui detail selengkapnya, lihat Halaman Platform.

Setiap constraint_setting memiliki kumpulan elemen terkait yang dapat diperluas constraint_value dtk. Biasanya ini didefinisikan dalam paket yang sama, tetapi kadang-kadang paket yang berbeda akan memperkenalkan nilai baru untuk pengaturan yang ada. Misalnya, standar setelan @platforms//cpu:cpu dapat diperpanjang dengan nilai kustom untuk mendefinisikan 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 merepresentasikan 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 menetapkan platform baru -- kumpulan pilihan batasan bernama (seperti arsitektur cpu atau versi compiler) yang menjelaskan lingkungan di bagian build mana yang 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",
    ],
)

Tanda Platform

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

Tanda yang ditetapkan dari platform secara efektif memiliki prioritas tertinggi dan menimpa tanda sebelumnya untuk penanda itu, dari baris perintah, file rc, atau transisi.

Contoh

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

Ini menentukan platform bernama foo. Ketika ini adalah platform target (baik karena pengguna menentukan --platforms//:foo, karena transisi menyetel //command_line_option:platforms ke ["//:foo"], atau karena //:foo digunakan sebagai platform eksekusi), maka flag yang diberikan akan ditetapkan di konfigurasi Anda.

Platform dan Bendera Berulang

Beberapa tanda akan mengumpulkan nilai saat diulang, seperti --features, --copt, setiap tanda Starlark yang dibuat sebagai config.string(repeatable = True). Tanda ini tidak kompatibel dengan penyetelan tanda dari platform: sebagai gantinya, semua tanda nilai-nilai itu akan dihapus dan ditimpa dengan nilai-nilai dari platform.

Sebagai contoh, dengan platform berikut, pemanggilan build --platforms=//:repeat_demo --features feature_a --features feature_b akan menghasilkan nilai Flag --feature menjadi ["feature_c", "feature_d"], yang akan menghapus fitur yang diatur pada baris perintah.

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

Karena alasan ini, tidak disarankan untuk menggunakan tanda 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 mengambil daftar, tidak lebih dari satu nilai saat ini didukung, dan menetapkan beberapa induk merupakan error.

Saat memeriksa nilai setelan batasan di platform, pertama-tama nilai ditetapkan secara langsung (melalui atribut constraint_values) diperiksa, lalu nilai batasan di orang tua. Hal ini terus berlanjut ke rantai platform induk secara rekursif. 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 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 menetapkan string kosong sebagai nilai, properti yang sesuai akan dibatalkan penetapannya.

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

1. Jika remote_execution_property tidak disetel di platform turunan, konfigurasi remote_execution_properties akan digunakan.
2. Jika remote_execution_property disetel di platform turunan, dan berisi string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, makro tersebut akan menjadi diganti dengan konten atribut remote_execution_property induk.
3. Jika remote_execution_property disetel 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, mencampur remote_execution_properties dan exec_properties dalam waktu yang sama rantai pewarisan tidak diizinkan. Lebih memilih menggunakan 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 salah satu itu 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" milik induk dan tidak ditetapkan sendiri.
• child_b mewarisi exec_properties induk dan menggantikan senilai k1. exec_properties-nya adalah: { "k1": "child", "k2": "v2" }.
• child_c mewarisi exec_properties induk dan tidak disetel k1. exec_properties-nya adalah: { "k2": "v2" }.
• child_d mewarisi exec_properties induk dan menambahkan yang baru saat ini. exec_properties-nya adalah: { "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 Toolchains untuk mengetahui informasi selengkapnya spesifikasi pendukung.

Argumen

toolchain_type

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

Aturan ini menetapkan jenis toolchain baru -- target sederhana yang mewakili kelas alat yang memiliki peran yang sama untuk platform yang berbeda.

Lihat halaman Toolchain untuk 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