CocoaPods Trunk: ce este, publicarea bibliotecilor prin Trunk

Ce este CocoaPods Trunk?

CocoaPods Trunk — este infrastructura server lansată în 2015 pentru publicarea centralizată a bibliotecilor pod. Înainte de apariția Trunk, fiecare pod era distribuit printr-un depozit Git: dezvoltatorul trebuia să creeze un depozit public, să adauge un fișier podspec și să trimită un Pull Request în depozitul central CocoaPods/Specs. Această abordare necesita moderare manuală și crea întârzieri la publicarea actualizărilor.

Trunk a rezolvat aceste probleme, oferind un API unificat pentru publicarea, actualizarea și ștergerea pod-urilor. Serviciul include patru componente cheie:

• Autentificare — înregistrare cu confirmare prin email și gestionarea token-urilor de sesiune. Fiecare dezvoltator primește un token unic, care este legat de contul și dispozitivele sale.
• Validare — verificarea automată a podspec înainte de publicare, inclusiv analiza sintactică, lintingul dependențelor și verificarea compatibilității platformelor.
• Găzduire — stocarea metadatelor și versiunilor pod-urilor pe serverele CocoaPods. Codul sursă rămâne în depozitul Git al dezvoltatorului, iar Trunk stochează doar fișierele podspec și link-urile.
• Gestionarea accesului — posibilitatea de a adăuga și elimina proprietari ai pod-ului, de a transfera drepturile de publicare, de a marca pod-urile ca învechite.

Arhitectura Trunk este construită pe stiva Ruby on Rails cu baza de date PostgreSQL. Serviciul utilizează HTTP API cu format JSON pentru toate operațiunile, iar clientul CLI pod trunk face parte din distribuția CocoaPods și se instalează împreună cu gem-ul principal cocoapods.

În prezent, prin Trunk au fost publicate peste 100 000 de pod-uri, iar numărul total de descărcări depășește 50 de miliarde. Zilnic, serviciul procesează mii de cereri de publicare și actualizare a bibliotecilor din partea dezvoltatorilor din întreaga lume.

Înregistrare și autentificare

Înainte de publicarea unui pod, trebuie să vă înregistrați în Trunk. Procesul constă dintr-un singur pas — comanda pod trunk register:

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

După executarea comenzii, pe adresa de email specificată sosește un e-mail cu un link de confirmare. Accesarea linkului activează contul și creează un token de sesiune, care este salvat în sistemul de chei (Keychain pe macOS, gnome-keyring sau echivalent pe Linux). Tokenul este utilizat automat în toate operațiunile pod trunk ulterioare.

Parametrul --description este opțional, dar recomandat — ajută la identificarea sesiunii la vizualizarea sesiunilor active prin pod trunk me. Dacă lucrați pe mai multe mașini (stație de lucru, server CI), descrierea vă permite să distingeți o sesiune de alta.

Pentru verificarea stării de autentificare se utilizează comanda:

pod trunk me

Rezultatul afișează emailul, numele, lista pod-urilor dvs. (dacă ați publicat deja) și sesiunile active. Exemplu de rezultat:

  - 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, dezvoltare iOS

Pe serverele CI (GitHub Actions, GitLab CI, Jenkins) autentificarea se realizează printr-un token transmis prin variabila de mediu COCOAPODS_TRUNK_TOKEN. Tokenul poate fi obținut cu comanda:

pod trunk me --token-only

Acest token este salvat în setările CI ca variabilă secretă, iar la etapa de publicare este utilizat fără o nouă înregistrare. Exemplu pentru GitHub Actions:

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

Important: tokenul oferă acces complet la gestionarea pod-urilor asociate contului. Nu îl publicați niciodată în depozite publice și nu îl transmiteți terților. În caz de compromitere, tokenul poate fi revocat prin pod trunk remove-session sau puteți șterge toate sesiunile prin panoul de gestionare de pe site-ul CocoaPods.

Pregătirea podspec

Fișierul podspec (.podspec sau .podspec.json) — este manifestul bibliotecii care conține metadate, dependențe, informații despre platforme și codul sursă. Trunk utilizează acest fișier pentru validarea și înregistrarea pod-ului. Un podspec minim pentru publicare arată astfel:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Descrierea scurtă a bibliotecii'
  s.description  = 'Descrierea detaliată cu explicarea capacităților'
  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

Câmpurile cheie ale podspec:

• name — numele pod-ului, trebuie să fie unic în registrul Trunk. Numele sunt înregistrate pe principiul «primul venit, primul servit» — dacă numele este ocupat, publicarea va fi respinsă.
• version — versiunea semantică în formatul MAJOR.MINOR.PATCH. Trunk nu acceptă republicarea aceleiași versiuni — trebuie să măriți numărul.
• source — link către depozitul Git și tag. Trunk nu stochează codul sursă, deci depozitul trebuie să fie accesibil pentru clonare.
• platform — platforma țintă (iOS, macOS, tvOS, watchOS) și versiunea minimă a SDK-ului.
• license — tipul de licență. Se recomandă specificarea MIT, Apache-2.0, BSD sau a altei licențe deschise.

Înainte de publicare, podspec trebuie verificat pentru corectitudine cu ajutorul linter-ului:

pod lib lint MyLibrary.podspec

Linter-ul verifică sintaxa, existența câmpurilor obligatorii, corectitudinea căilor către fișiere și rezolvabilitatea dependențelor. Dacă în procesul de linting se utilizează surse private (private specs), se adaugă flag-ul --sources. Pentru a omite încărcarea din rețea (doar verificare locală) se utilizează flag-ul --local-only.

Publicarea prin pod trunk push

Comanda principală pentru publicarea unui pod — pod trunk push. Aceasta transmite fișierul podspec pe serverul Trunk, unde trece printr-o validare completă și este înregistrat în registrul public. Sintaxa:

pod trunk push MyLibrary.podspec

Flag-ul --allow-warnings permite publicarea în prezența avertismentelor. În mod implicit, orice avertismente (warnings) blochează publicarea. Dacă biblioteca are avertismente cunoscute care nu afectează funcționalitatea, puteți utiliza acest flag. Important: erorile (errors) blochează întotdeauna publicarea, indiferent de flag-uri.

Flag-ul --synchronous face cererea sincronă — terminalul așteaptă finalizarea validării pe server. În mod implicit, comanda returnează controlul imediat după trimitere, iar serverul procesează publicarea asincron. Modul sincron este util în CI/CD, când următorul pas al pipeline-ului depinde de succesul publicării.

Flag-ul --skip-import-validation omite verificarea importului bibliotecii într-un proiect de test. Aceasta accelerează publicarea, dar nu garantează că biblioteca se compilează efectiv. Utilizați acest flag doar dacă sunteți sigur de corectitudinea build-ului.

Exemplu de publicare cu opțiuni tipice:

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

După o publicare reușită, Trunk returnează un JSON cu detalii:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Biblioteca devine disponibilă pentru instalare prin Podfile al oricărui proiect iOS sau macOS. De obicei, datele din indexul de căutare CocoaPods se actualizează în câteva minute, dar în cazuri rare indexarea poate dura până la o oră.

Restricție importantă: o dată publicată, versiunea unui pod nu poate fi ștearsă. Acest lucru este menit să prevină deteriorarea proiectelor care utilizează deja această versiune. Dacă publicarea a avut loc cu eroare, puteți publica următoarea versiune cu corecția, dar revenirea este imposibilă. Excepție — pod trunk delete, disponibil doar angajaților CocoaPods și aplicat în cazuri extreme (încălcarea licenței, cod malițios).

Gestionarea versiunilor și accesului

CocoaPods Trunk oferă mai multe comenzi pentru administrarea pod-urilor publicate:

Adăugarea proprietarilor

Pentru a transfera drepturile de publicare a pod-ului unui alt dezvoltator, se utilizează comanda:

pod trunk add-owner MyLibrary developer@email.com

După executare, noul proprietar primește acces complet la gestionarea pod-ului: publicarea de noi versiuni, adăugarea și eliminarea altor proprietari, marcarea pod-ului ca învechit. Proprietar poate fi orice utilizator înregistrat Trunk — înregistrarea prealabilă este obligatorie.

Eliminarea proprietarilor

Dacă un dezvoltator a părăsit proiectul sau nu mai trebuie să aibă acces la pod:

pod trunk remove-owner MyLibrary developer@email.com

Poate elimina un proprietar doar proprietarul curent. Nu se poate șterge ultimul proprietar al pod-ului — mai întâi trebuie adăugat unul nou. Acest lucru previne situația în care pod-ul rămâne fără proprietar.

Marcarea pod-ului ca învechit

Dacă biblioteca nu mai este suportată, poate fi marcată ca învechită (deprecated). Aceasta nu șterge pod-ul din registru, dar adaugă un avertisment utilizatorilor la instalare:

pod trunk deprecate MyLibrary

Opțional, se poate specifica un pod de înlocuire:

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

La instalarea unui pod învechit, CocoaPods afișează un avertisment în terminal și recomandă trecerea la înlocuitorul specificat. Aceasta este modalitatea corectă de a încheia suportul unei biblioteci fără a afecta build-ul proiectelor existente.

Vizualizarea informațiilor despre pod

Informațiile despre pod sunt disponibile prin comanda pod trunk info:

pod trunk info MyLibrary

Comanda afișează toate versiunile pod-ului, datele de publicare, lista proprietarilor și statusul (activ/învechit). Pentru vizualizarea detaliilor unei versiuni specifice se utilizează pod spec cat MyLibrary 0.1.0.

Erori și soluționarea lor

În lucrul cu Trunk, dezvoltatorii întâlnesc adesea erori tipice. Să le analizăm pe cele mai comune:

Eroare de autentificare

Simptom: [!] Authentication failed. You need to register a session first.
Cauză: Tokenul de sesiune lipsește sau a expirat. Token-urile au o perioadă limitată de valabilitate (implicit 30 de zile fără activitate).
Soluție: Rulați din nou pod trunk register your@email.com 'Your Name'. Dacă utilizați CI, verificați actualitatea variabilei COCOAPODS_TRUNK_TOKEN și, dacă este necesar, generați un nou token.

Conflict de versiuni

Simptom: [!] You have already pushed version 0.1.0 for MyLibrary.
Cauză: Încercarea de a republica o versiune existentă. Trunk nu permite suprascrierea versiunilor.
Soluție: Măriți versiunea în podspec conform versionării semantice. Dacă ați greșit în podspec, publicați următoarea versiune cu corecția.

Eroare de validare podspec

Simptom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Cauză: Calea către fișierele sursă în câmpul source_files este specificată incorect.
Soluție: Verificați căile în podspec, rulați pod lib lint local până la eliminarea tuturor erorilor, apoi repetați publicarea. Utilizați glob-uri: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Timeout conexiune

Simptom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Cauză: Probleme de rețea sau indisponibilitatea temporară a serverului Trunk.
Soluție: Verificați accesibilitatea serverului: curl -I https://trunk.cocoapods.org. Dacă serverul răspunde, repetați comanda peste câteva minute. Este posibil ca IP-ul dvs. să fie blocat — încercați de la o altă conexiune sau prin VPN.

Lipsa accesului la pod

Simptom: [!] You do not have permission to push to MyLibrary.
Cauză: Nu sunteți proprietarul pod-ului. Acest lucru se întâmplă dacă cineva a înregistrat deja un pod cu acest nume.
Soluție: Contactați proprietarul actual al pod-ului (poate fi aflat prin pod trunk info MyLibrary) și solicitați să vă adauge prin pod trunk add-owner. Dacă numele pod-ului este ocupat, luați în considerare un nume alternativ.