Catat Tanggalnya: BazelCon 2023 akan diadakan pada 24-25 Oktober di Google Munich! Pendaftaran sudah dibuka. Pelajari lebih lanjut

Halaman ini diterjemahkan oleh Cloud Translation API.

Switch to English

Bermigrasi ke Platform

Laporkan masalah Lihat sumber

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

Halaman ini merangkum status dukungan ini.

Lihat juga:

Status

C++

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

Ini berarti Anda dapat mengonfigurasi project C++ dengan:

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

bukan yang lama:

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

Fitur ini akan diaktifkan secara default di Bazel 7.0 (#7260).

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

Java

Aturan Java menggunakan platform untuk memilih toolchain.

Ini menggantikan flag 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 ditetapkan.

Ini berarti Anda dapat mengonfigurasi project Android dengan:

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

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

Fitur ini akan diaktifkan secara default di Bazel 7.0 (#16285).

Untuk menguji project Android dengan platform, lihat Memigrasikan Project.

Apel

Aturan Apple tidak mendukung platform dan belum dijadwalkan untuk dukungan.

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

Bahasa lainnya

Aturan Go mendukung sepenuhnya platform
Aturan kasar sepenuhnya mendukung platform.

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

Latar belakang

Platform dan Toolchain diperkenalkan untuk menstandarkan cara project software menargetkan berbagai arsitektur dan kompilasi silang.

Ini diinspirasi oleh pengamatan bahwa pengelola bahasa sudah melakukan ini dalam cara yang tidak kompatibel dan ad hoc. Misalnya, aturan C++ menggunakan --cpu dan --crosstool_top untuk mendeklarasikan CPU dan toolchain target. Tidak satu pun dari model ini yang memodelkan "platform" dengan benar. Hal ini menghasilkan build yang canggung dan salah.

Java, Android, dan bahasa lainnya mengembangkan flag mereka sendiri untuk tujuan serupa, yang tidak saling beroperasi satu sama lain. Hal ini membuat build lintas bahasa membingungkan dan rumit.

Bazel ditujukan untuk project besar multi-bahasa dan multi-platform. Hal ini memerlukan dukungan yang lebih prinsip untuk konsep ini, termasuk API standar yang jelas.

Kebutuhan untuk migrasi

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

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

Upaya ini sederhana tetapi memerlukan upaya yang berbeda untuk setiap bahasa, ditambah peringatan yang adil bagi pemilik project untuk menguji perubahan mendatang.

Itulah sebabnya migrasi ini sedang berlangsung.

Sasaran

Migrasi ini selesai jika semua project di-build 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 mereferensikan deklarasi umum CPU, OS, dan properti umum lainnya yang tidak bergantung pada bahasa
Semua select() yang relevan cocok dengan //:myplatform.
//:myplatform ditentukan di tempat yang jelas dan dapat diakses: di replika project Anda jika platform bersifat unik untuk project Anda, atau beberapa tempat umum semua project yang memakainya dapat menemukannya

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

Pada akhirnya, ini akan menjadi cara tunggal untuk mengonfigurasi arsitektur.

Memigrasikan project Anda

Jika Anda mem-build dengan bahasa yang mendukung platform, build Anda seharusnya sudah berfungsi 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 perlu menetapkan flag tersebut. Lihat Status untuk mengetahui detailnya.

Agar project Anda di-build, periksa hal-hal berikut:

//:myplatform harus ada. Secara umum, pemilik project bertanggung jawab untuk menentukan platform karena project yang berbeda menargetkan mesin yang berbeda. Lihat Platform default.
Toolchain yang ingin Anda gunakan harus ada. Jika menggunakan toolchain saham, pemilik bahasa harus menyertakan petunjuk tentang cara mendaftarkannya. Jika menulis toolchain kustom sendiri, Anda perlu mendaftarkan di WORKSPACE atau dengan --extra_toolchains.
select() dan transisi konfigurasi harus diselesaikan dengan benar. Lihat select() dan Transitions.
Jika build Anda mencampur bahasa yang mendukung dan tidak mendukung platform, Anda mungkin memerlukan pemetaan platform untuk membantu bahasa lama bekerja dengan API baru. Lihat Pemetaan platform untuk mengetahui detailnya.

Jika Anda masih mengalami masalah, hubungi untuk mendapatkan dukungan.

Platform default

Pemilik project harus menentukan platform eksplisit untuk mendeskripsikan arsitektur yang ingin dibuat. Ini kemudian dipicu dengan --platforms.

Jika --platforms tidak ditetapkan, Bazel akan ditetapkan secara default ke platform yang mewakili mesin build lokal. Ini dibuat secara otomatis di @local_config_platform//:host sehingga Anda tidak perlu menentukannya secara eksplisit. Ini memetakan OS mesin lokal dan CPU dengan constraint_value yang dideklarasikan di @platforms.

`select()`

Project dapat select() pada target constraint_value, tetapi tidak dapat menyelesaikan platform. Hal ini disengaja sehingga 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 di satu atau beberapa constraint_value, gunakan:

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

Hal 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 menjadi constraint_values atau menggunakan pemetaan platform untuk mendukung kedua gaya selama migrasi.

Transisi

Transisi Starlark mengubah flag bawah pada bagian grafik build Anda. Jika project Anda menggunakan transisi yang menetapkan --cpu, --crossstool_top, atau flag lama lainnya, aturan yang membaca --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 selama migrasi. jendela.

Memigrasikan kumpulan aturan Anda

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

Memiliki logika aturan untuk menyelesaikan toolchain dengan API toolchain. Lihat API toolchain (ctx.toolchains).
Opsional: Tentukan flag --incompatible_enable_platforms_for_my_language agar logika aturan secara alternatif menyelesaikan toolchain melalui API baru atau flag lama, seperti --crosstool_top, selama pengujian migrasi.
Tentukan properti relevan yang membentuk komponen platform. Lihat Properti platform umum
Tentukan toolchain standar dan buat agar dapat diakses oleh pengguna melalui petunjuk pendaftaran aturan Anda (detail)
Memastikan platform transisi select() dan transisi konfigurasi. Ini adalah tantangan terbesar. Ini sangat menantang untuk project multibahasa (yang mungkin gagal jika semua bahasa tidak dapat membaca --platforms).

Jika perlu tercampur dengan aturan yang tidak mendukung platform, Anda mungkin memerlukan pemetaan platform untuk menjembatani kesenjangan.

Properti platform umum

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

Properti yang unik untuk aturan Anda harus dideklarasikan dalam repo aturan. Ini memungkinkan Anda mempertahankan kepemilikan yang jelas atas konsep tertentu yang menjadi tanggung jawab aturan Anda.

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

Pemetaan platform

Pemetaan platform adalah API sementara yang memungkinkan perpaduan logika platform dengan logika lama dalam build yang sama. Ini adalah alat tumpul yang hanya ditujukan untuk memadukan inkompatibilitas dengan jangka waktu migrasi yang berbeda.

Pemetaan platform adalah peta platform() ke kumpulan tanda lama yang sesuai atau kebalikannya. 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 setelan, baik yang berbasis platform maupun yang 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 desain pemetaan platform untuk mengetahui detailnya.

Peninjauan API

platform adalah kumpulan constraint_value target:

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. Atribut ini mendeklarasikan alat bahasa (seperti compiler = "//mytoolchain:custom_gcc"). Penyedianya meneruskan informasi ini ke aturan yang perlu dibuat dengan alat ini.

Toolchain mendeklarasikan constraint_value mesin yang dapat ditargetkan (target_compatible_with = ["@platforms//os:linux"]) dan mesin yang dapat dijalankan (exec_compatible_with = ["@platforms//os:mac"]) oleh alat mereka.

Saat mem-build $ bazel build //:myproject --platforms=//:myplatform, Bazel akan otomatis memilih toolchain yang dapat berjalan di mesin build dan membuat biner untuk //:myplatform. Ini dikenal sebagai resolusi toolchain.

Kumpulan 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 linimasa migrasi, hubungi bazel-discuss atau pemilik aturan yang sesuai.

Untuk pembahasan tentang desain dan evolusi API platform/Toolchain, hubungi bazel-dev.