Bermigrasi dari Xcode ke Bazel

Laporkan masalah Lihat sumber Per Malam · 7,4 kami. 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Halaman ini menjelaskan cara mem-build atau menguji project Xcode dengan Bazel. Panduan ini menjelaskan perbedaan antara Xcode dan Bazel, serta memberikan langkah-langkah untuk mengonversi project Xcode menjadi project Bazel. Artikel ini juga memberikan solusi pemecahan masalah untuk mengatasi error umum.

Perbedaan antara Xcode dan Bazel

• Bazel mengharuskan Anda menentukan setiap target build dan dependensinya secara eksplisit, ditambah setelan build yang sesuai melalui aturan build.

• Bazel mewajibkan semua file yang menjadi dependensi project untuk ada dalam direktori ruang kerja atau ditentukan sebagai impor dalam file WORKSPACE.

• Saat membangun project Xcode dengan Bazel, file BUILD akan menjadi yang tepercaya. Jika mengerjakan project di Xcode, Anda harus membuat versi baru project Xcode yang cocok dengan file BUILD menggunakan rules_xcodeproj setiap kali Anda mengupdate file BUILD. Perubahan tertentu pada file BUILD seperti menambahkan dependensi ke target tidak memerlukan pembuatan ulang yang dapat mempercepat pengembangan. Jika Anda tidak menggunakan Xcode, perintah bazel build dan bazel test akan memberikan kemampuan build dan pengujian dengan batasan tertentu yang akan dijelaskan nanti dalam panduan ini.

Sebelum memulai

Sebelum memulai, lakukan hal berikut:

1. Instal Bazel jika Anda belum melakukannya.

2. Jika Anda tidak terbiasa dengan Bazel dan konsepnya, selesaikan tutorial aplikasi iOS. Anda harus memahami ruang kerja Bazel, termasuk file WORKSPACE dan BUILD, serta konsep target, aturan build, dan paket Bazel.

3. Menganalisis dan memahami dependensi project.

Menganalisis dependensi project

Tidak seperti Xcode, Bazel mengharuskan Anda untuk secara eksplisit mendeklarasikan semua dependensi untuk setiap target dalam file BUILD.

Untuk informasi selengkapnya tentang dependensi eksternal, lihat Menggunakan dependensi eksternal.

Mem-build atau menguji project Xcode dengan Bazel

Untuk mem-build atau menguji project Xcode dengan Bazel, lakukan hal berikut:

1. Membuat file WORKSPACE

2. (Eksperimental) Mengintegrasikan dependensi SwiftPM

3. Buat file BUILD:

   a. Menambahkan target aplikasi

   b. (Opsional) Menambahkan target pengujian

   c. Menambahkan target library

4. (Opsional) Membuat build menjadi lebih terperinci

5. Menjalankan build

6. Membuat project Xcode dengan rules_xcodeproj

Langkah 1: Buat file WORKSPACE

Buat file WORKSPACE di direktori baru. Direktori ini menjadi root workspace Bazel. Jika proyek tidak menggunakan dependensi eksternal, file ini dapat kosong. Jika project bergantung pada file atau paket yang tidak ada di salah satu direktori project, tentukan dependensi eksternal ini dalam file WORKSPACE.

Catatan: Tempatkan kode sumber project dalam hierarki direktori yang berisi WORKSPACE.

Langkah 2: (Eksperimental) Integrasikan dependensi SwiftPM

Untuk mengintegrasikan dependensi SwiftPM ke dalam ruang kerja Bazel dengan swift_bazel, Anda harus mengonversinya menjadi paket Bazel seperti yang dijelaskan dalam tutorial berikut.

Catatan: Dukungan SwiftPM adalah proses manual dengan banyak variabel. Integrasi SwiftPM dengan Bazel belum diverifikasi sepenuhnya dan tidak didukung secara resmi.

Langkah 3: Buat file BUILD

Setelah menentukan ruang kerja dan dependensi eksternal, Anda harus membuat file BUILD yang memberi tahu Bazel cara menyusun project. Berkreasi file BUILD di root ruang kerja Bazel dan konfigurasikan untuk melakukan pembuatan awal project sebagai berikut:

• Langkah 3a: Tambahkan target aplikasi
• Langkah 3b: (Opsional) Tambahkan target pengujian
• Langkah 3c: Tambahkan target library

Tips: Untuk mempelajari paket dan konsep Bazel lainnya lebih lanjut, lihat Ruang kerja, paket, dan target.

Langkah 3a: Tambahkan target aplikasi

Menambahkan macos_application atau ios_application target aturan. Target ini masing-masing mem-build app bundle macOS atau iOS. Pada target, tentukan minimal hal berikut:

• bundle_id - ID paket (jalur Reverse-DNS diikuti nama aplikasi) biner.

• provisioning_profile - profil penyediaan dari Apple Developer Anda (jika membuat aplikasi untuk perangkat iOS).

• families (khusus iOS) - apakah akan mem-build aplikasi untuk iPhone, iPad, atau keduanya.

• infoplists - daftar file .plist untuk digabungkan ke dalam file Info.plist akhir.

• minimum_os_version - versi minimum macOS atau iOS yang didukung aplikasi. Hal ini memastikan Bazel membangun aplikasi dengan level API yang benar.

Langkah 3b: (Opsional) Tambahkan target pengujian

Aturan build Apple Bazel mendukung pengujian unit berbasis library yang berjalan di iOS dan macOS, serta pengujian berbasis aplikasi di macOS. Untuk pengujian berbasis aplikasi pada iOS atau pengujian UI pada khusus, Bazel akan membangun output pengujian tetapi pengujian harus berjalan dalam Xcode melalui project yang dibuat dengan rules_xcodeproj. Tambahkan target pengujian sebagai berikut:

• macos_unit_test untuk menjalankan pengujian unit berbasis library dan berbasis aplikasi di macOS.

• ios_unit_test untuk menjalankan pengujian unit berbasis library di iOS. Untuk pengujian yang memerlukan simulator iOS, Bazel akan mem-build output pengujian, tetapi tidak menjalankan pengujian. Anda harus membuat project Xcode dengan rules_xcodeproj dan menjalankan pengujian dari dalam Xcode.

• ios_ui_test untuk mem-build output yang diperlukan untuk menjalankan pengujian antarmuka pengguna di simulator iOS menggunakan Xcode. Anda harus membuat project Xcode dengan rules_xcodeproj dan menjalankan pengujian dari dalam Xcode. Bazel tidak dapat menjalankan pengujian UI secara native.

Minimal, tentukan nilai untuk atribut minimum_os_version. Meskipun atribut paket lainnya, seperti bundle_identifier dan infoplists, memiliki nilai default yang paling umum digunakan, pastikan bahwa default tersebut kompatibel dengan project dan sesuaikan jika diperlukan. Untuk pengujian yang memerlukan simulator iOS, tentukan juga nama target ios_application sebagai nilai atribut test_host.

Langkah 3c: Tambahkan target library

Menambahkan objc_library target untuk setiap library Objective-C dan swift_library target untuk setiap library Swift yang menjadi dependensi aplikasi dan/atau pengujian.

Tambahkan target library sebagai berikut:

• Tambahkan target library aplikasi sebagai dependensi ke target aplikasi.

• Tambahkan target library pengujian sebagai dependensi ke target pengujian.

• Cantumkan sumber implementasi dalam atribut srcs.

• Cantumkan header dalam atribut hdrs.

Catatan: Anda dapat menggunakan fungsi glob untuk menyertakan semua sumber dan/atau header dari jenis tertentu. Gunakan dengan hati-hati karena mungkin menyertakan file yang tidak Anda inginkan untuk dibuat oleh Bazel.

Anda dapat menelusuri contoh yang ada untuk berbagai jenis aplikasi secara langsung di direktori contoh aturan_apple. Contoh:

• Target aplikasi macOS

• Target aplikasi iOS

• Aplikasi multiplatform (macOS, iOS, watchOS, tvOS)

Untuk mengetahui informasi selengkapnya tentang aturan build, lihat Aturan Apple untuk Bazel.

Pada tahap ini, sebaiknya uji build:

bazel build //:<application_target>

Langkah 4: (Opsional) Memerinci build

Jika proyek tersebut besar, atau seiring pertumbuhannya, pertimbangkan untuk membaginya menjadi beberapa Paket Bazel. Peningkatan perincian ini memberikan:

• Peningkatan inkrementalitas build,

• Peningkatan paralelisasi tugas build,

• Pengelolaan yang lebih baik untuk pengguna di masa depan,

• Kontrol yang lebih baik atas visibilitas kode sumber di seluruh target dan paket. Ini mencegah masalah seperti library yang berisi detail implementasi yang bocor menjadi API publik.

Tips untuk membuat project menjadi terperinci:

• Masukkan setiap library dalam paket Bazel-nya sendiri. Mulailah dengan yang memerlukan dependensi paling sedikit dan lanjutkan ke hierarki dependensi.

• Saat Anda menambahkan file BUILD dan menentukan target, tambahkan target baru ini ke atribut deps target yang bergantung padanya.

• Fungsi glob() tidak melewati batas paket, sehingga jumlah paket meningkatkan jumlah file yang cocok dengan glob() akan menyusut.

• Saat menambahkan file BUILD ke direktori main, tambahkan juga file BUILD ke direktori test yang sesuai.

• Terapkan batas visibilitas yang sehat di seluruh paket.

• Buat project setelah setiap perubahan besar pada file BUILD dan perbaiki {i>build error<i} saat Anda menemuinya.

Langkah 5: Jalankan build

Jalankan build yang dimigrasikan sepenuhnya untuk memastikan build selesai tanpa error atau peringatan. Jalankan setiap aplikasi dan target pengujian satu per satu untuk lebih mudah menemukan sumber error yang terjadi.

Contoh:

bazel build //:my-target

Langkah 6: Buat project Xcode dengan rules_xcodeproj

Saat mem-build dengan Bazel, file WORKSPACE dan BUILD menjadi sumber kebenaran tentang build. Agar Xcode mengetahui hal ini, Anda harus membuat Project Xcode yang kompatibel dengan Bazel menggunakan rules_xcodeproj.

Pemecahan masalah

Error Bazel dapat terjadi jika tidak sinkron dengan versi Xcode yang dipilih, seperti saat Anda menerapkan update. Berikut adalah beberapa hal yang perlu Anda coba jika mengalami kesalahan dengan Xcode, misalnya "Versi Xcode harus ditentukan untuk menggunakan Apple CROSSTOOL".

• Jalankan Xcode secara manual dan setujui persyaratan dan ketentuan apa pun.

• Gunakan Xcode select untuk menunjukkan versi yang benar, menyetujui lisensi, dan menghapus status Bazel.

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  sudo xcodebuild -license
  bazel sync --configure

• Jika tidak berhasil, Anda juga dapat mencoba menjalankan bazel clean --expunge.

Catatan: Jika telah menyimpan Xcode ke jalur lain, Anda dapat menggunakan xcode-select -s untuk mengarah ke jalur tersebut.