Bazel memiliki dukungan canggih untuk platform pemodelan dan Rantai Konten. Integrasi ini dengan proyek nyata membutuhkan kerja sama yang cermat antara pemilik kode, pengelola aturan, dan pengembang inti Bazel.
Halaman ini merangkum tujuan platform dan menunjukkan cara membangun dengan platform tersebut.
tl;dr: API platform dan toolchain Bazel tersedia, tetapi tidak akan berfungsi
di mana saja hingga semua aturan bahasa, select()
, dan referensi lama lainnya
diperbarui. Hal ini akan terus dilakukan. Pada akhirnya semua build akan berbasis platform.
Baca informasi di bawah ini untuk mengetahui kecocokan build Anda.
Untuk dokumentasi yang lebih formal, lihat:
Latar belakang
Platform dan toolchain diperkenalkan untuk menstandarkan cara software proyek menargetkan komputer yang berbeda dan membangun dengan alat bahasa yang tepat.
Ini adalah karakter yang baru ditambahkan oleh Bazel. Hal itu
terinspirasi
dengan pengamatan bahwa pengelola bahasa sudah melakukannya dalam iklan
yang tidak kompatibel. Misalnya, aturan C++ menggunakan --cpu
dan --crosstool_top
untuk menyetel target CPU dan toolchain C++ build. Tak satu pun dari model yang benar
sebuah "platform". Upaya historis untuk melakukannya menyebabkan build yang canggung dan tidak akurat.
Flag ini juga tidak mengontrol kompilasi Java, yang mengembangkan
antarmuka independen dengan --java_toolchain
.
Bazel ditujukan untuk project multiplatform berskala besar dan multibahasa. Ini menuntut dukungan yang lebih berprinsip untuk konsep ini, termasuk API yang jelas mendorong interoperabilitas bahasa dan proyek. Inilah API baru yang untuk mereka.
Migrasi
API platform dan toolchain hanya berfungsi jika project benar-benar menggunakannya. Ini
tidak mudah karena logika aturan, toolchain, dependensi, dan
select()
harus mendukungnya. Hal ini memerlukan urutan migrasi yang cermat
untuk menjaga agar semua proyek
dan dependensinya bekerja dengan benar.
Misalnya, Bazel Aturan C++ mendukung platform. Namun, Apple Rules tidak. Project C++ Anda mungkin tidak peduli dengan Apple. Tetapi yang lain mungkin. Namun belum aman untuk mengaktifkan platform secara global untuk semua build C++.
Bagian selanjutnya dari halaman ini akan menjelaskan urutan migrasi ini serta bagaimana dan kapan sesuai dengan proyek Anda.
Sasaran
Migrasi platform Bazel selesai saat semua project dibuat dengan formulir:
bazel build //:myproject --platforms=//:myplatform
Ini menyiratkan:
- Aturan yang digunakan project Anda dapat menyimpulkan toolchain yang benar dari
//:myplatform
. - Aturan yang digunakan dependensi project Anda dapat menyimpulkan toolchain yang benar
dari
//:myplatform
. - Baik project yang tergantung pada dukungan Anda,
//:myplatform
atau project mendukung API lama (seperti--crosstool_top
). //:myplatform
referensi [deklarasi umum][Pernyataan Platform Umum]{: .external} dariCPU
,OS
, dan konsep umum lainnya yang mendukung lintas project otomatis kompatibilitas mundur.- Semua project yang relevan
select()
memahami properti mesin yang tersirat oleh//:myplatform
. //:myplatform
ditentukan di tempat yang jelas dan dapat digunakan kembali: dalam project Anda jika platformnya unik untuk project Anda, atau di suatu tempat untuk semua project yang mungkin menggunakan platform ini.
API lama akan dihapus segera setelah sasaran ini tercapai. Maka ini akan menjadi cara standar bagi project untuk memilih platform dan toolchain.
Haruskah saya menggunakan platform?
Jika Anda hanya ingin membuat atau mengompilasi silang sebuah proyek, Anda harus mengikuti dokumentasi resmi proyek.
Jika Anda mengelola project, bahasa, atau toolchain, Anda mungkin ingin untuk mendukung API baru ini. Apakah Anda menunggu hingga migrasi global selesai atau memilih ikut serta lebih awal bergantung pada kebutuhan nilai / biaya spesifik Anda:
Nilai
- Anda dapat
select()
atau memilih toolchain di properti yang Anda inginkan alih-alih penanda hard code seperti--cpu
. Misalnya, beberapa CPU dapat mendukung kumpulan petunjuk yang sama. - Build yang lebih tepat. Jika Anda melakukan
select()
dengan--cpu
dalam contoh di atas, maka menambahkan CPU baru yang mendukung set petunjuk yang sama, yaituselect()
gagal mengenali CPU baru. Namun,select()
di platform akan tetap akurat. - Pengalaman pengguna yang lebih sederhana. Semua project memahami:
--platforms=//:myplatform
. Tidak perlu menggunakan beberapa bahasa pada command line. - Desain bahasa yang lebih sederhana. Semua bahasa memiliki API yang sama untuk menentukan toolchain, menggunakan toolchain, dan memilih toolchain yang tepat untuk suatu platform.
- Target dapat dilewati di membangun dan menguji jika mereka tidak kompatibel dengan platform target.
Biaya
- Project dependen yang belum mendukung platform mungkin tidak berfungsi secara otomatis dengan Anda.
- Agar dapat berfungsi, mungkin diperlukan pemeliharaan sementara tambahan.
- Koeksistensi API baru dan lama memerlukan panduan pengguna yang lebih cermat untuk menghindari kebingungan.
- Definisi kanonis untuk properti umum seperti
OS
danCPU
masih terus berkembang dan mungkin memerlukan kontribusi awal tambahan. - Definisi kanonis untuk toolchain khusus bahasa masih terus berkembang dan mungkin memerlukan kontribusi awal tambahan.
Peninjauan API
platform
adalah kumpulan
Target constraint_value
:
platform(
name = "myplatform",
constraint_values = [
"@platforms//os:linux",
"@platforms//cpu:arm",
],
)
constraint_value
adalah mesin
saat ini. Nilai "jenis" yang sama dikelompokkan ke dalam
constraint_setting
:
constraint_setting(name = "os")
constraint_value(
name = "linux",
constraint_setting = ":os",
)
constraint_value(
name = "mac",
constraint_setting = ":os",
)
toolchain
adalah aturan Starlark. Ini
mendeklarasikan alat bahasa (seperti compiler =
"//mytoolchain:custom_gcc"
). penyedia-nya meneruskan
informasi ini menjadi aturan yang perlu
dibuat dengan alat ini.
Toolchain mendeklarasikan constraint_value
mesin yang dapat
target
(target_compatible_with = ["@platforms//os:linux"]
) dan mesin yang dapat digunakan alat mereka
jalankan pada
(exec_compatible_with = ["@platforms//os:mac"]
).
Saat membangun $ bazel build //:myproject --platforms=//:myplatform
, Bazel
secara otomatis memilih toolchain yang dapat berjalan di mesin build dan
biner build untuk //:myplatform
. Hal ini dikenal sebagai resolusi toolchain.
Set toolchain yang tersedia dapat didaftarkan di WORKSPACE
dengan
register_toolchains
atau di
command line dengan --extra_toolchains
.
Lihat di sini untuk mempelajari lebih lanjut.
Status
Dukungan platform saat ini bervariasi antarbahasa. Semua aturan utama Bazel berpindah ke platform. Namun, proses ini akan memakan waktu. Hal ini disebabkan oleh tiga alasan utama:
Logika aturan harus diperbarui untuk mendapatkan info alat dari toolchain baru API (
ctx.toolchains
) dan berhenti membaca setelan lama seperti--cpu
dan--crosstool_top
. Hal ini relatif mudah.Pengelola toolchain harus menentukan toolchain dan membuatnya dapat diakses oleh pengguna (di repositori GitHub dan entri
WORKSPACE
). Secara teknis, ini mudah tetapi harus diatur secara cerdas agar mempertahankan pengalaman pengguna yang mudah.Definisi platform juga diperlukan (kecuali jika Anda membangun untuk mesin yang sama Bazel sudah dinyalakan). Umumnya, proyek harus menentukan platformnya sendiri.
Project yang sudah ada harus dimigrasikan.
select()
dtk dan transisi juga harus dimigrasikan. Ini adalah tantangan terbesar. Hal ini sangat menantang bagi project multibahasa (yang mungkin gagal jika semua bahasa tidak dapat membaca--platforms
).
Jika Anda merancang kumpulan aturan baru, Anda harus mendukung platform dari memulai. Hal ini secara otomatis membuat aturan Anda kompatibel dengan aturan dan project, dengan nilai yang terus meningkat seiring dengan makin ada di mana-mana.
Properti platform umum
Properti platform seperti OS
dan CPU
yang umum di seluruh project harus
dideklarasikan di tempat
standar dan terpusat. Hal ini mendorong lintas proyek
dan kompatibilitas lintas bahasa.
Misalnya, jika MyApp memiliki select()
di constraint_value
@myapp//cpus:arm
dan SomeCommonLib memiliki select()
di
@commonlib//constraints:arm
, ini memicu "arm"-nya mode multi-mode dengan
kriteria.
Properti yang umum secara global dideklarasikan dalam
Repositori @platforms
(jadi label kanonis untuk contoh di atas adalah @platforms//cpu:arm
).
Properti bahasa yang umum harus dideklarasikan dalam repositorinya masing-masing
bahasa.
Platform default
Umumnya, pemilik proyek
harus mendefinisikan pernyataan
platform untuk mendeskripsikan
jenis mesin yang ingin mereka bangun. Hal ini kemudian dipicu dengan
--platforms
.
Jika --platforms
tidak disetel, Bazel akan ditetapkan secara default ke platform
yang mewakili
mesin build lokal. Ringkasan ini dibuat secara otomatis pukul @local_config_platform//:host
jadi tidak perlu mendefinisikannya secara eksplisit. Alat ini memetakan OS
komputer lokal
dan CPU
dengan constraint_value
yang dideklarasikan di
@platforms
.
C++
Aturan C++ Bazel menggunakan platform untuk memilih toolchain saat Anda mengatur
--incompatible_enable_cc_toolchain_resolution
(#7260).
Artinya, Anda dapat mengonfigurasi project C++ dengan:
bazel build //:my_cpp_project --platforms=//:myplatform
alih-alih yang lama:
bazel build //:my_cpp_project` --cpu=... --crosstool_top=... --compiler=...
Jika project Anda murni C++ dan tidak bergantung pada project non-C++, Anda dapat menggunakan
platform tetap aman selama select
dan
transisi kompatibel. Lihat
#7260 dan
Mengonfigurasi toolchain C++ untuk panduan selengkapnya.
Mode ini tidak diaktifkan secara default. Hal ini karena Apple memproyeksikan
masih mengonfigurasi dependensi C++ dengan --cpu
dan --crosstool_top
(contoh). Jadi, cara ini bergantung pada aturan Apple yang dimigrasikan ke platform.
Java
Aturan Java Bazel menggunakan platform.
Tindakan ini menggantikan tanda lama --java_toolchain
, --host_java_toolchain
,
--javabase
, dan --host_javabase
.
Untuk mempelajari cara menggunakan tanda konfigurasi, lihat panduan Bazel dan Java. Untuk mengetahui informasi tambahan, lihat Dokumen desain.
Jika Anda masih menggunakan tanda lama, ikuti proses migrasi di Masalah #7849.
Android
Aturan Android Bazel menggunakan platform untuk memilih toolchain saat Anda mengatur
--incompatible_enable_android_toolchain_resolution
.
Opsi ini tidak diaktifkan secara default. Namun, migrasi sedang berlangsung.
Apple
Aturan Apple Bazel belum mendukung platform untuk toolchain Apple tertentu.
Mereka juga tidak mendukung dependensi C++ yang diaktifkan platform karena mereka menggunakan
--crosstool_top
lama untuk menetapkan toolchain C++. Hingga proses migrasi ini dimigrasikan, Anda
dapat menggabungkan project Apple dengan C++ yang mendukung platorm dengan platform
pemetaan
(contoh).
Bahasa lainnya
- Aturan Rust Bazel sepenuhnya mendukung di berbagai platform Google.
- Aturan Go Bazel mendukung penuh platform (detail).
Jika Anda merancang aturan untuk bahasa baru, gunakan {i>platform<i} untuk memilih toolchain bahasa Anda. Lihat dokumentasi toolchain untuk panduan yang baik.
select()
Project dapat select()
di
constraint_value
target tetapi belum selesai
di berbagai platform Google. Hal ini disengaja agar select()
mendukung berbagai
sebanyak mungkin. Library dengan sumber khusus ARM
harus mendukung
semua mesin yang didukung ARM
kecuali ada alasan untuk lebih spesifik.
Untuk memilih satu atau beberapa constraint_value
, gunakan:
config_setting(
name = "is_arm",
constraint_values = [
"@platforms//cpu:arm",
],
)
Tindakan ini sama dengan memilih secara tradisional di --cpu
:
config_setting(
name = "is_arm",
values = {
"cpu": "arm",
},
)
Lihat detail selengkapnya di sini.
select
di --cpu
, --crosstool_top
, dll. tidak memahami --platforms
. Kapan
memigrasikan project Anda ke platform, Anda harus mengonversinya menjadi
constraint_values
atau gunakan pemetaan platform untuk mendukung
kedua gaya melalui jendela migrasi.
Transisi
Perubahan Transisi Starlark
menandai bagian grafik build Anda. Jika proyek Anda menggunakan transisi yang
menetapkan --cpu
, --crossstool_top
, atau tanda lama lainnya, aturan yang terbaca
--platforms
tidak akan melihat perubahan ini.
Saat memigrasikan project Anda ke platform, Anda harus mengonversi perubahan seperti
return { "//command_line_option:cpu": "arm" }
ke return {
"//command_line_option:platforms": "//:my_arm_platform" }
atau gunakan platform
pemetaan untuk mendukung kedua gaya melalui migrasi
jendela.
Cara menggunakan platform saat ini
Jika Anda hanya ingin membuat atau mengompilasi silang sebuah proyek, Anda harus mengikuti dokumentasi resmi proyek. Terserah bahasa dan pengelola proyek untuk menentukan bagaimana dan kapan mengintegrasikannya dengan platform, dan nilai apa yang ditawarkan.
Jika Anda adalah pengelola project, bahasa, atau toolchain dan build Anda tidak menggunakan platform secara {i>default<i}, Anda memiliki tiga opsi (selain menunggu migrasi):
Buka "platform penggunaan" untuk bahasa proyek Anda (jika ada satu) dan lakukan pengujian apa pun yang diperlukan untuk melihat apakah project yang diminati tentang pekerjaan.
Jika project yang Anda minati masih bergantung pada flag lama seperti
--cpu
dan--crosstool_top
, gunakan ini bersama dengan--platforms
:bazel build //:my_mixed_project --platforms==//:myplatform --cpu=... --crosstool_top=...
Hal ini membutuhkan biaya pemeliharaan (Anda harus memastikan setelan yang cocok). Namun, cara ini seharusnya berhasil jika tidak ada bias transisi.
Tulis pemetaan platform untuk mendukung kedua gaya dengan memetakan setelan gaya
--cpu
ke platform yang sesuai dan sebaliknya.
Pemetaan platform
Pemetaan platform adalah API sementara yang memungkinkan koeksistensi logika yang didukung versi lama dalam build yang sama melalui penghentian penggunaan yang terakhir jendela.
Pemetaan platform adalah peta platform()
ke
set tanda lama yang sesuai atau sebaliknya. Contoh:
platforms:
# Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
//platforms:ios
--cpu=ios_x86_64
--apple_platform_type=ios
flags:
# Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
--cpu=ios_x86_64
--apple_platform_type=ios
//platforms:ios
# Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
--cpu=darwin
--apple_platform_type=macos
//platforms:macos
Bazel menggunakannya untuk menjamin semua pengaturan, baik yang berbasis platform yang lama, diterapkan secara konsisten di seluruh build, termasuk melalui transisi.
Secara default, Bazel membaca pemetaan dari file platform_mappings
dalam
root workspace. Anda juga dapat mengatur
--platform_mappings=//:my_custom_mapping
.
Lihat di sini untuk detail selengkapnya.
Pertanyaan
Untuk dukungan umum dan pertanyaan tentang jadwal migrasi, hubungi bazel-discuss@googlegroups.com atau pemilik aturan yang sesuai.
Untuk diskusi tentang desain dan evolusi API platform/toolchain, kontak bazel-dev@googlegroups.com.