Bermigrasi ke Platform

Bazel memiliki dukungan canggih untuk memodelkan platform dan toolchain untuk build multi-arsitektur dan lintas kompilasi.

Halaman ini merangkum status dukungan ini.

Lihat juga:

• Platform
• Toolchain
• Latar belakang

Status

C++

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

Artinya, 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++ Anda dengan platform, lihat Memigrasikan Project Anda dan Mengonfigurasi toolchain C++.

Java

Aturan Java menggunakan platform untuk memilih toolchain.

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

Artinya, 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 Anda dengan platform, lihat Memigrasikan Project Anda.

Apple

Aturan Apple tidak mendukung platform dan belum dijadwalkan untuk dukungan.

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

Bahasa lainnya

• Aturan Go sepenuhnya mendukung platform
• Aturan Rust 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 software project menargetkan arsitektur yang berbeda dan lintas kompilasi.

Hal ini terinspirasi oleh pengamatan bahwa pemelihara bahasa sudah melakukannya dengan cara ad hoc yang tidak kompatibel. Misalnya, aturan C++ menggunakan --cpu dan --crosstool_top untuk mendeklarasikan CPU dan toolchain target. Tidak ada 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 dapat dioperasikan 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 berprinsip 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, tetapi yang kedua masih 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 di API baru, bukan flag lama.

Pekerjaan ini mudah, tetapi memerlukan upaya yang berbeda untuk setiap bahasa, ditambah peringatan yang adil bagi pemilik project untuk menguji perubahan yang akan datang.

Inilah alasan migrasi ini sedang berlangsung.

Sasaran

Migrasi ini selesai saat semua project di-build dengan formulir:

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

Hal ini berarti:

1. Aturan project Anda memilih toolchain yang tepat untuk //:myplatform.
2. Dependensi project Anda memilih toolchain yang tepat untuk //:myplatform.
3. //:myplatform mereferensikan deklarasi umum dari CPU, OS, dan properti generik lainnya yang tidak bergantung pada bahasa
4. Semua select() yang relevan cocok dengan //:myplatform dengan benar.
5. //:myplatform ditentukan di tempat yang jelas dan dapat diakses: di repo project Anda jika platform tersebut unik untuk project Anda, atau di tempat umum yang dapat ditemukan oleh semua project yang menggunakan

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

Pada akhirnya, ini akan menjadi satu-satunya cara 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 yang tepat.

Jika bahasa memerlukan flag untuk mengaktifkan dukungan platform, Anda juga perlu menetapkan flag tersebut. Lihat Status untuk mengetahui detailnya.

Agar project Anda dapat di-build, Anda harus memeriksa hal berikut:

1. //:myplatform harus ada. Secara umum, pemilik project bertanggung jawab untuk menentukan platform karena project yang berbeda menargetkan mesin yang berbeda. Lihat Platform default.

2. Toolchain yang ingin Anda gunakan harus ada. Jika menggunakan toolchain stok, pemilik bahasa harus menyertakan petunjuk cara mendaftarkannya. Jika menulis toolchain kustom Anda sendiri, Anda harus mendaftarkannya dalam file MODULE.bazel atau dengan --extra_toolchains.

3. select()s dan transisi konfigurasi harus diselesaikan dengan benar. Lihat select() dan Transisi.

4. Jika build Anda mencampur bahasa yang mendukung dan tidak mendukung platform, Anda mungkin memerlukan 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 menentukan platform eksplisit untuk menjelaskan arsitektur yang ingin mereka build. Kemudian, platform ini akan dipicu dengan --platforms.

Jika --platforms tidak ditetapkan, Bazel akan menggunakan platform default yang mewakili mesin build lokal. Platform ini dibuat secara otomatis di @platforms//host (diberi alias sebagai @bazel_tools//tools:host_platform) sehingga Anda tidak perlu menentukannya secara eksplisit. Platform ini memetakan OS dan CPU mesin lokal dengan constraint_values yang dideklarasikan di @platforms.

select()

Project dapat select() pada constraint_value target tetapi tidak pada platform lengkap. Hal ini disengaja agar select() mendukung berbagai mesin seluas mungkin. Library dengan sumber khusus ARM harus mendukung semua mesin yang didukung ARM kecuali ada alasan untuk lebih spesifik.

Untuk memilih một hoặc nhiều constraint_values, sử dụng:

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

Hal ini setara dengan memilih --cpu secara tradisional:

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

Informasi selengkapnya di sini.

selects pada --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 selama migrasi.

Transisi

Transisi Starlark mengubah flag di bagian bawah 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" } menjadi return { "//command_line_option:platforms": "//:my_arm_platform" } atau menggunakan pemetaan platform untuk mendukung kedua gaya selama migrasi.

Memigrasikan kumpulan aturan

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

1. Memiliki logika aturan yang menyelesaikan toolchain dengan toolchain API. Lihat toolchain API (ctx.toolchains).

2. Opsional: tentukan flag --incompatible_enable_platforms_for_my_language sehingga logika aturan secara bergantian menyelesaikan toolchain melalui API baru atau flag lama seperti --crosstool_top selama pengujian migrasi.

3. Tentukan properti relevan yang membentuk komponen platform. Lihat Properti platform umum

4. Tentukan toolchain standar dan buat toolchain tersebut dapat diakses oleh pengguna melalui petunjuk pendaftaran aturan Anda (detail)

5. Pastikan select()s dan transisi konfigurasi mendukung platform. Ini adalah tantangan terbesar. Hal ini sangat menantang untuk project multi-bahasa (yang mungkin gagal jika semua bahasa tidak dapat membaca --platforms).

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

Properti platform umum

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

Properti yang unik untuk aturan Anda harus dideklarasikan di repo aturan Anda. Hal ini memungkinkan Anda mempertahankan kepemilikan yang jelas atas konsep spesifik yang menjadi tanggung jawab aturan Anda.

Jika aturan Anda menggunakan OS atau CPU tujuan kustom, aturan ini harus dideklarasikan di repo aturan Anda, bukan @platforms.

Pemetaan platform

Pemetaan platform adalah API sementara yang memungkinkan logika yang mendukung platform digabungkan dengan logika lama dalam build yang sama. Ini adalah alat yang sederhana dan hanya ditujukan untuk memperlancar ketidakcocokan dengan jangka waktu migrasi yang berbeda.

Pemetaan platform adalah peta platform() ke kumpulan flag lama yang sesuai atau sebaliknya. Contoh:

platforms:
  # Maps "--platforms=//platforms:ios" to "--ios_multi_cpus=x86_64 --apple_platform_type=ios".
  //platforms:ios
    --ios_multi_cpus=x86_64
    --apple_platform_type=ios

flags:
  # Maps "--ios_multi_cpus=x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --ios_multi_cpus=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 menggunakan pemetaan ini untuk menjamin semua setelan, baik 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 desain pemetaan platform untuk mengetahui detailnya.

Peninjauan API

A platform adalah kumpulan target constraint_value:

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

A constraint_value adalah properti mesin. Nilai dari "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",
)

A toolchain adalah aturan Starlark. Its atributnya mendeklarasikan alat bahasa (seperti compiler = "//mytoolchain:custom_gcc"). Penyedianya meneruskan informasi ini ke aturan yang perlu di-build dengan alat ini.

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

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

Kumpulan toolchain yang tersedia dapat didaftarkan dalam file MODULE.bazeldengan 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 diskusi tentang desain dan evolusi platform/toolchain API, hubungi bazel-dev.

Lihat juga

• Build yang Dapat Dikonfigurasi - Bagian 1
• Platform
• Toolchain
• Cookbook Platform Bazel
• Contoh platform
• Contoh toolchain C++