Aturan Platform dan Toolchain

Laporkan masalah Lihat sumber Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Kumpulan aturan ini ada untuk memungkinkan Anda memodelkan platform hardware tertentu yang Anda bangun 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

Lihat sumber aturan

constraint_setting(name, aspect_hints, default_constraint_value, deprecation, 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 merepresentasikan kemampuan platform agar memiliki versi library glibc yang berbeda yang diinstal. Untuk mengetahui detail selengkapnya, lihat halaman Platform.

Setiap constraint_setting memiliki serangkaian constraint_value terkait yang dapat diperluas. Biasanya, setelan 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 penargetan platform yang menggunakan arsitektur CPU yang tidak umum.

Argumen

Atribut
name	Nama; wajib Nama unik untuk target ini.
default_constraint_value	Name; nonconfigurable; default adalah None Label nilai default untuk setelan ini, yang akan digunakan jika tidak ada nilai yang diberikan. Jika atribut ini ada, constraint_value yang ditujuknya 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 tersebut, hal ini sama seperti jika platform telah menentukan nilai default. Jika tidak, 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 aturan

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

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

Contoh

Berikut akan membuat nilai baru yang mungkin untuk constraint_value yang telah ditentukan sebelumnya yang merepresentasikan arsitektur CPU.

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

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

Argumen

Atribut
name	Nama; wajib Nama unik untuk target ini.
constraint_setting	Label; tidak dapat dikonfigurasi; wajib constraint_setting yang memungkinkan constraint_value ini menjadi pilihan.

platform

Lihat sumber aturan

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

Aturan ini menentukan platform baru -- kumpulan pilihan batasan bernama (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",
    ],
)

Bendera Platform

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

Flag yang ditetapkan dari platform secara efektif memiliki prioritas tertinggi dan menggantikan 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), maka flag yang diberikan akan ditetapkan dalam konfigurasi.

Platform dan Flag yang Dapat Diulang

Beberapa tanda akan mengakumulasi nilai saat diulang, seperti --features, --copt, tanda Starlark apa pun yang dibuat sebagai config.string(repeatable = True). Flag ini tidak kompatibel dengan menyetel flag dari platform: sebagai gantinya, semua nilai sebelumnya akan dihapus dan diganti dengan 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"], sehingga menghapus fitur yang ditetapkan di command line.

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

Oleh karena itu, sebaiknya jangan gunakan tanda berulang dalam atribut flags.

Pewarisan Platform

Platform dapat menggunakan atribut parents untuk menentukan platform lain yang akan mewarisi nilai batasan dari platform tersebut. 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, pertama-tama nilai yang ditetapkan secara langsung (melalui atribut constraint_values) diperiksa, lalu nilai batasan pada induk. Proses ini berlanjut secara rekursif ke atas rantai platform induk. Dengan cara ini, semua 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 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.

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 menyetel remote_execution_platform adalah sebagai berikut jika ada platform induk:

1. Jika remote_execution_property tidak disetel 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, penggabungan remote_execution_properties dan exec_properties dalam rantai pewarisan yang sama tidak diizinkan. Lebih baik 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 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 menyetelnya 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 setelan 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	Nama; wajib Nama unik untuk target ini.
constraint_values	Daftar label; tidak dapat dikonfigurasi; defaultnya adalah [] Kombinasi pilihan batasan yang membentuk platform ini. Agar platform dapat diterapkan ke lingkungan tertentu, lingkungan tersebut 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 memerlukan arsitektur CPU menjadi @platforms//cpu:x86_64 dan @platforms//cpu:arm.
exec_properties	Dictionary: String -> String; nonconfigurable; default adalah {} Peta string yang memengaruhi cara tindakan dijalankan dari jarak jauh. Bazel tidak berupaya menafsirkan hal ini, melainkan memperlakukannya sebagai data buram yang diteruskan melalui kolom Platform dari protokol eksekusi jarak jauh. Hal ini mencakup data apa pun dari atribut exec_properties platform induk. Jika platform turunan dan induk menentukan kunci yang sama, nilai turunan akan dipertahankan. Setiap kunci yang terkait dengan nilai berupa string kosong akan dihapus dari kamus. Atribut ini adalah pengganti lengkap untuk remote_execution_properties yang tidak digunakan lagi.
flags	Daftar string; tidak dapat dikonfigurasi; defaultnya adalah [] Daftar tanda yang akan diaktifkan saat platform ini digunakan sebagai platform target dalam konfigurasi. Hanya tanda yang merupakan bagian dari konfigurasi yang dapat ditetapkan, seperti tanda yang dapat digunakan dalam transisi, atau tanda --define.
missing_toolchain_error	String; tidak dapat dikonfigurasi; defaultnya adalah "For more information on platforms or toolchains see https://bazel.build/concepts/platforms-intro." Pesan error kustom yang ditampilkan saat persyaratan toolchain wajib tidak dapat dipenuhi untuk platform target ini. Dimaksudkan untuk mengarahkan ke dokumentasi relevan yang dapat dibaca pengguna untuk memahami alasan konfigurasi yang salah pada toolchain mereka. Tidak diwarisi dari platform induk.
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. Setelan batasan yang tidak ditetapkan langsung di platform ini akan ditemukan di platform induk. Lihat bagian Pewarisan Platform untuk mengetahui detailnya.
remote_execution_properties	String; tidak dapat dikonfigurasi; defaultnya adalah "" TIDAK DIGUNAKAN LAGI. Sebagai gantinya, gunakan atribut exec_properties. String yang digunakan untuk mengonfigurasi platform eksekusi jarak jauh. Build sebenarnya tidak mencoba menafsirkan hal ini, melainkan memperlakukannya sebagai data buram yang dapat digunakan oleh SpawnRunner tertentu. Hal ini dapat mencakup data dari atribut "remote_execution_properties" platform induk, dengan menggunakan makro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Lihat bagian tentang Pewarisan Platform untuk mengetahui detailnya.
required_settings	Daftar label; defaultnya adalah [] Daftar config_setting yang harus dipenuhi oleh konfigurasi target agar platform ini dapat digunakan sebagai platform eksekusi selama penyelesaian toolchain. Setelan yang diperlukan tidak diwarisi dari platform induk.

toolchain

Lihat sumber aturan

toolchain(name, aspect_hints, deprecation, exec_compatible_with, features, licenses, package_metadata, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, use_target_platform_constraints, visibility)

Aturan ini mendeklarasikan jenis dan batasan toolchain tertentu sehingga dapat dipilih selama penyelesaian toolchain. Lihat halaman Toolchains untuk mengetahui detail selengkapnya.

Argumen

Atribut
name	Nama; wajib Nama unik untuk target ini.
exec_compatible_with	Daftar label; tidak dapat dikonfigurasi; defaultnya adalah [] Daftar constraint_value yang harus dipenuhi oleh platform eksekusi agar rangkaian alat ini dipilih untuk membangun target di platform tersebut.
target_compatible_with	Daftar label; tidak dapat dikonfigurasi; defaultnya adalah [] Daftar constraint_value yang harus dipenuhi oleh platform target agar toolchain ini dipilih untuk pembuatan target bagi platform tersebut.
target_settings	Daftar label; defaultnya adalah [] Daftar config_setting yang harus dipenuhi oleh konfigurasi target agar toolchain ini dipilih selama penyelesaian toolchain.
toolchain	Nama; wajib Target yang merepresentasikan alat atau rangkaian alat sebenarnya yang tersedia saat toolchain ini dipilih.
toolchain_type	Label; tidak dapat dikonfigurasi; wajib Label target toolchain_type yang merepresentasikan peran yang dilayani oleh toolchain ini.
use_target_platform_constraints	Boolean; tidak dapat dikonfigurasi; defaultnya adalah False Jika True, toolchain ini berperilaku seolah-olah batasan exec_compatible_with dan target_compatible_with-nya ditetapkan ke batasan platform target saat ini. exec_compatible_with dan target_compatible_with tidak boleh ditetapkan dalam kasus tersebut.

toolchain_type

Lihat sumber aturan

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

Aturan ini menentukan jenis toolchain baru -- target sederhana yang merepresentasikan class alat yang memiliki peran yang sama untuk platform yang berbeda.

Lihat halaman Toolchains untuk mengetahui detail selengkapnya.

Contoh

Tindakan 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 Nama unik untuk target ini.
no_match_error	String; tidak dapat dikonfigurasi; defaultnya adalah "" Pesan error kustom yang akan ditampilkan jika tidak ada toolchain yang cocok untuk jenis ini.