CocoaPods Trunk: vad är det, publicera bibliotek via Trunk

Vad är CocoaPods Trunk?

CocoaPods Trunk — är en serverinfrastruktur som lanserades 2015 för centraliserad publicering av pod-bibliotek. Före Trunk distribuerades varje pod via ett Git-repository: utvecklaren var tvungen att skapa ett offentligt repository, lägga till en podspec-fil och skicka en Pull Request till det centrala CocoaPods/Specs-repositoryt. Detta tillvägagångssätt krävde manuell moderering och orsakade förseningar vid publicering av uppdateringar.

Trunk löste dessa problem genom att tillhandahålla ett enhetligt API för publicering, uppdatering och borttagning av poddar. Tjänsten omfattar fyra nyckelkomponenter:

• Autentisering — registrering med e-postbekräftelse och hantering av sessionstoken. Varje utvecklare får en unik token som är bunden till hans konto och enheter.
• Validering — automatisk kontroll av podspec före publicering, inklusive syntaktisk analys, linting av beroenden och kontroll av plattformskompatibilitet.
• Hosting — lagring av metadata och pod-versioner på CocoaPods-servrar. Källkoden finns kvar i utvecklarens Git-repository, medan Trunk endast lagrar podspec-filer och länkar.
• Åtkomsthantering — möjlighet att lägga till och ta bort ägare av poddar, överföra publiceringsrättigheter, markera poddar som föråldrade.

Arkitekturen för Trunk är byggd på Ruby on Rails-stack med PostgreSQL-databas. Tjänsten använder HTTP API med JSON-format för alla operationer, och CLI-klienten pod trunk är en del av CocoaPods-distributionen och installeras tillsammans med huvud-gemen cocoapods.

För närvarande har över 100 000 poddar publicerats via Trunk, med totalt antal nedladdningar som överstiger 50 miljarder. Dagligen behandlar tjänsten tusentals publicerings- och uppdateringsförfrågningar från utvecklare över hela världen.

Registrering och autentisering

Innan du publicerar en pod måste du registrera dig i Trunk. Processen består av ett steg — kommandot pod trunk register:

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

Efter att kommandot har körts skickas ett brev med en bekräftelselänk till den angivna e-postadressen. Genom att klicka på länken aktiveras kontot och en sessionstoken skapas som sparas i systemets nyckelkedja (Keychain på macOS, gnome-keyring eller motsvarighet på Linux). Token används automatiskt vid alla efterföljande pod trunk-operationer.

Parametern --description är valfri men rekommenderas — den hjälper till att identifiera sessionen när du visar aktiva sessioner via pod trunk me. Om du arbetar på flera maskiner (arbetsstation, CI-server) gör beskrivningen det möjligt att skilja en session från en annan.

För att kontrollera autentiseringsstatusen används följande kommando:

pod trunk me

Utdata visar e-post, namn, lista över dina poddar (om du redan har publicerat) och aktiva sessioner. Exempel på resultat:

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

På CI-servrar (GitHub Actions, GitLab CI, Jenkins) sker autentisering via en token som skickas via miljövariabeln COCOAPODS_TRUNK_TOKEN. Token kan erhållas med kommandot:

pod trunk me --token-only

Denna token sparas i CI-inställningarna som en hemlig variabel och används i publiceringsfasen utan omregistrering. Exempel för GitHub Actions:

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

Viktigt: token ger fullständig åtkomst till hanteringen av poddar som är kopplade till kontot. Publicera den aldrig i offentliga repositories och överlämna den inte till tredje part. Vid kompromettering kan token återkallas via pod trunk remove-session eller så kan alla sessioner tas bort via kontrollpanelen på CocoaPods webbplats.

Förbereda podspec

Podspec-filen (.podspec eller .podspec.json) — är manifestet för biblioteket som innehåller metadata, beroenden, information om plattformar och källkod. Trunk använder denna fil för validering och registrering av podden. En minimal podspec för publicering ser ut så här:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Kort beskrivning av biblioteket'
  s.description  = 'Detaljerad beskrivning med förklaring av funktioner'
  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

Nyckelfält i podspec:

• name — poddens namn, måste vara unikt i Trunk-registret. Namn registreras enligt principen 'först till kvarn' — om namnet är upptaget kommer publiceringen att avvisas.
• version — semantisk version i formatet MAJOR.MINOR.PATCH. Trunk accepterar inte återpublicering av samma version — du måste öka numret.
• source — länk till Git-repositoryt och tagg. Trunk lagrar inte källkoden, så repositoryt måste vara tillgängligt för kloning.
• platform — målplattform (iOS, macOS, tvOS, watchOS) och minimal SDK-version.
• license — licenstyp. Det rekommenderas att ange MIT, Apache-2.0, BSD eller annan öppen licens.

Före publicering måste podspec kontrolleras för korrekthet med hjälp av en linter:

pod lib lint MyLibrary.podspec

Linter kontrollerar syntax, förekomst av obligatoriska fält, korrekthet av filsökvägar och lösbarhet av beroenden. Om privata källor (private specs) används i lintningsprocessen läggs flaggan --sources till. För att hoppa över nätverksnedladdning (endast lokal kontroll) används flaggan --local-only.

Publicera via pod trunk push

Huvudkommandot för att publicera en pod — pod trunk push. Det skickar podspec-filen till Trunk-servern, där den genomgår fullständig validering och registreras i det offentliga registret. Syntax:

pod trunk push MyLibrary.podspec

Flaggan --allow-warnings tillåter publicering vid förekomst av varningar. Som standard blockerar alla varningar (warnings) publiceringen. Om biblioteket har kända varningar som inte påverkar funktionaliteten kan du använda denna flagga. Viktigt: fel (errors) blockerar alltid publiceringen, oavsett flaggor.

Flaggan --synchronous gör förfrågan synkron — terminalen väntar på att valideringen på servern ska slutföras. Som standard återlämnar kommandot kontrollen omedelbart efter sändning och servern bearbetar publiceringen asynkront. Synkront läge är användbart i CI/CD när nästa pipeline-steg beror på publiceringens framgång.

Flaggan --skip-import-validation hoppar över kontrollen av importen av biblioteket i ett testprojekt. Detta påskyndar publiceringen men garanterar inte att biblioteket faktiskt kompilerar. Använd denna flagga endast om du är säker på att bygget är korrekt.

Exempel på publicering med typiska alternativ:

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

Efter framgångsrik publicering returnerar Trunk en JSON med detaljer:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Biblioteket blir tillgängligt för installation via Podfile för alla iOS- eller macOS-projekt. Vanligtvis uppdateras data i CocoaPods sökindex inom några minuter, men i sällsynta fall kan indexeringen ta upp till en timme.

Viktig begränsning: en en gång publicerad pod-version kan inte tas bort. Detta för att förhindra skador på projekt som redan använder denna version. Om publiceringen gick fel kan du publicera nästa version med korrigeringen, men återställning är omöjlig. Undantag — pod trunk delete, endast tillgängligt för CocoaPods-anställda och tillämpas i extrema fall (licensbrott, skadlig kod).

Hantera utgåvor och åtkomst

CocoaPods Trunk tillhandahåller flera kommandon för administration av publicerade poddar:

Lägga till ägare

För att överföra publiceringsrättigheterna för en pod till en annan utvecklare används följande kommando:

pod trunk add-owner MyLibrary developer@email.com

Efter utförandet får den nya ägaren fullständig åtkomst till hanteringen av podden: publicering av nya versioner, lägga till och ta bort andra ägare, markera podden som föråldrad. Ägare kan vara vilken registrerad Trunk-användare som helst — förhandsregistrering är obligatorisk.

Ta bort ägare

Om en utvecklare har lämnat projektet eller inte längre ska ha åtkomst till podden:

pod trunk remove-owner MyLibrary developer@email.com

En ägare kan endast tas bort av den nuvarande ägaren. Den sista ägaren av en pod kan inte tas bort — först måste en ny läggas till. Detta förhindrar att podden blir utan ägare.

Markera pod som föråldrad

Om ett bibliotek inte längre stöds kan det markeras som föråldrat (deprecated). Detta tar inte bort podden från registret, men lägger till en varning för användare vid installation:

pod trunk deprecate MyLibrary

Alternativt kan en ersättningspod anges:

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

Vid installation av en föråldrad pod visar CocoaPods en varning i terminalen och rekommenderar att byta till den angivna ersättaren. Detta är det korrekta sättet att avsluta stödet för ett bibliotek utan att störa bygget av befintliga projekt.

Visa information om pod

Information om podden är tillgänglig via kommandot pod trunk info:

pod trunk info MyLibrary

Kommandot visar alla versioner av podden, publiceringsdatum, lista över ägare och status (aktiv/föråldrad). För att visa detaljer för en specifik version används pod spec cat MyLibrary 0.1.0.

Fel och deras lösning

Vid arbete med Trunk stöter utvecklare ofta på typiska fel. Låt oss titta på de vanligaste:

Autentiseringsfel

Symptom: [!] Authentication failed. You need to register a session first.
Orsak: Sessionstoken saknas eller har löpt ut. Token har begränsad giltighetstid (standard 30 dagar utan aktivitet).
Lösning: Kör pod trunk register your@email.com 'Your Name' igen. Om du använder CI, kontrollera att variabeln COCOAPODS_TRUNK_TOKEN är aktuell och generera vid behov en ny token.

Versionskonflikt

Symptom: [!] You have already pushed version 0.1.0 for MyLibrary.
Orsak: Försök att återpublicera en befintlig version. Trunk tillåter inte överskrivning av versioner.
Lösning: Öka versionen i podspec enligt semantisk versionshantering. Om du gjorde ett misstag i podspec, publicera nästa version med korrigeringen.

Podspec-valideringsfel

Symptom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Orsak: Sökvägen till källfiler i fältet source_files är felaktigt angiven.
Lösning: Kontrollera sökvägarna i podspec, kör pod lib lint lokalt tills alla fel är åtgärdade, upprepa sedan publiceringen. Använd glob-mönster: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Anslutningstimeout

Symptom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Orsak: Nätverksproblem eller tillfällig otillgänglighet av Trunk-servern.
Lösning: Kontrollera serverns tillgänglighet: curl -I https://trunk.cocoapods.org. Om servern svarar, upprepa kommandot om några minuter. Din IP kan vara blockerad — försök från en annan anslutning eller via VPN.

Ingen åtkomst till pod

Symptom: [!] You do not have permission to push to MyLibrary.
Orsak: Du är inte ägare till podden. Detta händer om någon redan har registrerat en pod med detta namn.
Lösning: Kontakta den nuvarande ägaren av podden (kan hittas via pod trunk info MyLibrary) och be att bli tillagd via pod trunk add-owner. Om pod-namnet är upptaget, överväg ett alternativt namn.