Aturan Platform dan Toolchain

Laporkan masalahopen_in_new Lihat sumberopen_in_new

Kumpulan aturan ini memungkinkan Anda membuat model platform hardware tertentu yang Anda buat 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

Lihat sumber aturanopen_in_new

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

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

Setiap constraint_setting memiliki kumpulan ekstensi 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 yang telah ditetapkan sebelumnya @platforms//cpu:cpu dapat diperluas dengan nilai kustom untuk menentukan platform yang menargetkan arsitektur cpu yang tidak jelas.

Argumen

Atribut
name	Name; required Nama unik untuk target ini.
default_constraint_value	Name; optional; nonconfigurable Label nilai default untuk setelan ini, yang akan digunakan jika tidak ada nilai yang diberikan. Jika atribut ini ada, constraint_value yang ditunjuknya harus ditentukan dalam paket yang sama dengan constraint_setting ini. Jika setelan batasan memiliki nilai default, maka setiap kali platform tidak menyertakan nilai batasan untuk setelan tersebut, setelan ini sama seperti jika platform telah menetapkan nilai default. Sebaliknya, jika tidak ada nilai default, setelan batasan dianggap tidak ditentukan oleh platform tersebut. Dalam hal ini, platform tidak akan cocok dengan daftar batasan apa pun (seperti untuk config_setting) yang memerlukan nilai tertentu untuk setelan tersebut.

constraint_value

Lihat sumber aturanopen_in_new

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

Aturan ini memperkenalkan nilai baru untuk jenis batasan tertentu. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Contoh

Berikut adalah kemungkinan nilai baru untuk constraint_value yang telah ditentukan dan mewakili arsitektur cpu.

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

Platform kemudian dapat mendeklarasikan bahwa mereka memiliki arsitektur mips sebagai alternatif untuk x86_64, arm, dan seterusnya.

Argumen

Atribut
name	Name; required Nama unik untuk target ini.
constraint_setting	Label; required; nonconfigurable constraint_setting yang memungkinkan constraint_value untuk pilihan.

platform

Lihat sumber aturanopen_in_new

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 yang diberi nama (seperti arsitektur cpu atau versi compiler) yang menjelaskan lingkungan tempat bagian build dapat berjalan. 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, tidak lebih dari satu nilai yang saat ini didukung, dan menentukan beberapa induk adalah error.

Saat memeriksa nilai setelan batasan di platform, pertama-tama nilai yang ditetapkan secara langsung (melalui atribut constraint_values) diperiksa, lalu nilai batasan pada induk. Hal ini 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 dibatalkan penetapannya.

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

1. Jika remote_execution_property tidak ditetapkan pada 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 tidak akan digunakan.

Karena remote_execution_properties tidak digunakan lagi dan akan dihentikan, pencampuran remote_execution_properties dan exec_properties dalam rantai pewarisan yang sama tidak diizinkan. Memilih untuk 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 pada 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" dari induk dan tidak menetapkan sendiri.
• child_b mewarisi exec_properties induk dan mengganti nilai k1. exec_properties-nya adalah: { "k1": "child", "k2": "v2" }.
• child_c mewarisi exec_properties induk dan membatalkan penetapan k1. exec_properties-nya adalah: { "k2": "v2" }.
• child_d mewarisi exec_properties induk dan menambahkan properti baru. exec_properties-nya adalah: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumen

Atribut
name	Name; required Nama unik untuk target ini.
constraint_values	List of labels; optional; nonconfigurable Kombinasi pilihan batasan yang terdiri dari platform ini. Agar platform dapat diterapkan ke lingkungan tertentu, lingkungan harus memiliki setidaknya nilai dalam daftar ini. Setiap constraint_value dalam daftar ini harus untuk constraint_setting yang berbeda. Misalnya, Anda tidak dapat menentukan platform yang mengharuskan arsitektur cpu menjadi @platforms//cpu:x86_64 dan @platforms//cpu:arm.
exec_properties	Dictionary: String -> String; optional Peta string yang memengaruhi cara tindakan dieksekusi dari jarak jauh. Bazel tidak berupaya untuk menafsirkan hal ini. Bazel diperlakukan sebagai data buram yang diteruskan melalui kolom Platform pada protokol eksekusi jarak jauh. Ini mencakup semua data dari atribut exec_properties platform induk. Jika platform turunan dan induk menentukan kunci yang sama, nilai turunan akan dipertahankan. Kunci apa pun yang terkait dengan nilai berupa string kosong akan dihapus dari kamus. Atribut ini adalah pengganti penuh untuk remote_execution_properties yang tidak digunakan lagi.
parents	List of labels; optional; nonconfigurable Label target platform yang harus diwariskan oleh platform ini. Meskipun atribut mengambil daftar, tidak boleh ada lebih dari satu platform. Setiap constraint_settings yang tidak disetel langsung di platform ini akan ditemukan di platform induk. Lihat bagian tentang Pewarisan Platform untuk mengetahui detailnya.
remote_execution_properties	String; optional TIDAK DIGUNAKAN LAGI. Sebagai gantinya, gunakan atribut exec_properties. String yang digunakan untuk mengonfigurasi platform eksekusi jarak jauh. Build sebenarnya tidak berupaya untuk menafsirkannya, tetapi akan diperlakukan sebagai data buram yang dapat digunakan oleh SpawnRunner tertentu. Ini dapat mencakup data dari atribut "remote_Execution_properties" platform induk, dengan menggunakan makro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Lihat bagian tentang Pewarisan Platform untuk detailnya.

toolchain

Lihat sumber aturanopen_in_new

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. Baca halaman Toolchain untuk mengetahui informasi lebih lanjut.

Argumen

Atribut
name	Name; required Nama unik untuk target ini.
exec_compatible_with	List of labels; optional; nonconfigurable Daftar constraint_value yang harus dipenuhi oleh platform eksekusi agar toolchain ini dapat dipilih untuk bangunan target di platform tersebut.
target_compatible_with	List of labels; optional; nonconfigurable Daftar constraint_value yang harus dipenuhi oleh platform target agar toolchain ini dipilih untuk gedung target bagi platform tersebut.
target_settings	List of labels; optional Daftar config_setting yang harus dipenuhi oleh konfigurasi target agar toolchain ini dipilih selama resolusi toolchain.
toolchain	Name; required Target yang merepresentasikan alat atau rangkaian alat sebenarnya yang tersedia saat toolchain ini dipilih.
toolchain_type	Label; required; nonconfigurable Label target toolchain_type yang mewakili peran yang dilayani toolchain ini.

toolchain_type

Lihat sumber aturanopen_in_new

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 sebuah class alat yang memiliki 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

Atribut
name	Name; required Nama unik untuk target ini.