CocoaPods Trunk: apa itu, publikasi pustaka melalui Trunk

Apa itu CocoaPods Trunk?

CocoaPods Trunk — adalah infrastruktur server yang diluncurkan pada tahun 2015 untuk publikasi terpusat pustaka pod. Sebelum hadirnya Trunk, setiap pod didistribusikan melalui repositori Git: pengembang harus membuat repositori publik, menambahkan file podspec, dan mengirim Pull Request ke repositori pusat CocoaPods/Specs. Pendekatan ini memerlukan moderasi manual dan menyebabkan keterlambatan dalam publikasi pembaruan.

Trunk memecahkan masalah ini dengan menyediakan API terpadu untuk publikasi, pembaruan, dan penghapusan pod. Layanan ini mencakup empat komponen utama:

• Autentikasi — registrasi dengan konfirmasi email dan manajemen token sesi. Setiap pengembang mendapatkan token unik yang terikat pada akun dan perangkatnya.
• Validasi — pemeriksaan otomatis podspec sebelum publikasi, termasuk analisis sintaksis, linting dependensi, dan pemeriksaan kompatibilitas platform.
• Hosting — penyimpanan metadata dan versi pod di server CocoaPods. Kode sumber tetap berada di repositori Git pengembang, sementara Trunk hanya menyimpan file podspec dan tautan.
• Manajemen akses — kemampuan untuk menambah dan menghapus pemilik pod, mentransfer hak publikasi, menandai pod sebagai usang.

Arsitektur Trunk dibangun di atas stack Ruby on Rails dengan database PostgreSQL. Layanan ini menggunakan HTTP API dengan format JSON untuk semua operasi, dan klien CLI pod trunk adalah bagian dari distribusi CocoaPods dan diinstal bersama gem utama cocoapods.

Saat ini, lebih dari 100.000 pod telah dipublikasikan melalui Trunk, dengan total unduhan melebihi 50 miliar. Setiap hari, layanan ini memproses ribuan permintaan publikasi dan pembaruan pustaka dari pengembang di seluruh dunia.

Registrasi dan autentikasi

Sebelum mempublikasikan pod, Anda harus mendaftar di Trunk. Prosesnya terdiri dari satu langkah — perintah pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, pengembangan iOS'

Setelah perintah dijalankan, email dengan tautan konfirmasi dikirim ke alamat yang ditentukan. Mengklik tautan akan mengaktifkan akun dan membuat token sesi yang disimpan di keychain sistem (Keychain di macOS, gnome-keyring atau yang setara di Linux). Token digunakan secara otomatis di semua operasi pod trunk berikutnya.

Parameter --description bersifat opsional tetapi disarankan — membantu mengidentifikasi sesi saat melihat sesi aktif melalui pod trunk me. Jika Anda bekerja di beberapa mesin (stasiun kerja, server CI), deskripsi memungkinkan Anda membedakan satu sesi dari sesi lainnya.

Untuk memeriksa status autentikasi, gunakan perintah berikut:

pod trunk me

Keluaran menunjukkan email, nama, daftar pod Anda (jika sudah pernah mempublikasikan) dan sesi aktif. Contoh hasil:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, pengembangan iOS

Di server CI (GitHub Actions, GitLab CI, Jenkins), autentikasi dilakukan melalui token yang diteruskan melalui variabel lingkungan COCOAPODS_TRUNK_TOKEN. Token dapat diperoleh dengan perintah:

pod trunk me --token-only

Token ini disimpan di pengaturan CI sebagai variabel rahasia dan digunakan pada tahap publikasi tanpa registrasi ulang. Contoh untuk GitHub Actions:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

Penting: token memberikan akses penuh ke manajemen pod yang terikat pada akun. Jangan pernah mempublikasikannya di repositori publik atau memberikannya kepada pihak ketiga. Jika token dikompromikan, token dapat dicabut melalui pod trunk remove-session atau semua sesi dapat dihapus melalui panel manajemen di situs web CocoaPods.

Persiapan podspec

File podspec (.podspec atau .podspec.json) — adalah manifes pustaka yang berisi metadata, dependensi, informasi tentang platform, dan kode sumber. Trunk menggunakan file ini untuk validasi dan registrasi pod. Podspec minimal untuk publikasi terlihat seperti ini:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Deskripsi singkat pustaka'
  s.description  = 'Deskripsi terperinci dengan penjelasan kemampuan'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

Bidang utama podspec:

• name — nama pod, harus unik di registry Trunk. Nama didaftarkan berdasarkan prinsip 'pertama datang, pertama dilayani' — jika nama sudah digunakan, publikasi akan ditolak.
• version — versi semantik dalam format MAJOR.MINOR.PATCH. Trunk tidak menerima publikasi ulang versi yang sama — Anda harus menaikkan nomornya.
• source — tautan ke repositori Git dan tag. Trunk tidak menyimpan kode sumber, jadi repositori harus dapat diakses untuk cloning.
• platform — platform target (iOS, macOS, tvOS, watchOS) dan versi SDK minimum.
• license — jenis lisensi. Disarankan untuk mencantumkan MIT, Apache-2.0, BSD atau lisensi terbuka lainnya.

Sebelum publikasi, podspec harus diperiksa kebenarannya menggunakan linter:

pod lib lint MyLibrary.podspec

Linter memeriksa sintaksis, keberadaan bidang wajib, kebenaran jalur file, dan keterpecahan dependensi. Jika dalam proses linting menggunakan sumber privat (private specs), tambahkan flag --sources. Untuk melewati unduhan jaringan (hanya pemeriksaan lokal), gunakan flag --local-only.

Publikasi melalui pod trunk push

Perintah utama untuk mempublikasikan pod — pod trunk push. Perintah ini mengirim file podspec ke server Trunk, di mana ia menjalani validasi penuh dan didaftarkan di registry publik. Sintaksis:

pod trunk push MyLibrary.podspec

Flag --allow-warnings mengizinkan publikasi jika ada peringatan. Secara default, peringatan apa pun (warnings) memblokir publikasi. Jika pustaka memiliki peringatan yang diketahui yang tidak memengaruhi fungsionalitas, Anda dapat menggunakan flag ini. Penting: kesalahan (errors) selalu memblokir publikasi, terlepas dari flag.

Flag --synchronous membuat permintaan sinkron — terminal menunggu validasi selesai di server. Secara default, perintah mengembalikan kontrol segera setelah pengiriman, dan server memproses publikasi secara asinkron. Mode sinkron berguna di CI/CD ketika langkah pipeline berikutnya bergantung pada keberhasilan publikasi.

Flag --skip-import-validation melewatkan pemeriksaan impor pustaka ke proyek pengujian. Ini mempercepat publikasi, tetapi tidak menjamin bahwa pustaka benar-benar dikompilasi. Gunakan flag ini hanya jika Anda yakin dengan kebenaran build.

Contoh publikasi dengan opsi tipikal:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

Setelah publikasi berhasil, Trunk mengembalikan JSON dengan detail:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

Pustaka tersedia untuk instalasi melalui Podfile proyek iOS atau macOS mana pun. Biasanya data di indeks pencarian CocoaPods diperbarui dalam beberapa menit, tetapi dalam kasus yang jarang terjadi, indeksasi bisa memakan waktu hingga satu jam.

Batasan penting: versi pod yang telah dipublikasikan tidak dapat dihapus. Ini dilakukan untuk mencegah kerusakan pada proyek yang sudah menggunakan versi tersebut. Jika publikasi berakhir dengan kesalahan, Anda dapat mempublikasikan versi berikutnya dengan koreksi, tetapi pengembalian tidak dimungkinkan. Pengecualian — pod trunk delete, hanya tersedia untuk karyawan CocoaPods dan diterapkan dalam kasus ekstrem (pelanggaran lisensi, kode berbahaya).

Manajemen rilis dan akses

CocoaPods Trunk menyediakan beberapa perintah untuk mengelola pod yang dipublikasikan:

Menambahkan pemilik

Untuk mentransfer hak publikasi pod ke pengembang lain, gunakan perintah berikut:

pod trunk add-owner MyLibrary developer@email.com

Setelah dijalankan, pemilik baru mendapatkan akses penuh ke manajemen pod: publikasi versi baru, menambah dan menghapus pemilik lain, menandai pod sebagai usang. Pemilik dapat berupa pengguna Trunk mana pun yang terdaftar — registrasi awal wajib dilakukan.

Menghapus pemilik

Jika pengembang meninggalkan proyek atau tidak lagi memiliki akses ke pod:

pod trunk remove-owner MyLibrary developer@email.com

Pemilik hanya dapat dihapus oleh pemilik saat ini. Pemilik terakhir pod tidak dapat dihapus — pertama-tama Anda harus menambahkan yang baru. Ini mencegah situasi di mana pod menjadi tidak memiliki pemilik.

Menandai pod sebagai usang

Jika pustaka tidak lagi didukung, pustaka dapat ditandai sebagai usang (deprecated). Ini tidak menghapus pod dari registry, tetapi menambahkan peringatan kepada pengguna saat instalasi:

pod trunk deprecate MyLibrary

Secara opsional, pod pengganti dapat ditentukan:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

Saat menginstal pod usang, CocoaPods menampilkan peringatan di terminal dan merekomendasikan untuk beralih ke pengganti yang ditentukan. Ini adalah cara yang benar untuk mengakhiri dukungan pustaka tanpa mengganggu build proyek yang ada.

Melihat informasi pod

Informasi tentang pod tersedia melalui perintah pod trunk info:

pod trunk info MyLibrary

Perintah ini menampilkan semua versi pod, tanggal publikasi, daftar pemilik, dan status (aktif/usang). Untuk melihat detail versi tertentu, gunakan pod spec cat MyLibrary 0.1.0.

Kesalahan dan solusinya

Saat bekerja dengan Trunk, pengembang sering menghadapi kesalahan umum. Mari kita bahas yang paling sering terjadi:

Kesalahan autentikasi

Gejala: [!] Authentication failed. You need to register a session first.
Penyebab: Token sesi tidak ada atau kedaluwarsa. Token memiliki masa berlaku terbatas (secara default 30 hari tanpa aktivitas).
Solusi: Jalankan ulang pod trunk register your@email.com 'Your Name'. Jika menggunakan CI, periksa keaktualan variabel COCOAPODS_TRUNK_TOKEN dan buat token baru jika perlu.

Konflik versi

Gejala: [!] You have already pushed version 0.1.0 for MyLibrary.
Penyebab: Upaya mempublikasikan ulang versi yang sudah ada. Trunk tidak mengizinkan penimpaan versi.
Solusi: Naikkan versi di podspec sesuai dengan versioning semantik. Jika Anda membuat kesalahan di podspec, publikasikan versi berikutnya dengan koreksi.

Kesalahan validasi podspec

Gejala: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Penyebab: Jalur ke file sumber di bidang source_files salah ditentukan.
Solusi: Periksa jalur di podspec, jalankan pod lib lint secara lokal sampai semua kesalahan teratasi, lalu ulangi publikasi. Gunakan pola glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Waktu habis koneksi

Gejala: [!] Connection to trunk.cocoapods.org failed. Timeout.
Penyebab: Masalah jaringan atau server Trunk tidak tersedia sementara.
Solusi: Periksa ketersediaan server: curl -I https://trunk.cocoapods.org. Jika server merespons, ulangi perintah dalam beberapa menit. Mungkin IP Anda diblokir — coba dari koneksi lain atau melalui VPN.

Tidak ada akses ke pod

Gejala: [!] You do not have permission to push to MyLibrary.
Penyebab: Anda bukan pemilik pod. Ini terjadi jika seseorang sudah mendaftarkan pod dengan nama tersebut.
Solusi: Hubungi pemilik pod saat ini (dapat diketahui melalui pod trunk info MyLibrary) dan minta untuk menambahkan Anda melalui pod trunk add-owner. Jika nama pod sudah digunakan, pertimbangkan nama alternatif.