CocoaPods Trunk: wat is het, publiceren van bibliotheken via Trunk

Wat is CocoaPods Trunk?

CocoaPods Trunk — is een serverinfrastructuur die in 2015 is gelanceerd voor gecentraliseerde publicatie van pod-bibliotheken. Vóór de komst van Trunk werd elke pod via een Git-repository verspreid: een ontwikkelaar moest een openbare repository aanmaken, een podspec-bestand toevoegen en een Pull Request indienen bij de centrale repository CocoaPods/Specs. Deze aanpak vereiste handmatige moderatie en veroorzaakte vertragingen bij het publiceren van updates.

Trunk loste deze problemen op door een uniforme API te bieden voor het publiceren, bijwerken en verwijderen van pods. De service omvat vier kerncomponenten:

• Authenticatie — registratie met e-mailbevestiging en beheer van sessietokens. Elke ontwikkelaar krijgt een uniek token dat aan zijn account en apparaten is gekoppeld.
• Validatie — automatische controle van podspec voor publicatie, inclusief syntaxanalyse, linting van afhankelijkheden en controle op platformcompatibiliteit.
• Hosting — opslag van metadata en pod-versies op CocoaPods-servers. De broncode blijft in de Git-repository van de ontwikkelaar; Trunk slaat alleen podspec-bestanden en links op.
• Toegangsbeheer — mogelijkheid om pod-eigenaren toe te voegen en te verwijderen, publicatierechten over te dragen, pods als verouderd te markeren.

De architectuur van Trunk is gebouwd op Ruby on Rails met PostgreSQL-database. De service gebruikt HTTP API met JSON-formaat voor alle bewerkingen, en de CLI-client pod trunk maakt deel uit van de CocoaPods-distributie en wordt samen met de hoofd-gem cocoapods geïnstalleerd.

Momenteel zijn via Trunk meer dan 100.000 pods gepubliceerd, met een totaal aantal downloads van meer dan 50 miljard. Dagelijks verwerkt de service duizenden publicatie- en updateverzoeken van ontwikkelaars over de hele wereld.

Registratie en authenticatie

Voordat u een pod publiceert, moet u zich registreren bij Trunk. Het proces bestaat uit één stap — het commando pod trunk register:

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

Na het uitvoeren van het commando ontvangt u een e-mail met een bevestigingslink. Door op de link te klikken wordt het account geactiveerd en wordt een sessietoken aangemaakt dat wordt opgeslagen in de systeem-sleutelketen (Keychain op macOS, gnome-keyring of equivalent op Linux). Het token wordt automatisch gebruikt bij alle volgende pod trunk-bewerkingen.

De parameter --description is optioneel maar aanbevolen — het helpt bij het identificeren van een sessie bij het bekijken van actieve sessies via pod trunk me. Als u op meerdere machines werkt (werkstation, CI-server), kunt u met de beschrijving de ene sessie van de andere onderscheiden.

Om de authenticatiestatus te controleren, wordt het volgende commando gebruikt:

pod trunk me

De uitvoer toont het e-mailadres, naam, lijst van uw pods (indien u al hebt gepubliceerd) en actieve sessies. Voorbeeld van de uitvoer:

  - 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-ontwikkeling

Op CI-servers (GitHub Actions, GitLab CI, Jenkins) vindt authenticatie plaats via een token dat wordt doorgegeven via de omgevingsvariabele COCOAPODS_TRUNK_TOKEN. Het token kan worden verkregen met het commando:

pod trunk me --token-only

Dit token wordt opgeslagen in de CI-instellingen als een geheime variabele en wordt in de publicatiefase gebruikt zonder opnieuw te registreren. Voorbeeld voor GitHub Actions:

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

Belangrijk: het token geeft volledige toegang tot het beheer van aan het account gekoppelde pods. Publiceer het nooit in openbare repositories en geef het niet aan derden. Bij compromittering kan het token worden ingetrokken via pod trunk remove-session of kunnen alle sessies worden verwijderd via het bedieningspaneel op de CocoaPods-website.

Voorbereiden van podspec

Het podspec-bestand (.podspec of .podspec.json) — is het manifest van de bibliotheek met metadata, afhankelijkheden, informatie over platforms en broncode. Trunk gebruikt dit bestand voor validatie en registratie van de pod. Een minimale podspec voor publicatie ziet er als volgt uit:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Korte beschrijving van de bibliotheek'
  s.description  = 'Gedetailleerde beschrijving met uitleg van mogelijkheden'
  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

Belangrijkste podspec-velden:

• name — naam van de pod, moet uniek zijn in het Trunk-register. Namen worden geregistreerd op basis van het principe 'wie het eerst komt, wie het eerst maalt' — als de naam bezet is, wordt publicatie geweigerd.
• version — semantische versie in het formaat MAJOR.MINOR.PATCH. Trunk accepteert geen herpublicatie van dezelfde versie — u moet het nummer verhogen.
• source — link naar de Git-repository en tag. Trunk slaat de broncode niet op, dus de repository moet toegankelijk zijn om te klonen.
• platform — doelplatform (iOS, macOS, tvOS, watchOS) en minimale SDK-versie.
• license — licentietype. Het wordt aanbevolen MIT, Apache-2.0, BSD of een andere open licentie te vermelden.

Voor publicatie moet de podspec met een linter worden gecontroleerd:

pod lib lint MyLibrary.podspec

De linter controleert de syntax, aanwezigheid van verplichte velden, correctheid van bestandspaden en oplosbaarheid van afhankelijkheden. Als in het lintingproces privébronnen (private specs) worden gebruikt, wordt de vlag --sources toegevoegd. Om netwerkdownload over te slaan (alleen lokale controle) wordt de vlag --local-only gebruikt.

Publiceren via pod trunk push

Het hoofdcommando voor het publiceren van een pod — pod trunk push. Het verzendt het podspec-bestand naar de Trunk-server, waar het volledige validatie ondergaat en wordt geregistreerd in het openbare register. Syntax:

pod trunk push MyLibrary.podspec

De vlag --allow-warnings staat publicatie toe bij aanwezigheid van waarschuwingen. Standaard blokkeren alle waarschuwingen (warnings) de publicatie. Als de bibliotheek bekende waarschuwingen heeft die de functionaliteit niet beïnvloeden, kunt u deze vlag gebruiken. Belangrijk: fouten (errors) blokkeren altijd de publicatie, ongeacht de vlaggen.

De vlag --synchronous maakt het verzoek synchroon — de terminal wacht op voltooiing van de validatie op de server. Standaard retourneert het commando direct de controle na verzending en verwerkt de server de publicatie asynchroon. Synchrone modus is handig in CI/CD wanneer de volgende pipeline-stap afhangt van het succes van de publicatie.

De vlag --skip-import-validation slaat de controle van de import van de bibliotheek in een testproject over. Dit versnelt de publicatie, maar garandeert niet dat de bibliotheek daadwerkelijk compileert. Gebruik deze vlag alleen als u zeker bent van de correctheid van de build.

Voorbeeld van publicatie met typische opties:

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

Na succesvolle publicatie retourneert Trunk een JSON met details:

  Congrats

  MyLibrary (0.1.0) successfully published

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

De bibliotheek wordt beschikbaar voor installatie via Podfile van elk iOS- of macOS-project. Gewoonlijk worden de gegevens in de CocoaPods-zoekindex binnen enkele minuten bijgewerkt, maar in zeldzame gevallen kan de indexering tot een uur duren.

Belangrijke beperking: een eenmaal gepubliceerde podversie kan niet worden verwijderd. Dit is om schade te voorkomen aan projecten die deze versie al gebruiken. Als de publicatie met een fout is verlopen, kunt u de volgende versie met een correctie publiceren, maar terugdraaien is onmogelijk. Uitzondering — pod trunk delete, alleen beschikbaar voor CocoaPods-medewerkers en toegepast in extreme gevallen (licentieschending, kwaadaardige code).

Beheren van releases en toegang

CocoaPods Trunk biedt verschillende commando's voor het beheren van gepubliceerde pods:

Eigenaren toevoegen

Om de publicatierechten van een pod aan een andere ontwikkelaar over te dragen, wordt het volgende commando gebruikt:

pod trunk add-owner MyLibrary developer@email.com

Na uitvoering krijgt de nieuwe eigenaar volledige toegang tot het beheer van de pod: publiceren van nieuwe versies, toevoegen en verwijderen van andere eigenaren, markeren van de pod als verouderd. Eigenaar kan elke geregistreerde Trunk-gebruiker zijn — voorafgaande registratie is verplicht.

Eigenaren verwijderen

Als een ontwikkelaar het project heeft verlaten of geen toegang meer tot de pod mag hebben:

pod trunk remove-owner MyLibrary developer@email.com

Een eigenaar kan alleen worden verwijderd door de huidige eigenaar. De laatste eigenaar van een pod kan niet worden verwijderd — eerst moet een nieuwe worden toegevoegd. Dit voorkomt dat een pod zonder eigenaar komt te zitten.

Pod als verouderd markeren

Als een bibliotheek niet langer wordt ondersteund, kan deze als verouderd (deprecated) worden gemarkeerd. Dit verwijdert de pod niet uit het register, maar voegt een waarschuwing toe voor gebruikers bij installatie:

pod trunk deprecate MyLibrary

Optioneel kan een vervangende pod worden opgegeven:

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

Bij installatie van een verouderde pod geeft CocoaPods een waarschuwing in de terminal en raadt aan over te stappen op de opgegeven vervanger. Dit is de juiste manier om de ondersteuning van een bibliotheek te beëindigen zonder de builds van bestaande projecten te verstoren.

Informatie over een pod bekijken

Informatie over een pod is beschikbaar via het commando pod trunk info:

pod trunk info MyLibrary

Het commando toont alle versies van de pod, publicatiedata, lijst van eigenaren en status (actief/verouderd). Voor het bekijken van details van een specifieke versie wordt pod spec cat MyLibrary 0.1.0 gebruikt.

Fouten en oplossingen

Bij het werken met Trunk komen ontwikkelaars vaak typische fouten tegen. Laten we de meest voorkomende bekijken:

Authenticatiefout

Symptoom: [!] Authentication failed. You need to register a session first.
Oorzaak: Sessietoken ontbreekt of is verlopen. Tokens hebben een beperkte geldigheidsduur (standaard 30 dagen zonder activiteit).
Oplossing: Voer opnieuw pod trunk register your@email.com 'Your Name' uit. Als u CI gebruikt, controleer dan de actualiteit van de variabele COCOAPODS_TRUNK_TOKEN en genereer indien nodig een nieuw token.

Versieconflict

Symptoom: [!] You have already pushed version 0.1.0 for MyLibrary.
Oorzaak: Poging tot herpublicatie van een bestaande versie. Trunk staat niet toe dat versies worden overschreven.
Oplossing: Verhoog de versie in podspec volgens semantische versionering. Als u een fout hebt gemaakt in podspec, publiceer dan de volgende versie met de correctie.

Podspec-validatiefout

Symptoom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Oorzaak: Het pad naar bronbestanden in het veld source_files is onjuist opgegeven.
Oplossing: Controleer de paden in podspec, voer pod lib lint lokaal uit tot alle fouten zijn opgelost en herhaal vervolgens de publicatie. Gebruik glob-patronen: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Verbindingstime-out

Symptoom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Oorzaak: Netwerkproblemen of tijdelijke onbeschikbaarheid van de Trunk-server.
Oplossing: Controleer de beschikbaarheid van de server: curl -I https://trunk.cocoapods.org. Als de server reageert, herhaal het commando dan over enkele minuten. Mogelijk is uw IP geblokkeerd — probeer het via een andere verbinding of via VPN.

Geen toegang tot pod

Symptoom: [!] You do not have permission to push to MyLibrary.
Oorzaak: U bent niet de eigenaar van de pod. Dit gebeurt als iemand al een pod met deze naam heeft geregistreerd.
Oplossing: Neem contact op met de huidige eigenaar van de pod (te vinden via pod trunk info MyLibrary) en vraag om u toe te voegen via pod trunk add-owner. Als de podnaam bezet is, overweeg dan een alternatieve naam.