CocoaPods Trunk: cos'è, pubblicazione di librerie tramite Trunk

Cos'è CocoaPods Trunk?

CocoaPods Trunk è un'infrastruttura server lanciata nel 2015 per la pubblicazione centralizzata delle librerie pod. Prima di Trunk, ogni pod veniva distribuito tramite un repository Git: lo sviluppatore doveva creare un repository pubblico, aggiungere un file podspec e inviare una Pull Request al repository centrale CocoaPods/Specs. Questo approccio richiedeva moderazione manuale e creava ritardi nella pubblicazione degli aggiornamenti.

Trunk ha risolto questi problemi fornendo un'API unificata per pubblicare, aggiornare e gestire i pod. Il servizio include quattro componenti chiave:

• Autenticazione — registrazione con conferma email e gestione dei token di sessione. Ogni sviluppatore riceve un token unico collegato al proprio account e ai propri dispositivi.
• Validazione — verifica automatica del podspec prima della pubblicazione, inclusa analisi sintattica, linting delle dipendenze e controllo di compatibilità delle piattaforme.
• Hosting — archiviazione dei metadati e delle versioni dei pod sui server CocoaPods. Il codice sorgente rimane nel repository Git dello sviluppatore, mentre Trunk memorizza solo i file podspec e i collegamenti.
• Gestione degli accessi — possibilità di aggiungere e rimuovere proprietari dei pod, trasferire i diritti di pubblicazione, contrassegnare i pod come obsoleti.

L'architettura di Trunk è basata su Ruby on Rails con database PostgreSQL. Il servizio utilizza API HTTP con formato JSON per tutte le operazioni, e il client CLI pod trunk fa parte della distribuzione CocoaPods, installato insieme alla gemma principale cocoapods.

Ad oggi, oltre 100.000 pod sono stati pubblicati tramite Trunk, con un totale di download superiore a 50 miliardi. Il servizio elabora migliaia di richieste di pubblicazione e aggiornamento ogni giorno da sviluppatori di tutto il mondo.

Registrazione e autenticazione

Prima di pubblicare un pod, è necessario registrarsi a Trunk. Il processo consiste in un unico passaggio — il comando pod trunk register:

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

Dopo l'esecuzione del comando, viene inviato un link di conferma all'email specificata. Cliccando sul link si attiva l'account e si crea un token di sessione che viene memorizzato nel portachiavi di sistema (Keychain su macOS, gnome-keyring o equivalente su Linux). Il token viene utilizzato automaticamente per tutte le successive operazioni pod trunk.

Il parametro --description è facoltativo ma consigliato — aiuta a identificare la sessione durante la visualizzazione delle sessioni attive tramite pod trunk me. Se si lavora da più macchine (workstation, server CI), la descrizione consente di distinguere una sessione dall'altra.

Per verificare lo stato dell'autenticazione, utilizzare il comando:

pod trunk me

L'output mostra email, nome, elenco dei propri pod (se già pubblicati) e sessioni attive. Esempio di risultato:

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

Sui server CI (GitHub Actions, GitLab CI, Jenkins), l'autenticazione avviene tramite un token passato attraverso la variabile d'ambiente COCOAPODS_TRUNK_TOKEN. Il token può essere ottenuto con il comando:

pod trunk me --token-only

Questo token viene memorizzato nelle impostazioni CI come variabile segreta e utilizzato nella fase di pubblicazione senza ripetere la registrazione. Esempio per GitHub Actions:

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

Importante: il token fornisce accesso completo alla gestione dei pod collegati all'account. Non pubblicarlo mai in repository pubblici né condividerlo con terze parti. Se compromesso, il token può essere revocato tramite pod trunk remove-session o eliminando tutte le sessioni tramite il pannello di controllo del sito CocoaPods.

Preparazione del podspec

Il file podspec (.podspec o .podspec.json) è il manifesto della libreria contenente metadati, dipendenze, informazioni sulle piattaforme e dettagli del codice sorgente. Trunk utilizza questo file per la validazione e la registrazione del pod. Un podspec minimo per la pubblicazione si presenta così:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Breve descrizione della libreria'
  s.description  = 'Descrizione dettagliata con spiegazione delle funzionalità'
  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

Campi chiave del podspec:

• name — nome del pod, deve essere univoco nel registro Trunk. I nomi vengono registrati in base al principio "primo arrivato, primo servito" — se il nome è occupato, la pubblicazione verrà rifiutata.
• version — versione semantica nel formato MAJOR.MINOR.PATCH. Trunk non accetta la ripubblicazione della stessa versione — è necessario incrementare il numero.
• source — link al repository Git e tag. Trunk non memorizza il codice sorgente, quindi il repository deve essere disponibile per la clonazione.
• platform — piattaforma di destinazione (iOS, macOS, tvOS, watchOS) e versione minima dell'SDK.
• license — tipo di licenza. Si consiglia di specificare MIT, Apache-2.0, BSD o un'altra licenza open source.

Prima della pubblicazione, verificare la correttezza del podspec con il linter:

pod lib lint MyLibrary.podspec

Il linter controlla la sintassi, i campi obbligatori, la correttezza dei percorsi dei file e la risolvibilità delle dipendenze. Se durante il linting vengono utilizzate fonti private, viene aggiunto il flag --sources. Per saltare il download di rete (solo controllo locale), viene utilizzato il flag --local-only.

Pubblicazione tramite pod trunk push

Il comando principale per pubblicare un pod è pod trunk push. Invia il file podspec al server Trunk, dove viene sottoposto a una validazione completa e registrato nel registro pubblico. Sintassi:

pod trunk push MyLibrary.podspec

Il flag --allow-warnings consente la pubblicazione in presenza di avvisi. Per impostazione predefinita, qualsiasi avviso blocca la pubblicazione. Se la libreria ha avvisi noti che non influiscono sulla funzionalità, è possibile utilizzare questo flag. Importante: gli errori bloccano sempre la pubblicazione, indipendentemente dai flag.

Il flag --synchronous rende la richiesta sincrona — il terminale attende il completamento della validazione lato server. Per impostazione predefinita, il comando restituisce il controllo immediatamente dopo l'invio e il server elabora la pubblicazione in modo asincrono. La modalità sincrona è utile in CI/CD quando il passaggio successivo della pipeline dipende dal successo della pubblicazione.

Il flag --skip-import-validation salta la verifica dell'importazione della libreria in un progetto di test. Questo velocizza la pubblicazione ma non garantisce che la libreria compili effettivamente. Utilizzare questo flag solo se si è sicuri della correttezza della build.

Esempio di pubblicazione con opzioni tipiche:

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

Dopo una pubblicazione riuscita, Trunk restituisce un JSON con i dettagli:

  Congrats

  MyLibrary (0.1.0) successfully published

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

La libreria diventa disponibile per l'installazione tramite Podfile in qualsiasi progetto iOS o macOS. Normalmente, l'indice di ricerca CocoaPods viene aggiornato entro pochi minuti, ma in rari casi l'indicizzazione può richiedere fino a un'ora.

Limitazione importante: una versione di pod pubblicata non può essere eliminata. Questo per evitare di rompere i progetti che già utilizzano questa versione. Se la pubblicazione è stata errata, è possibile pubblicare la versione successiva con la correzione, ma il rollback è impossibile. L'eccezione è pod trunk delete, disponibile solo per il personale CocoaPods e utilizzato in casi estremi (violazione di licenza, codice dannoso).

Gestione dei rilasci e dell'accesso

CocoaPods Trunk fornisce diversi comandi per amministrare i pod pubblicati:

Aggiungere proprietari

Per trasferire i diritti di pubblicazione di un pod a un altro sviluppatore, utilizzare il comando:

pod trunk add-owner MyLibrary developer@email.com

Dopo l'esecuzione, il nuovo proprietario ottiene accesso completo alla gestione del pod: pubblicazione di nuove versioni, aggiunta e rimozione di altri proprietari, contrassegno del pod come obsoleto. Qualsiasi utente registrato di Trunk può essere proprietario — la registrazione preventiva è obbligatoria.

Rimuovere proprietari

Se uno sviluppatore ha lasciato il progetto o non dovrebbe più avere accesso al pod:

pod trunk remove-owner MyLibrary developer@email.com

Solo un proprietario attuale può rimuovere un proprietario. Non è possibile rimuovere l'ultimo proprietario di un pod — prima è necessario aggiungerne uno nuovo. Questo impedisce che un pod rimanga senza proprietario e venga abbandonato.

Contrassegnare un pod come obsoleto

Se la libreria non è più mantenuta, è possibile contrassegnarla come obsoleta (deprecated). Questo non rimuove il pod dal registro, ma aggiunge un avviso per gli utenti durante l'installazione:

pod trunk deprecate MyLibrary

Opzionalmente, è possibile specificare un pod sostitutivo:

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

Durante l'installazione di un pod obsoleto, CocoaPods mostra un avviso nel terminale e consiglia di passare al sostituto specificato. Questo è il modo corretto per terminare il supporto di una libreria senza rompere le build dei progetti esistenti.

Visualizzare le informazioni del pod

Le informazioni del pod sono disponibili tramite il comando pod trunk info:

pod trunk info MyLibrary

Il comando mostra tutte le versioni del pod, le date di pubblicazione, l'elenco dei proprietari e lo stato (attivo/obsoleto). Per vedere i dettagli di una versione specifica, utilizzare pod spec cat MyLibrary 0.1.0.

Errori e soluzioni

Quando lavorano con Trunk, gli sviluppatori incontrano spesso errori tipici. Esaminiamo i più comuni:

Errore di autenticazione

Sintomo: [!] Authentication failed. You need to register a session first.
Causa: Token di sessione mancante o scaduto. I token hanno un periodo di validità limitato (30 giorni senza attività per impostazione predefinita).
Soluzione: Eseguire nuovamente pod trunk register your@email.com 'Your Name'. Se si utilizza CI, verificare che la variabile d'ambiente COCOAPODS_TRUNK_TOKEN sia aggiornata e generare un nuovo token se necessario.

Conflitto di versioni

Sintomo: [!] You have already pushed version 0.1.0 for MyLibrary.
Causa: Tentativo di ripubblicazione di una versione esistente. Trunk non consente di sovrascrivere le versioni.
Soluzione: Incrementare la versione nel podspec secondo il versionamento semantico. Se si è commesso un errore nel podspec, pubblicare la versione successiva con la correzione.

Errore di validazione del podspec

Sintomo: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Causa: Percorso errato ai file sorgente nel campo source_files.
Soluzione: Verificare i percorsi nel podspec, eseguire pod lib lint localmente fino alla risoluzione di tutti gli errori, quindi ripetere la pubblicazione. Utilizzare pattern glob: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Timeout di connessione

Sintomo: [!] Connection to trunk.cocoapods.org failed. Timeout.
Causa: Problemi di rete o indisponibilità temporanea del server Trunk.
Soluzione: Verificare la disponibilità del server: curl -I https://trunk.cocoapods.org. Se il server risponde, ripetere il comando dopo alcuni minuti. L'IP potrebbe essere bloccato — provare da un'altra connessione o tramite VPN.

Nessun accesso al pod

Sintomo: [!] You do not have permission to push to MyLibrary.
Causa: Non si è proprietari del pod. Questo accade se qualcuno ha già registrato un pod con quel nome.
Soluzione: Contattare il proprietario attuale del pod (identificabile tramite pod trunk info MyLibrary) e chiedergli di aggiungerlo tramite pod trunk add-owner. Se il nome del pod è occupato, considerare un nome alternativo.