Bazel memiliki dukungan yang canggih untuk membuat model platform dan toolchain. Integrasi ini memerlukan kerja sama yang cermat antara pemilik kode, pengelola aturan, dan developer 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
diupdate. 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 project software menargetkan berbagai mesin dan membangun dengan alat bahasa yang tepat.
Ini adalah karakter yang baru ditambahkan oleh Bazel. Hal ini
terinspirasi
oleh pengamatan bahwa pengelola bahasa sudah melakukan ini secara ad
hoc dan tidak kompatibel. Misalnya, aturan C++ menggunakan --cpu
dan --crosstool_top
untuk menetapkan toolchain C++ dan CPU target dari build. Tak satu pun dari keduanya yang
memodelkan "platform". Upaya historis untuk melakukannya menyebabkan build yang canggung dan tidak akurat.
Flag ini juga tidak mengontrol kompilasi Java, yang mengembangkan
antarmuka independennya sendiri dengan --java_toolchain
.
Bazel ditujukan untuk project multiplatform berskala besar dan multibahasa. Hal ini memerlukan dukungan yang lebih berprinsip untuk konsep ini, termasuk API yang jelas yang mendorong bahasa dan interoperabilitas project. Inilah kegunaan API baru ini.
Migrasi
API platform dan toolchain hanya berfungsi jika project benar-benar menggunakannya. Ini
tidaklah mudah karena logika aturan, toolchain, dependensi, dan
select()
project harus mendukungnya. Hal ini memerlukan urutan migrasi yang cermat
agar semua project dan dependensinya berfungsi dengan benar.
Misalnya, Aturan C++ Bazel mendukung platform. Namun, Apple Rules tidak. Project C++ Anda mungkin tidak terkait dengan Apple. Namun, sebagian lainnya mungkin. Jadi, belum aman untuk mengaktifkan platform secara global di semua build C++.
Bagian selanjutnya dari halaman ini akan menjelaskan urutan migrasi ini serta bagaimana dan kapan project Anda bisa cocok.
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 bergantung pada dukungan Anda
//:myplatform
atau project Anda mendukung API lama (seperti--crosstool_top
). //:myplatform
merujuk ke [deklarasi umum][Pernyataan Platform Umum]{: .external} dariCPU
,OS
, dan konsep umum lainnya yang mendukung kompatibilitas lintas project otomatis.- Semua
select()
project yang relevan memahami properti mesin yang tersirat oleh//:myplatform
. //:myplatform
ditentukan di tempat yang jelas dan dapat digunakan kembali: di repositori project Anda jika platform tersebut bersifat unik untuk project Anda. Jika tidak, di suatu tempat yang dapat ditemukan oleh 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 project, Anda harus mengikuti dokumentasi resmi project.
Jika Anda merupakan pengelola project, bahasa, atau toolchain, Anda mungkin perlu mendukung API baru. 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 tepat untuk properti, bukan flag 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, lalu menambahkan CPU baru yang mendukung kumpulan petunjuk yang sama,select()
akan gagal mengenali CPU baru. Namun,select()
di platform akan tetap akurat. - Pengalaman pengguna yang lebih sederhana. Semua project memahami:
--platforms=//:myplatform
. Tidak perlu banyak penanda khusus bahasa pada baris perintah. - 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 dalam fase build dan pengujian jika tidak kompatibel dengan platform target.
Biaya
- Project dependen yang belum mendukung platform mungkin tidak otomatis berfungsi dengan project 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 properti
mesin. Nilai "jenis" yang sama dikelompokkan dalam constraint_setting
umum:
constraint_setting(name = "os")
constraint_value(
name = "linux",
constraint_setting = ":os",
)
constraint_value(
name = "mac",
constraint_setting = ":os",
)
toolchain
adalah aturan Starlark. Atributnya mendeklarasikan alat bahasa (seperti compiler =
"//mytoolchain:custom_gcc"
). Penyedianya meneruskan informasi ini ke aturan yang perlu di-build dengan alat tersebut.
Toolchain mendeklarasikan constraint_value
mesin yang dapat mereka
targetkan
(target_compatible_with = ["@platforms//os:linux"]
) dan mesin yang dapat
dijalankan
(exec_compatible_with = ["@platforms//os:mac"]
).
Saat mem-build $ bazel build //:myproject --platforms=//:myplatform
, Bazel
akan otomatis memilih toolchain yang dapat dijalankan 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 API (
ctx.toolchains
) baru 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, hal ini mudah tetapi harus diatur secara cerdas untuk mempertahankan pengalaman pengguna yang mudah.Definisi platform juga diperlukan (kecuali jika Anda mem-build untuk mesin yang sama yang digunakan Bazel). Umumnya, proyek harus menentukan platformnya sendiri.
Project yang sudah ada harus dimigrasikan.
select()
dan transisi juga harus dimigrasikan. Ini adalah tantangan terbesar. Hal ini sangat sulit dilakukan untuk project multibahasa (yang mungkin gagal jika semua bahasa tidak dapat membaca--platforms
).
Jika Anda mendesain kumpulan aturan baru, Anda harus mendukung platform dari awal. Hal ini secara otomatis membuat aturan Anda kompatibel dengan aturan dan project lainnya, dengan nilai yang terus meningkat karena API platform menjadi semakin banyak digunakan.
Properti platform umum
Properti platform seperti OS
dan CPU
yang umum di seluruh project harus
dideklarasikan di tempat standar dan terpusat. Hal ini mendorong kompatibilitas lintas
project dan lintas bahasa.
Misalnya, jika MyApp memiliki select()
di constraint_value
@myapp//cpus:arm
dan SomeCommonLib memiliki select()
di
@commonlib//constraints:arm
, ini akan memicu mode "arm"-nya dengan kriteria
yang tidak kompatibel.
Properti yang umum secara global dideklarasikan dalam repo
@platforms
(jadi label kanonis untuk contoh di atas adalah @platforms//cpu:arm
).
Properti bahasa umum harus dideklarasikan dalam repo masing-masing
bahasa.
Platform default
Umumnya, pemilik project harus menentukan platform eksplisit untuk mendeskripsikan jenis mesin yang ingin mereka bangun. Peristiwa ini kemudian dipicu dengan
--platforms
.
Jika --platforms
tidak disetel, Bazel akan ditetapkan secara default ke platform
yang mewakili
mesin build lokal. ID ini dibuat secara otomatis di @local_config_platform//:host
,
jadi tidak perlu menentukannya secara eksplisit. Objek ini memetakan OS
dan CPU
komputer lokal dengan constraint_value
yang dideklarasikan dalam
@platforms
.
C++
Aturan C++ Bazel menggunakan platform untuk memilih toolchain saat Anda menetapkan
--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 merupakan C++ murni dan tidak bergantung pada project non-C++, Anda dapat menggunakan
platform dengan aman selama select
dan
transisi kompatibel. Lihat
#7260 dan
Mengonfigurasi toolchain C++ untuk mendapatkan panduan selengkapnya.
Mode ini tidak diaktifkan secara default. Hal ini karena project Apple 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 menetapkan
--incompatible_enable_android_toolchain_resolution
.
Opsi ini tidak diaktifkan secara default. Namun, migrasi sedang berlangsung.
Apel
Aturan Apple Bazel belum mendukung platform untuk toolchain Apple tertentu.
Alat tersebut juga tidak mendukung dependensi C++ yang mendukung platform karena menggunakan
--crosstool_top
lama untuk menetapkan toolchain C++. Hingga migrasi ini dimigrasikan, Anda dapat menggabungkan project Apple dengan C++ yang mendukung platorm dengan pemetaan platform (contoh).
Bahasa lainnya
- Aturan Rust Bazel sepenuhnya mendukung platform.
- Aturan Go Bazel sepenuhnya mendukung platform (detail).
Jika Anda mendesain aturan untuk bahasa baru, gunakan platform untuk memilih toolchain bahasa Anda. Lihat dokumentasi toolchain untuk panduan yang baik.
select()
Project dapat select()
pada
target constraint_value
, tetapi tidak dapat menyelesaikan
platform. Hal ini disengaja agar select()
mendukung
sebanyak mungkin mesin. Library dengan sumber khusus ARM
harus mendukung
semua mesin yang didukung ARM
kecuali jika 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
. Saat
memigrasikan project ke platform, Anda harus mengonversinya ke
constraint_values
atau menggunakan pemetaan platform untuk mendukung
kedua gaya melalui periode migrasi.
Transisi
Transisi Starlark mengubah
tombol di grafik build ke bawah. Jika project Anda menggunakan transisi yang menetapkan --cpu
, --crossstool_top
, atau tanda lama lainnya, aturan yang bertuliskan --platforms
tidak akan melihat perubahan ini.
Saat memigrasikan project ke platform, Anda harus mengonversi perubahan seperti
return { "//command_line_option:cpu": "arm" }
ke return {
"//command_line_option:platforms": "//:my_arm_platform" }
atau menggunakan pemetaan
platform untuk mendukung kedua gaya melalui periode
migrasi.
Cara menggunakan platform saat ini
Jika Anda hanya ingin membuat atau mengompilasi silang sebuah project, Anda harus mengikuti dokumentasi resmi project tersebut. Pengelola project dan bahasa dapat menentukan cara dan waktu berintegrasi dengan platform, serta nilai apa yang ditawarkan.
Jika Anda adalah pengelola project, bahasa, atau toolchain dan build Anda tidak menggunakan platform secara default, Anda memiliki tiga opsi (selain menunggu migrasi global):
Lihat tanda "gunakan platform" untuk bahasa project Anda (jika ada) dan lakukan pengujian apa pun yang diperlukan untuk melihat apakah project yang Anda minati sesuai.
Jika project yang penting bagi Anda masih bergantung pada flag lama seperti
--cpu
dan--crosstool_top
, gunakan keduanya bersama dengan--platforms
:bazel build //:my_mixed_project --platforms==//:myplatform --cpu=... --crosstool_top=...
Tindakan ini memerlukan biaya pemeliharaan (Anda harus memastikan setelannya sama secara manual). Namun, cara ini akan berfungsi jika tidak ada transisi pemberontak.
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 logika yang didukung platform dan teknologi lama berdampingan dalam build yang sama melalui periode penghentian yang kedua.
Pemetaan platform adalah peta platform()
ke
kumpulan 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 setelan, baik yang berbasis platform maupun lama, diterapkan secara konsisten di seluruh build, termasuk melalui transisi.
Secara default, Bazel membaca pemetaan dari file platform_mappings
di root ruang kerja Anda. Anda juga dapat menetapkan --platform_mappings=//:my_custom_mapping
.
Lihat di sini untuk mengetahui detail selengkapnya.
Pertanyaan
Untuk mendapatkan dukungan umum dan pertanyaan tentang linimasa migrasi, hubungi bazel-discuss@googlegroups.com atau pemilik aturan yang sesuai.
Untuk diskusi tentang desain dan evolusi API platform/Unity, hubungi bazel-dev@googlegroups.com.