CocoaPods Trunk: nedir, Trunk ile kütüphane yayınlama

CocoaPods Trunk nedir?

CocoaPods Trunk, pod kütüphanelerinin merkezi olarak yayınlanması için 2015 yılında başlatılan bir sunucu altyapısıdır. Trunk'tan önce, her pod bir Git deposu aracılığıyla dağıtılırdı: geliştiricinin herkese açık bir depo oluşturması, podspec dosyası eklemesi ve merkezi depo CocoaPods/Specs'e Pull Request göndermesi gerekiyordu. Bu yaklaşım manuel moderasyon gerektiriyor ve güncellemelerin yayınlanmasında gecikmelere neden oluyordu.

Trunk, yayınlama, güncelleme ve pod yönetimi için birleşik bir API sağlayarak bu sorunları çözdü. Hizmet dört temel bileşen içerir:

• Kimlik doğrulama — e-posta onayı ile kayıt ve oturum token yönetimi. Her geliştirici, hesabına ve cihazlarına bağlı benzersiz bir token alır.
• Doğrulama — sözdizimi analizi, bağımlılık linting'i ve platform uyumluluk kontrolü dahil olmak üzere yayın öncesi podspec'in otomatik olarak doğrulanması.
• Barındırma — CocoaPods sunucularında pod meta verilerinin ve sürümlerinin depolanması. Kaynak kodu geliştiricinin Git deposunda kalırken, Trunk yalnızca podspec dosyalarını ve bağlantıları saklar.
• Erişim yönetimi — pod sahiplerini ekleme ve kaldırma, yayınlama haklarını devretme, pod'ları kullanım dışı olarak işaretleme.

Trunk'ın mimarisi, PostgreSQL veritabanı ile Ruby on Rails yığını üzerine inşa edilmiştir. Hizmet, tüm işlemler için JSON formatında HTTP API kullanır ve CLI istemcisi pod trunk, ana cocoapods gem'i ile birlikte kurulan CocoaPods dağıtımının bir parçasıdır.

Bugüne kadar Trunk aracılığıyla 100.000'den fazla pod yayınlandı ve toplam indirme sayısı 50 milyarı aştı. Hizmet, dünyanın dört bir yanından geliştiricilerden gelen binlerce yayınlama ve güncelleme talebini günlük olarak işler.

Kayıt ve kimlik doğrulama

Bir pod yayınlamadan önce Trunk'a kaydolmanız gerekir. Süreç tek bir adımdan oluşur — pod trunk register komutu:

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

Komut çalıştırıldıktan sonra, belirtilen e-postaya bir onay bağlantısı gönderilir. Bağlantıya tıklandığında hesap etkinleştirilir ve sistem anahtar zincirinde (macOS'te Keychain, Linux'ta gnome-keyring veya benzeri) saklanan bir oturum token'ı oluşturulur. Token, sonraki tüm pod trunk işlemlerinde otomatik olarak kullanılır.

--description parametresi isteğe bağlıdır ancak önerilir — pod trunk me aracılığıyla aktif oturumları görüntülerken oturumu tanımlamaya yardımcı olur. Birden fazla makineden (iş istasyonu, CI sunucusu) çalışıyorsanız, açıklama bir oturumu diğerinden ayırt etmenizi sağlar.

Kimlik doğrulama durumunu kontrol etmek için komutu kullanın:

pod trunk me

Çıktı, e-posta, ad, pod listeniz (daha önce yayınladıysanız) ve aktif oturumları gösterir. Örnek sonuç:

  - 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, iOS geliştirme

CI sunucularında (GitHub Actions, GitLab CI, Jenkins), kimlik doğrulama COCOAPODS_TRUNK_TOKEN ortam değişkeni aracılığıyla iletilen bir token ile yapılır. Token şu komutla alınabilir:

pod trunk me --token-only

Bu token, CI ayarlarında gizli bir değişken olarak saklanır ve tekrar kayıt gerektirmeden yayınlama adımında kullanılır. GitHub Actions için örnek:

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

Önemli: token, hesaba bağlı pod'ların yönetimine tam erişim sağlar. Bunu asla herkese açık depolarda yayınlamayın veya üçüncü taraflarla paylaşmayın. Tehlikeye girerse, token pod trunk remove-session aracılığıyla veya CocoaPods web sitesi kontrol panelinden tüm oturumlar silinerek iptal edilebilir.

Podspec hazırlama

Podspec dosyası (.podspec veya .podspec.json), meta verileri, bağımlılıkları, platform bilgilerini ve kaynak kodu ayrıntılarını içeren kütüphane manifestosudur. Trunk bu dosyayı doğrulama ve pod kaydı için kullanır. Yayınlama için minimum bir podspec şöyle görünür:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Kütüphanenin kısa açıklaması'
  s.description  = 'Özelliklerin açıklamasıyla birlikte ayrıntılı açıklama'
  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

Podspec'in temel alanları:

• name — pod adı, Trunk kayıt defterinde benzersiz olmalıdır. İsimler ilk gelen alır esasına göre kaydedilir — isim alınmışsa yayınlama reddedilir.
• version — MAJOR.MINOR.PATCH formatında anlamsal sürüm. Trunk aynı sürümün yeniden yayınlanmasını kabul etmez — numara artırılmalıdır.
• source — Git deposu bağlantısı ve etiketi. Trunk kaynak kodunu saklamaz, bu nedenle depo klonlama için erişilebilir olmalıdır.
• platform — hedef platform (iOS, macOS, tvOS, watchOS) ve minimum SDK sürümü.
• license — lisans türü. MIT, Apache-2.0, BSD veya başka bir açık kaynak lisansı belirtilmesi önerilir.

Yayınlamadan önce, podspec'i linter ile doğrulayın:

pod lib lint MyLibrary.podspec

Linter, sözdizimini, zorunlu alanları, dosya yollarının doğruluğunu ve bağımlılıkların çözülebilirliğini kontrol eder. Linting işlemi sırasında özel kaynaklar kullanılıyorsa, --sources bayrağı eklenir. Ağ indirmelerini atlamak için (yalnızca yerel kontrol), --local-only bayrağı kullanılır.

pod trunk push ile yayınlama

Bir pod yayınlamak için ana komut pod trunk push'tur. Podspec dosyasını Trunk sunucusuna gönderir, burada tam doğrulamadan geçer ve genel kayıt defterine kaydedilir. Sözdizimi:

pod trunk push MyLibrary.podspec

--allow-warnings bayrağı, uyarılar olsa bile yayınlamaya izin verir. Varsayılan olarak, herhangi bir uyarı yayınlamayı engeller. Kütüphanenizde işlevselliği etkilemeyen bilinen uyarılar varsa bu bayrağı kullanabilirsiniz. Önemli: hatalar, bayraklardan bağımsız olarak her zaman yayınlamayı engeller.

--synchronous bayrağı isteği senkron hale getirir — terminal, sunucu tarafı doğrulamasının tamamlanmasını bekler. Varsayılan olarak, komut gönderimden hemen sonra kontrolü geri verir ve sunucu yayınlamayı asenkron olarak işler. Senkron mod, pipeline'ın sonraki adımının başarılı yayınlamaya bağlı olduğu CI/CD'de kullanışlıdır.

--skip-import-validation bayrağı, kütüphanenin test projesine aktarımının kontrolünü atlar. Bu yayınlamayı hızlandırır ancak kütüphanenin gerçekten derlendiğini garanti etmez. Bu bayrağı yalnızca derlemenin doğruluğundan eminseniz kullanın.

Tipik seçeneklerle yayınlama örneği:

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

Başarılı yayınlamadan sonra Trunk, ayrıntılarla birlikte JSON döndürür:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Kütüphane, herhangi bir iOS veya macOS projesinde Podfile aracılığıyla kurulum için kullanılabilir hale gelir. Normalde, CocoaPods arama dizini birkaç dakika içinde güncellenir, ancak nadir durumlarda indeksleme bir saate kadar sürebilir.

Önemli sınırlama: bir kez yayınlanmış pod sürümü silinemez. Bu, bu sürümü zaten kullanan projelerin bozulmasını önlemek içindir. Yayınlama hatalıysa, düzeltme ile bir sonraki sürümü yayınlayabilirsiniz, ancak geri alma mümkün değildir. İstisna, yalnızca CocoaPods personeli tarafından kullanılabilen ve aşırı durumlarda (lisans ihlali, kötü amaçlı kod) uygulanan pod trunk delete'tir.

Sürüm ve erişim yönetimi

CocoaPods Trunk, yayınlanmış pod'ları yönetmek için çeşitli komutlar sağlar:

Sahip ekleme

Bir pod'un yayınlama haklarını başka bir geliştiriciye devretmek için komutu kullanın:

pod trunk add-owner MyLibrary developer@email.com

Yürütmeden sonra, yeni sahip pod yönetimine tam erişim elde eder: yeni sürümler yayınlama, diğer sahipleri ekleme ve kaldırma, pod'u kullanım dışı olarak işaretleme. Kayıtlı herhangi bir Trunk kullanıcısı sahip olabilir — ön kayıt zorunludur.

Sahip kaldırma

Bir geliştirici projeden ayrıldıysa veya pod'a artık erişimi olmamalıysa:

pod trunk remove-owner MyLibrary developer@email.com

Yalnızca mevcut bir sahip, bir sahibi kaldırabilir. Bir pod'un son sahibi kaldırılamaz — önce yeni bir tane eklenmelidir. Bu, bir pod'un sahipsiz kalmasını ve terk edilmesini önler.

Pod'u kullanım dışı olarak işaretleme

Kütüphane artık desteklenmiyorsa, onu kullanım dışı (deprecated) olarak işaretleyebilirsiniz. Bu, pod'u kayıt defterinden kaldırmaz, ancak kurulum sırasında kullanıcılara bir uyarı ekler:

pod trunk deprecate MyLibrary

İsteğe bağlı olarak, bir yedek pod belirtebilirsiniz:

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

Kullanım dışı bir pod kurulurken, CocoaPods terminalde bir uyarı görüntüler ve belirtilen yedeğe geçilmesini önerir. Bu, mevcut proje derlemelerini bozmadan bir kütüphanenin desteğini sonlandırmanın doğru yoludur.

Pod bilgilerini görüntüleme

Pod bilgileri pod trunk info komutuyla kullanılabilir:

pod trunk info MyLibrary

Komut, tüm pod sürümlerini, yayın tarihlerini, sahip listesini ve durumu (aktif/kullanım dışı) gösterir. Belirli bir sürümün ayrıntılarını görmek için pod spec cat MyLibrary 0.1.0 kullanın.

Hatalar ve çözümleri

Trunk ile çalışırken, geliştiriciler sıklıkla tipik hatalarla karşılaşır. En yaygın olanları inceleyelim:

Kimlik doğrulama hatası

Belirti: [!] Authentication failed. You need to register a session first.
Neden: Oturum token'ı eksik veya süresi dolmuş. Token'ların sınırlı bir geçerlilik süresi vardır (varsayılan olarak etkinlik olmadan 30 gün).
Çözüm: pod trunk register your@email.com 'Your Name' komutunu yeniden çalıştırın. CI kullanıyorsanız, COCOAPODS_TRUNK_TOKEN ortam değişkeninin güncel olduğunu kontrol edin ve gerekirse yeni bir token oluşturun.

Sürüm çakışması

Belirti: [!] You have already pushed version 0.1.0 for MyLibrary.
Neden: Mevcut bir sürümü yeniden yayınlama girişimi. Trunk, sürümlerin üzerine yazmaya izin vermez.
Çözüm: Anlamsal sürümlemeye göre podspec'teki sürümü artırın. Podspec'te hata yaptıysanız, düzeltme ile bir sonraki sürümü yayınlayın.

Podspec doğrulama hatası

Belirti: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Neden: source_files alanında kaynak dosyalara giden yol yanlış.
Çözüm: Podspec'teki yolları kontrol edin, tüm hatalar çözülene kadar yerel olarak pod lib lint çalıştırın, ardından yayınlamayı tekrarlayın. Glob kalıpları kullanın: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Bağlantı zaman aşımı

Belirti: [!] Connection to trunk.cocoapods.org failed. Timeout.
Neden: Ağ sorunları veya Trunk sunucusunun geçici olarak kullanılamaması.
Çözüm: Sunucu kullanılabilirliğini kontrol edin: curl -I https://trunk.cocoapods.org. Sunucu yanıt veriyorsa, birkaç dakika sonra komutu tekrarlayın. IP'niz engellenmiş olabilir — başka bir bağlantıdan veya VPN üzerinden deneyin.

Pod'a erişim yok

Belirti: [!] You do not have permission to push to MyLibrary.
Neden: Pod'un sahibi değilsiniz. Bu, birisi zaten bu adla bir pod kaydettiyse olur.
Çözüm: Mevcut pod sahibiyle iletişime geçin (pod trunk info MyLibrary aracılığıyla öğrenin) ve sizi pod trunk add-owner aracılığıyla eklemesini isteyin. Pod adı alınmışsa, alternatif bir ad düşünün.