CocoaPods Trunk: co to je, publikace knihoven přes Trunk

Co je CocoaPods Trunk?

CocoaPods Trunk — je serverová infrastruktura spuštěná v roce 2015 pro centralizovanou publikaci pod knihoven. Před příchodem Trunku byl každý pod distribuován přes Git repozitář: vývojář musel vytvořit veřejný repozitář, přidat podspec soubor a odeslat Pull Request do centrálního repozitáře CocoaPods/Specs. Tento přístup vyžadoval ruční moderování a způsoboval zpoždění při publikaci aktualizací.

Trunk tyto problémy vyřešil poskytnutím jednotného API pro publikaci, aktualizaci a mazání podů. Služba zahrnuje čtyři klíčové komponenty:

• Autentizace — registrace s potvrzením e-mailem a správa tokenů relací. Každý vývojář obdrží jedinečný token, který je vázán na jeho účet a zařízení.
• Validace — automatická kontrola podspec před publikací, včetně syntaktické analýzy, lintingu závislostí a kontroly kompatibility platforem.
• Hosting — ukládání metadat a verzí podů na serverech CocoaPods. Zdrojový kód zůstává v Git repozitáři vývojáře, Trunk ukládá pouze podspec soubory a odkazy.
• Správa přístupu — možnost přidávat a odebírat vlastníky podů, převádět práva k publikaci, označovat pody jako zastaralé.

Architektura Trunku je postavena na stacku Ruby on Rails s databází PostgreSQL. Služba používá HTTP API s JSON formátem pro všechny operace a CLI klient pod trunk je součástí distribuce CocoaPods a instaluje se spolu s hlavním gemem cocoapods.

V současné době bylo přes Trunk publikováno více než 100 000 podů a celkový počet stažení přesahuje 50 miliard. Služba denně zpracovává tisíce požadavků na publikaci a aktualizaci knihoven od vývojářů z celého světa.

Registrace a autentizace

Před publikací podu je nutné se zaregistrovat v Trunku. Proces se skládá z jednoho kroku — příkazu pod trunk register:

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

Po provedení příkazu je na zadaný e-mail odeslán dopis s odkazem pro potvrzení. Kliknutím na odkaz se aktivuje účet a vytvoří se token relace, který je uložen v systémové klíčence (Keychain na macOS, gnome-keyring nebo ekvivalent na Linuxu). Token se automaticky používá při všech následujících operacích pod trunk.

Parametr --description je volitelný, ale doporučený — pomáhá identifikovat relaci při prohlížení aktivních relací přes pod trunk me. Pokud pracujete na více počítačích (pracovní stanice, CI server), popis vám umožní odlišit jednu relaci od druhé.

Pro kontrolu stavu autentizace se používá příkaz:

pod trunk me

Výstup zobrazuje e-mail, jméno, seznam vašich podů (pokud jste již publikovali) a aktivní relace. Příklad výsledku:

  - 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, vývoj pro iOS

Na CI serverech (GitHub Actions, GitLab CI, Jenkins) probíhá autentizace pomocí tokenu předaného prostřednictvím proměnné prostředí COCOAPODS_TRUNK_TOKEN. Token lze získat příkazem:

pod trunk me --token-only

Tento token je uložen v nastavení CI jako tajná proměnná a ve fázi publikace se používá bez opětovné registrace. Příklad pro GitHub Actions:

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

Důležité: token poskytuje plný přístup ke správě podů vázaných na účet. Nikdy jej nezveřejňujte ve veřejných repozitářích a nepředávejte třetím stranám. Při kompromitaci lze token odvolat pomocí pod trunk remove-session nebo odstranit všechny relace prostřednictvím ovládacího panelu na webu CocoaPods.

Příprava podspec

Soubor podspec (.podspec nebo .podspec.json) — je manifest knihovny obsahující metadata, závislosti, informace o platformách a zdrojovém kódu. Trunk tento soubor používá pro validaci a registraci podu. Minimální podspec pro publikaci vypadá takto:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Stručný popis knihovny'
  s.description  = 'Podrobný popis s vysvětlením možností'
  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

Klíčová pole podspec:

• name — název podu, musí být jedinečný v registru Trunk. Názvy se registrují na principu „kdo dřív přijde, ten dřív mele" — pokud je název obsazený, publikace bude zamítnuta.
• version — sémantická verze ve formátu MAJOR.MINOR.PATCH. Trunk nepřijímá opětovnou publikaci stejné verze — je třeba zvýšit číslo.
• source — odkaz na Git repozitář a tag. Trunk neukládá zdrojový kód, takže repozitář musí být přístupný pro klonování.
• platform — cílová platforma (iOS, macOS, tvOS, watchOS) a minimální verze SDK.
• license — typ licence. Doporučuje se uvádět MIT, Apache-2.0, BSD nebo jinou otevřenou licenci.

Před publikací je třeba zkontrolovat správnost podspec pomocí linteru:

pod lib lint MyLibrary.podspec

Linter kontroluje syntaxi, přítomnost povinných polí, správnost cest k souborům a řešitelnost závislostí. Pokud se v procesu lintingu používají soukromé zdroje (private specs), přidá se přepínač --sources. Pro přeskočení síťového stahování (pouze lokální kontrola) se používá přepínač --local-only.

Publikace přes pod trunk push

Hlavní příkaz pro publikaci podu — pod trunk push. Odesílá podspec soubor na server Trunk, kde prochází úplnou validací a je registrován ve veřejném registru. Syntaxe:

pod trunk push MyLibrary.podspec

Přepínač --allow-warnings povoluje publikaci při výskytu varování. Ve výchozím nastavení jakákoli varování (warnings) blokují publikaci. Pokud má knihovna známá varování, která neovlivňují funkčnost, můžete tento přepínač použít. Důležité: chyby (errors) vždy blokují publikaci, bez ohledu na přepínače.

Přepínač --synchronous činí požadavek synchronním — terminál čeká na dokončení validace na serveru. Ve výchozím nastavení příkaz vrátí řízení ihned po odeslání a server zpracovává publikaci asynchronně. Synchronní režim je užitečný v CI/CD, když další krok pipeline závisí na úspěšnosti publikace.

Přepínač --skip-import-validation přeskočí kontrolu importu knihovny do testovacího projektu. To urychluje publikaci, ale nezaručuje, že se knihovna skutečně zkompiluje. Použijte tento přepínač pouze pokud jste si jisti správností sestavení.

Příklad publikace s typickými možnostmi:

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

Po úspěšné publikaci Trunk vrátí JSON s podrobnostmi:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Knihovna se stane dostupnou pro instalaci přes Podfile libovolného iOS nebo macOS projektu. Obvykle se data v indexu vyhledávání CocoaPods aktualizují během několika minut, ale ve vzácných případech může indexace trvat až hodinu.

Důležité omezení: jednou publikovanou verzi podu nelze smazat. Toto je provedeno, aby se zabránilo poškození projektů, které tuto verzi již používají. Pokud publikace proběhla s chybou, můžete publikovat další verzi s opravou, ale vrácení zpět není možné. Výjimkou je pod trunk delete, dostupný pouze zaměstnancům CocoaPods a používaný v extrémních případech (porušení licence, škodlivý kód).

Správa vydání a přístupu

CocoaPods Trunk poskytuje několik příkazů pro správu publikovaných podů:

Přidávání vlastníků

Pro převedení práv k publikaci podu jinému vývojáři se používá následující příkaz:

pod trunk add-owner MyLibrary developer@email.com

Po provedení získá nový vlastník plný přístup ke správě podu: publikování nových verzí, přidávání a odebírání dalších vlastníků, označení podu jako zastaralého. Vlastníkem může být jakýkoli registrovaný uživatel Trunku — předchozí registrace je povinná.

Odebírání vlastníků

Pokud vývojář opustil projekt nebo by již neměl mít přístup k podu:

pod trunk remove-owner MyLibrary developer@email.com

Vlastníka může odebrat pouze aktuální vlastník. Nelze odebrat posledního vlastníka podu — nejprve je třeba přidat nového. Tím se zabrání situaci, kdy pod zůstane bez vlastníka.

Označení podu jako zastaralého

Pokud knihovna již není podporována, lze ji označit jako zastaralou (deprecated). Toto pod z registru neodstraní, ale přidá varování uživatelům při instalaci:

pod trunk deprecate MyLibrary

Volitelně lze zadat náhradní pod:

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

Při instalaci zastaralého podu CocoaPods zobrazí varování v terminálu a doporučí přechod na zadanou náhradu. Toto je správný způsob ukončení podpory knihovny bez narušení sestavení stávajících projektů.

Zobrazení informací o podu

Informace o podu jsou k dispozici prostřednictvím příkazu pod trunk info:

pod trunk info MyLibrary

Příkaz zobrazuje všechny verze podu, data publikace, seznam vlastníků a stav (aktivní/zastaralý). Pro zobrazení podrobností konkrétní verze se používá pod spec cat MyLibrary 0.1.0.

Chyby a jejich řešení

Při práci s Trunkem se vývojáři často setkávají s typickými chybami. Podívejme se na ty nejčastější:

Chyba autentizace

Příznak: [!] Authentication failed. You need to register a session first.
Příčina: Token relace chybí nebo vypršel. Tokeny mají omezenou dobu platnosti (výchozí 30 dní bez aktivity).
Řešení: Znovu spusťte pod trunk register your@email.com 'Your Name'. Pokud používáte CI, zkontrolujte aktuálnost proměnné COCOAPODS_TRUNK_TOKEN a v případě potřeby vygenerujte nový token.

Konflikt verzí

Příznak: [!] You have already pushed version 0.1.0 for MyLibrary.
Příčina: Pokus o opětovnou publikaci existující verze. Trunk neumožňuje přepisování verzí.
Řešení: Zvyšte verzi v podspec podle sémantického verzování. Pokud jste udělali chybu v podspec, publikujte další verzi s opravou.

Chyba validace podspec

Příznak: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Příčina: Nesprávně uvedená cesta ke zdrojovým souborům v poli source_files.
Řešení: Zkontrolujte cesty v podspec, spusťte pod lib lint lokálně do odstranění všech chyb, poté opakujte publikaci. Používejte glob vzory: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Timeout připojení

Příznak: [!] Connection to trunk.cocoapods.org failed. Timeout.
Příčina: Problémy se sítí nebo dočasná nedostupnost serveru Trunk.
Řešení: Zkontrolujte dostupnost serveru: curl -I https://trunk.cocoapods.org. Pokud server odpovídá, opakujte příkaz za pár minut. Vaše IP může být blokována — zkuste z jiného připojení nebo přes VPN.

Nedostatek přístupu k podu

Příznak: [!] You do not have permission to push to MyLibrary.
Příčina: Nejste vlastníkem podu. K tomu dochází, pokud již někdo zaregistroval pod s tímto názvem.
Řešení: Kontaktujte aktuálního vlastníka podu (lze zjistit přes pod trunk info MyLibrary) a požádejte o přidání přes pod trunk add-owner. Pokud je název podu obsazený, zvažte alternativní název.