Aturan Platform dan Toolchain

Laporkan masalah Lihat sumber Malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

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

Lihat sumber aturan 
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

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
default_constraint_value

Nama; tidak dapat dikonfigurasi; defaultnya adalah None

Label nilai default untuk setelan ini, yang akan digunakan jika tidak ada nilai yang diberikan. Jika ini ada, constraint_value yang ditunjuk harus ditentukan dalam paket yang sama dengan constraint_setting ini.

Jika setelan batasan memiliki nilai default, setiap kali platform tidak menyertakan nilai batasan untuk setelan itu, maka akan sama seolah-olah platform telah menentukan untuk nilai default. Sebaliknya, jika tidak ada nilai default, setelan batasan akan dipertimbangkan tidak ditentukan oleh platform tersebut. Dalam hal ini, platform tidak akan cocok dengan daftar batasan (seperti untuk config_setting) yang memerlukan nilai tertentu setelan tersebut.

constraint_value

Lihat sumber aturan 
constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)
 Aturan ini memasukkan nilai baru untuk jenis batasan tertentu. Untuk mengetahui detail selengkapnya, lihat Halaman Platform.

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",
)
Platform kemudian dapat mendeklarasikan bahwa memiliki arsitektur mips sebagai alternatif x86_64, arm, dan seterusnya.

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
constraint_setting

Label; tidak dapat dikonfigurasi; wajib diisi

constraint_setting yang constraint_value-nya adalah pilihan yang memungkinkan.

platform

Lihat sumber aturan 
platform(name, constraint_values, deprecation, distribs, exec_properties, features, licenses, parents, remote_execution_properties, 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",
    ],
)

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

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
constraint_values

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Kombinasi pilihan batasan yang ada pada platform ini. Agar platform agar diterapkan ke lingkungan tertentu, lingkungan harus memiliki setidaknya nilai yang ada dalam daftar ini.

Setiap constraint_value dalam daftar ini harus untuk constraint_setting. Misalnya, Anda tidak dapat menentukan platform yang memerlukan arsitektur cpu menjadi @platforms//cpu:x86_64 dan @platforms//cpu:arm.

exec_properties

Kamus: String -> String; tidak dapat dikonfigurasi; default adalah {}

Peta string yang memengaruhi cara tindakan dijalankan dari jarak jauh. Bazel tidak berusaha untuk menafsirkannya, ini diperlakukan sebagai data buram yang diteruskan melalui bidang Platform di 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. Apa saja kunci yang terkait dengan nilai berupa string kosong akan dihapus dari kamus. Atribut ini adalah pengganti penuh untuk atribut yang tidak digunakan lagi remote_execution_properties.
parents

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Label target platform yang harus diwarisi oleh platform ini. Meskipun atribut mengambil daftar, tidak boleh ada lebih dari satu platform. Apa saja constraint_settings yang tidak disetel langsung di platform ini akan ditemukan di platform induk. Lihat bagian Pewarisan Platform untuk mengetahui detailnya.
remote_execution_properties

String; tidak dapat dikonfigurasi; default adalah ""

TIDAK DIGUNAKAN LAGI. Sebagai gantinya, gunakan atribut exec_properties. String yang digunakan untuk mengonfigurasi platform eksekusi jarak jauh. Build yang sebenarnya tidak akan mencoba menafsirkannya, maka akan diperlakukan sebagai data buram yang dapat digunakan oleh SpawnRunner tertentu. Ini dapat mencakup data dari "remote_execution_properties" platform induk , dengan menggunakan makro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Lihat bagian tentang Pewarisan Platform untuk mengetahui detailnya.

toolchain

Lihat sumber aturan 
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

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
exec_compatible_with

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Daftar constraint_value yang harus dipenuhi oleh platform eksekusi di agar toolchain ini dipilih untuk sebuah build target pada platform tersebut.
target_compatible_with

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Daftar constraint_value yang harus dipenuhi oleh platform target di agar toolchain ini dipilih untuk sebuah build target untuk platform tersebut.
target_settings

Daftar label; default adalah []

Daftar config_setting yang harus dipenuhi oleh konfigurasi target agar toolchain ini dapat dipilih selama resolusi toolchain.
toolchain

Nama; wajib diisi

Target yang merepresentasikan rangkaian alat atau rangkaian alat sebenarnya yang tersedia saat toolchain dipilih.
toolchain_type

Label; tidak dapat dikonfigurasi; wajib diisi

Label target toolchain_type yang mewakili peran yang disadari oleh toolchain.

toolchain_type

Lihat sumber aturan 
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

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.