CocoaPods Trunk: co to jest, publikacja bibliotek przez Trunk

Czym jest CocoaPods Trunk?

CocoaPods Trunk — to infrastruktura serwerowa uruchomiona w 2015 roku do scentralizowanej publikacji bibliotek pod. Przed pojawieniem się Trunk każdy pod był rozpowszechniany przez repozytorium Git: deweloper musiał utworzyć publiczne repozytorium, dodać plik podspec i wysłać Pull Request do centralnego repozytorium CocoaPods/Specs. Takie podejście wymagało ręcznej moderacji i powodowało opóźnienia przy publikacji aktualizacji.

Trunk rozwiązał te problemy, zapewniając jednolity API do publikacji, aktualizacji i usuwania podów. Serwis obejmuje cztery kluczowe komponenty:

• Uwierzytelnianie — rejestracja z potwierdzeniem email i zarządzanie tokenami sesji. Każdy deweloper otrzymuje unikalny token, który jest powiązany z jego kontem i urządzeniami.
• Walidacja — automatyczne sprawdzanie podspec przed publikacją, w tym analiza składniowa, linting zależności i sprawdzanie zgodności platform.
• Hosting — przechowywanie metadanych i wersji podów na serwerach CocoaPods. Kod źródłowy nadal znajduje się w repozytorium Git dewelopera, a Trunk przechowuje tylko pliki podspec i linki.
• Zarządzanie dostępem — możliwość dodawania i usuwania właścicieli poda, przekazywania praw do publikacji, oznaczania podów jako przestarzałe.

Architektura Trunk jest zbudowana na stosie Ruby on Rails z bazą danych PostgreSQL. Serwis używa HTTP API z formatem JSON dla wszystkich operacji, a klient CLI pod trunk jest częścią dystrybucji CocoaPods i instaluje się razem z głównym gemem cocoapods.

Obecnie przez Trunk opublikowano ponad 100 000 podów, a łączna liczba pobrań przekracza 50 miliardów. Codziennie serwis przetwarza tysiące żądań publikacji i aktualizacji bibliotek od deweloperów z całego świata.

Rejestracja i uwierzytelnianie

Przed publikacją poda należy przejść rejestrację w Trunk. Proces składa się z jednego kroku — polecenia pod trunk register:

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

Po wykonaniu polecenia na podany email przychodzi list z linkiem do potwierdzenia. Kliknięcie linku aktywuje konto i tworzy token sesji, który jest zapisywany w systemowej przechowalni kluczy (Keychain na macOS, gnome-keyring lub odpowiednik na Linux). Token jest automatycznie używany we wszystkich kolejnych operacjach pod trunk.

Parametr --description jest opcjonalny, ale zalecany — pomaga identyfikować sesję podczas przeglądania aktywnych sesji przez pod trunk me. Jeśli pracujesz na kilku maszynach (stacja robocza, serwer CI), opis pozwoli odróżnić jedną sesję od drugiej.

Do sprawdzenia statusu uwierzytelnienia używa się polecenia:

pod trunk me

Wynik pokazuje email, nazwę, listę twoich podów (jeśli już publikowałeś) i aktywne sesje. Przykładowy wynik:

  - 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, rozwój iOS

Na serwerach CI (GitHub Actions, GitLab CI, Jenkins) uwierzytelnianie odbywa się przez token przekazany przez zmienną środowiskową COCOAPODS_TRUNK_TOKEN. Token można uzyskać poleceniem:

pod trunk me --token-only

Ten token jest zapisywany w ustawieniach CI jako zmienna sekretna i na etapie publikacji jest używany bez ponownej rejestracji. Przykład dla GitHub Actions:

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

Ważne: token daje pełny dostęp do zarządzania podami powiązanymi z kontem. Nigdy nie publikuj go w publicznych repozytoriach ani nie przekazuj osobom trzecim. W przypadku kompromitacji token można unieważnić przez pod trunk remove-session lub usunąć wszystkie sesje przez panel zarządzania na stronie CocoaPods.

Przygotowanie podspec

Plik podspec (.podspec lub .podspec.json) — to manifest biblioteki zawierający metadane, zależności, informacje o platformach i kodzie źródłowym. Trunk używa tego pliku do walidacji i rejestracji poda. Minimalny podspec do publikacji wygląda następująco:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Krótki opis biblioteki'
  s.description  = 'Szczegółowy opis z wyjaśnieniem możliwości'
  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

Kluczowe pola podspec:

• name — nazwa poda, musi być unikalna w rejestrze Trunk. Nazwy są rejestrowane na zasadzie „kto pierwszy, ten lepszy” — jeśli nazwa jest zajęta, publikacja zostanie odrzucona.
• version — wersja semantyczna w formacie MAJOR.MINOR.PATCH. Trunk nie przyjmuje ponownej publikacji tej samej wersji — należy zwiększyć numer.
• source — link do repozytorium Git i tag. Trunk nie przechowuje kodu źródłowego, więc repozytorium musi być dostępne do klonowania.
• platform — docelowa platforma (iOS, macOS, tvOS, watchOS) i minimalna wersja SDK.
• license — typ licencji. Zaleca się podanie MIT, Apache-2.0, BSD lub innej otwartej licencji.

Przed publikacją należy sprawdzić poprawność podspec za pomocą lintera:

pod lib lint MyLibrary.podspec

Linter sprawdza składnię, obecność obowiązkowych pól, poprawność ścieżek do plików i rozwiązywalność zależności. Jeśli w procesie lintingu używane są prywatne źródła (private specs), dodaje się flagę --sources. Aby pominąć pobieranie z sieci (tylko lokalne sprawdzenie), używa się flagi --local-only.

Publikacja przez pod trunk push

Główne polecenie do publikacji poda — pod trunk push. Przekazuje ono plik podspec na serwer Trunk, gdzie przechodzi pełną walidację i jest rejestrowany w publicznym rejestrze. Składnia:

pod trunk push MyLibrary.podspec

Flaga --allow-warnings zezwala na publikację w przypadku ostrzeżeń. Domyślnie wszelkie ostrzeżenia (warnings) blokują publikację. Jeśli biblioteka ma znane ostrzeżenia, które nie wpływają na funkcjonalność, można użyć tej flagi. Ważne: błędy (errors) zawsze blokują publikację, niezależnie od flag.

Flaga --synchronous sprawia, że żądanie jest synchroniczne — terminal czeka na zakończenie walidacji na serwerze. Domyślnie polecenie zwraca kontrolę natychmiast po wysłaniu, a serwer przetwarza publikację asynchronicznie. Tryb synchroniczny jest przydatny w CI/CD, gdy następny krok pipeline'u zależy od powodzenia publikacji.

Flaga --skip-import-validation pomija sprawdzanie importu biblioteki w projekcie testowym. To przyspiesza publikację, ale nie gwarantuje, że biblioteka rzeczywiście się kompiluje. Używaj tej flagi tylko jeśli jesteś pewien poprawności budowania.

Przykład publikacji z typowymi opcjami:

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

Po udanej publikacji Trunk zwraca JSON ze szczegółami:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Biblioteka staje się dostępna do instalacji przez Podfile dowolnego projektu iOS lub macOS. Zazwyczaj dane w indeksie wyszukiwania CocoaPods aktualizują się w ciągu kilku minut, ale w rzadkich przypadkach indeksacja może zająć do godziny.

Ważne ograniczenie: raz opublikowanej wersji poda nie można usunąć. Ma to na celu zapobieganie uszkodzeniom w projektach, które już używają tej wersji. Jeśli publikacja przebiegła z błędem, można opublikować następną wersję z poprawką, ale wycofanie jest niemożliwe. Wyjątkiem jest pod trunk delete, dostępny tylko dla pracowników CocoaPods i stosowany w skrajnych przypadkach (naruszenie licencji, złośliwy kod).

Zarządzanie wydaniami i dostępem

CocoaPods Trunk udostępnia kilka poleceń do administrowania opublikowanymi podami:

Dodawanie właścicieli

Aby przekazać prawa do publikacji poda innemu deweloperowi, używa się polecenia:

pod trunk add-owner MyLibrary developer@email.com

Po wykonaniu nowy właściciel otrzymuje pełny dostęp do zarządzania podem: publikacja nowych wersji, dodawanie i usuwanie innych właścicieli, oznaczanie poda jako przestarzałego. Właścicielem może być każdy zarejestrowany użytkownik Trunk — wcześniejsza rejestracja jest obowiązkowa.

Usuwanie właścicieli

Jeśli deweloper opuścił projekt lub nie powinien już mieć dostępu do poda:

pod trunk remove-owner MyLibrary developer@email.com

Usunąć właściciela może tylko obecny właściciel. Nie można usunąć ostatniego właściciela poda — najpierw trzeba dodać nowego. Zapobiega to sytuacji, w której pod pozostaje bez właściciela i staje się niczyj.

Oznaczanie poda jako przestarzałego

Jeśli biblioteka nie jest już wspierana, można ją oznaczyć jako przestarzałą (deprecated). Nie usuwa to poda z rejestru, ale dodaje ostrzeżenie użytkownikom przy instalacji:

pod trunk deprecate MyLibrary

Opcjonalnie można wskazać pod zastępczy:

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

Przy instalacji przestarzałego poda CocoaPods wyświetla ostrzeżenie w terminalu i zaleca przejście na wskazany zamiennik. Jest to poprawny sposób zakończenia wsparcia biblioteki bez naruszania budowania istniejących projektów.

Przeglądanie informacji o podzie

Informacje o podzie są dostępne przez polecenie pod trunk info:

pod trunk info MyLibrary

Polecenie pokazuje wszystkie wersje poda, daty publikacji, listę właścicieli i status (aktywny/przestarzały). Aby wyświetlić szczegóły konkretnej wersji, używa się pod spec cat MyLibrary 0.1.0.

Błędy i ich rozwiązywanie

Podczas pracy z Trunk deweloperzy często napotykają typowe błędy. Omówmy najczęstsze z nich:

Błąd uwierzytelnienia

Symptom: [!] Authentication failed. You need to register a session first.
Przyczyna: Brak lub wygaśnięcie tokena sesji. Tokeny mają ograniczony czas ważności (domyślnie 30 dni bez aktywności).
Rozwiązanie: Ponownie wykonaj pod trunk register your@email.com 'Your Name'. Jeśli używasz CI, sprawdź aktualność zmiennej COCOAPODS_TRUNK_TOKEN i w razie potrzeby wygeneruj nowy token.

Konflikt wersji

Symptom: [!] You have already pushed version 0.1.0 for MyLibrary.
Przyczyna: Próba ponownej publikacji istniejącej wersji. Trunk nie pozwala nadpisywać wersji.
Rozwiązanie: Zwiększ wersję w podspec zgodnie z semantycznym wersjonowaniem. Jeśli popełniłeś błąd w podspec, opublikuj następną wersję z poprawką.

Błąd walidacji podspec

Symptom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Przyczyna: Nieprawidłowo podana ścieżka do plików źródłowych w polu source_files.
Rozwiązanie: Sprawdź ścieżki w podspec, wykonaj pod lib lint lokalnie do usunięcia wszystkich błędów, następnie powtórz publikację. Używaj glob-patterns: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Przekroczenie czasu połączenia

Symptom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Przyczyna: Problemy z siecią lub tymczasowa niedostępność serwera Trunk.
Rozwiązanie: Sprawdź dostępność serwera: curl -I https://trunk.cocoapods.org. Jeśli serwer odpowiada, powtórz polecenie za kilka minut. Możliwe, że twoje IP jest zablokowane — spróbuj z innego połączenia lub przez VPN.

Brak dostępu do poda

Symptom: [!] You do not have permission to push to MyLibrary.
Przyczyna: Nie jesteś właścicielem poda. Dzieje się tak, jeśli ktoś już zarejestrował pod o tej nazwie.
Rozwiązanie: Skontaktuj się z obecnym właścicielem poda (można go znaleźć przez pod trunk info MyLibrary) i poproś o dodanie cię przez pod trunk add-owner. Jeśli nazwa poda jest zajęta, rozważ alternatywną nazwę.