Pendaftaran BazelCon 2024 sudah dibuka!

Halaman ini diterjemahkan oleh Cloud Translation API.

Bermigrasi ke Platform

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

Bazel memiliki dukungan yang canggih untuk pemodelan platform dan toolchain untuk multi-arsitektur dan build yang dikompilasi silang.

Halaman ini merangkum status dukungan ini.

Lihat juga:

Status

C++

Aturan C++ menggunakan platform untuk memilih toolchain saat --incompatible_enable_cc_toolchain_resolution disetel.

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=...

Ini akan diaktifkan secara default pada Bazel 7.0 (#7260).

Untuk menguji project C++ Anda dengan platform, lihat Memigrasikan Project Anda dan Mengonfigurasi toolchain C++.

Java

Aturan Java menggunakan platform untuk memilih toolchain.

Tindakan ini menggantikan tanda lama --java_toolchain, --host_java_toolchain, --javabase, dan --host_javabase.

Lihat Java dan Bazel untuk mengetahui detailnya.

Android

Aturan Android menggunakan platform untuk memilih toolchain saat --incompatible_enable_android_toolchain_resolution disetel.

Ini berarti Anda dapat mengonfigurasi project Android dengan:

bazel build //:my_android_project --android_platforms=//:my_android_platform

bukan dengan tanda lama seperti --android_crosstool_top, --android_cpu, dan --fat_apk_cpu.

Ini akan diaktifkan secara default pada Bazel 7.0 (#16285).

Untuk menguji project Android Anda dengan platform, lihat Memigrasikan Project Anda.

Apple

Aturan Apple tidak mendukung platform dan belum dijadwalkan untuk mendapatkan dukungan.

Anda masih dapat menggunakan API platform dengan build Apple (misalnya, saat membangun dengan campuran aturan Apple dan C++ murni) dengan platform pemetaan.

Bahasa lainnya

Aturan Go mendukung sepenuhnya platform
Aturan Rust sepenuhnya mendukung platform.

Jika Anda memiliki kumpulan aturan bahasa, lihat Memigrasikan kumpulan aturan untuk menambahkan dukungan teknis IT.

Latar belakang

Platform dan toolchain diperkenalkan untuk menstandarkan cara software project menargetkan arsitektur yang berbeda dan melakukan kompilasi silang.

Ini adalah terinspirasi dengan pengamatan bahwa pengelola bahasa telah melakukan hal ini dalam iklan yang tidak kompatibel. Misalnya, aturan C++ menggunakan --cpu dan --crosstool_top untuk mendeklarasikan CPU target dan toolchain. Tidak satu pun membuat model "platform" dengan benar. Hal ini menghasilkan build yang tidak nyaman dan salah.

Java, Android, dan bahasa lain mengembangkan penanda mereka sendiri untuk tujuan serupa, dan tidak ada satu sama lain yang beroperasi satu sama lain. Solusi ini menghasilkan build lintas bahasa membingungkan dan rumit.

Bazel ditujukan untuk project multiplatform berskala besar dan multibahasa. Ini menuntut dukungan yang lebih berprinsip untuk konsep ini, termasuk API standar.

Perlunya migrasi

Upgrade ke API yang baru memerlukan dua upaya: merilis API dan mengupgrade logika aturan untuk menggunakannya.

Yang pertama sudah selesai, tetapi yang kedua sedang berlangsung. Hal ini terdiri dari memastikan platform khusus bahasa dan toolchain ditentukan, toolchain melalui API baru, bukan flag lama seperti --crosstool_top, dan config_setting memilih API baru, bukan tanda lama.

Pekerjaan ini sangat mudah tetapi membutuhkan upaya berbeda untuk setiap bahasa, plus peringatan yang adil bagi pemilik proyek untuk menguji perubahan yang akan datang.

Itulah sebabnya migrasi ini bersifat berkelanjutan.

Sasaran

Migrasi ini selesai jika semua project dibuat dengan formulir:

bazel build //:myproject --platforms=//:myplatform

Ini menyiratkan:

Aturan project Anda memilih toolchain yang tepat untuk //:myplatform.
Dependensi project Anda memilih toolchain yang tepat untuk //:myplatform.
//:myplatform referensi deklarasi umum dari CPU, OS, dan properti generik lain yang tidak bergantung pada bahasa
Semua select() yang relevan cocok dengan //:myplatform.
//:myplatform ditentukan di tempat yang jelas dan dapat diakses: dalam project Anda jika platformnya unik untuk project Anda, atau di beberapa tempat menikmati proyek dapat menemukannya

Tanda lama seperti --cpu, --crosstool_top, dan --fat_apk_cpu akan menjadi tidak digunakan lagi dan dihapus segera setelah aman untuk melakukannya.

Pada akhirnya, ini akan menjadi cara satu-satunya untuk mengonfigurasi arsitektur.

Memigrasikan project Anda

Jika Anda membangun dengan bahasa yang mendukung platform, build Anda seharusnya sudah bekerja dengan pemanggilan seperti:

bazel build //:myproject --platforms=//:myplatform

Lihat Status dan dokumentasi bahasa Anda untuk mengetahui detail selengkapnya.

Jika sebuah bahasa memerlukan flag untuk mengaktifkan dukungan platform, Anda juga harus mengaturnya penanda itu. Lihat Status untuk mengetahui detailnya.

Agar project dapat dibuat, Anda perlu memeriksa hal-hal berikut:

//:myplatform harus ada. Umumnya pemilik proyek bertanggung jawab mendefinisikan platform karena proyek yang berbeda menargetkan komputer yang berbeda pula. Lihat Platform default.
Toolchain yang ingin Anda gunakan harus ada. Jika menggunakan toolchain stok, pemilik bahasa harus menyertakan petunjuk cara mendaftarkannya. Jika untuk menulis toolchain kustom, Anda harus mendaftarkannya di WORKSPACE atau dengan --extra_toolchains.
select() dan transisi konfigurasi harus diselesaikan dengan benar. Lihat select() dan Transitions.
Jika build Anda menggabungkan bahasa yang mendukung dan tidak mendukung platform, Anda mungkin membutuhkan pemetaan platform untuk membantu bahasa lama berfungsi dengan API baru. Lihat Pemetaan platform untuk mengetahui detailnya.

Jika Anda masih mengalami masalah, hubungi dukungan.

Platform default

Pemilik project harus mendefinisikan platform untuk mendeskripsikan arsitektur 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. Ini dibuat secara otomatis pada @platforms//host (alias sebagai @bazel_tools//tools:host_platform) jadi tidak perlu mendefinisikannya secara eksplisit. Alat ini memetakan OS komputer lokal dan CPU dengan constraint_value yang dideklarasikan di @platforms.

`select()`

Project dapat select() di constraint_value target tetapi belum selesai di seluruh platform Google. Hal ini disengaja sehingga select() mendukung berbagai macam sebanyak mungkin. Library dengan sumber khusus ARM harus mendukung semua Mesin 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. Saat memigrasikan project Anda ke platform, Anda harus mengonversinya menjadi constraint_values atau gunakan pemetaan platform untuk mendukung kedua gaya selama 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 selama migrasi. jendela.

Memigrasikan kumpulan aturan

Jika memiliki kumpulan aturan dan ingin mendukung platform, Anda harus:

Buat logika aturan me-resolve toolchain dengan API toolchain. Lihat toolchain API (ctx.toolchains).
Opsional: tentukan flag --incompatible_enable_platforms_for_my_language agar logika aturan secara bergantian me-resolve toolchain melalui API baru atau flag lama seperti --crosstool_top selama pengujian migrasi.
Menentukan properti relevan yang membentuk komponen platform. Lihat Properti platform umum
Menentukan toolchain standar dan membuatnya dapat diakses oleh pengguna melalui petunjuk pendaftaran aturan (detail)
Memastikan select() dan transisi konfigurasi mendukung platform. Ini adalah tantangan terbesar. Hal ini sangat menantang untuk proyek multibahasa (yang mungkin gagal jika semua bahasa tidak dapat membaca --platforms).

Jika Anda perlu menggabungkan aturan yang tidak mendukung platform, Anda mungkin perlu pemetaan platform untuk menjembatani kesenjangan.

Properti platform umum

Properti platform lintas bahasa yang umum seperti OS dan CPU harus yang dideklarasikan di @platforms. Hal ini mendorong aktivitas berbagi, standardisasi, dan kompatibilitas lintas bahasa.

Properti yang unik untuk aturan Anda harus dideklarasikan di repositori aturan Anda. Ini memungkinkan Anda mempertahankan kepemilikan yang jelas atas konsep tertentu yang bertanggung jawab.

Jika aturan Anda menggunakan OS atau CPU dengan tujuan khusus, ini harus dideklarasikan dalam repo aturan vs. @platforms

Pemetaan platform

Pemetaan platform adalah API sementara yang memungkinkan penggabungan logika yang peka platform dengan logika lama dalam build yang sama. Ini adalah alat tumpul yang hanya dimaksudkan untuk inkompatibilitas yang lancar dengan rentang waktu migrasi yang berbeda.

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_x86_64 --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin_x86_64
  --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 desain pemetaan platform untuk mengetahui detailnya.

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.

Untuk informasi selengkapnya lihat di sini.

Pertanyaan

Untuk dukungan umum dan pertanyaan tentang jadwal migrasi, hubungi bazel-discuss atau pemilik aturan yang sesuai.

Untuk diskusi tentang desain dan evolusi API platform/toolchain, hubungi bazel-dev.