CocoaPods Trunk: Was es ist, Bibliotheken über Trunk veröffentlichen

Was ist CocoaPods Trunk?

CocoaPods Trunk ist eine Serverinfrastruktur, die 2015 für die zentralisierte Veröffentlichung von Pod-Bibliotheken eingeführt wurde. Vor Trunk wurde jeder Pod über ein Git-Repository verteilt: Der Entwickler musste ein öffentliches Repository erstellen, eine Podspec-Datei hinzufügen und einen Pull Request an das zentrale Repository CocoaPods/Specs senden. Dieser Ansatz erforderte manuelle Moderation und verursachte Verzögerungen bei der Veröffentlichung von Aktualisierungen.

Trunk löste diese Probleme, indem es eine einheitliche API zum Veröffentlichen, Aktualisieren und Verwalten von Pods bereitstellte. Der Dienst umfasst vier Schlüsselkomponenten:

• Authentifizierung — Registrierung mit E-Mail-Bestätigung und Verwaltung von Sitzungstoken. Jeder Entwickler erhält ein eindeutiges Token, das mit seinem Konto und seinen Geräten verknüpft ist.
• Validierung — automatische Überprüfung der Podspec vor der Veröffentlichung, einschließlich Syntaxanalyse, Abhängigkeits-Linting und Plattformkompatibilitätsprüfung.
• Hosting — Speicherung von Pod-Metadaten und -Versionen auf CocoaPods-Servern. Der Quellcode verbleibt im Git-Repository des Entwicklers, während Trunk nur Podspec-Dateien und Links speichert.
• Zugriffsverwaltung — Möglichkeit, Pod-Besitzer hinzuzufügen und zu entfernen, Veröffentlichungsrechte zu übertragen, Pods als veraltet zu markieren.

Die Architektur von Trunk basiert auf dem Ruby-on-Rails-Stack mit einer PostgreSQL-Datenbank. Der Dienst verwendet eine HTTP-API mit JSON-Format für alle Operationen, und der CLI-Client pod trunk ist Teil der CocoaPods-Distribution und wird zusammen mit dem Haupt-Gem cocoapods installiert.

Bis heute wurden über 100.000 Pods über Trunk veröffentlicht, die Gesamtzahl der Downloads übersteigt 50 Milliarden. Der Dienst verarbeitet täglich Tausende von Veröffentlichungs- und Aktualisierungsanfragen von Entwicklern weltweit.

Registrierung und Authentifizierung

Vor der Veröffentlichung eines Pods müssen Sie sich bei Trunk registrieren. Der Prozess besteht aus einem einzigen Schritt — dem Befehl pod trunk register:

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

Nach der Ausführung des Befehls wird an die angegebene E-Mail ein Bestätigungslink gesendet. Durch Klicken auf den Link wird das Konto aktiviert und ein Sitzungstoken erstellt, das in der System-Tresor (Keychain unter macOS, gnome-keyring oder Äquivalent unter Linux) gespeichert wird. Das Token wird automatisch bei allen nachfolgenden pod trunk-Operationen verwendet.

Der Parameter --description ist optional, aber empfohlen — er hilft, die Sitzung bei der Anzeige aktiver Sitzungen über pod trunk me zu identifizieren. Wenn Sie von mehreren Maschinen (Workstation, CI-Server) aus arbeiten, ermöglicht die Beschreibung, eine Sitzung von einer anderen zu unterscheiden.

Um den Authentifizierungsstatus zu überprüfen, verwenden Sie den Befehl:

pod trunk me

Die Ausgabe zeigt E-Mail, Name, Liste Ihrer Pods (falls bereits veröffentlicht) und aktive Sitzungen. Beispielergebnis:

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

Auf CI-Servern (GitHub Actions, GitLab CI, Jenkins) erfolgt die Authentifizierung über ein Token, das über die Umgebungsvariable COCOAPODS_TRUNK_TOKEN übergeben wird. Das Token kann mit dem Befehl abgerufen werden:

pod trunk me --token-only

Dieses Token wird in den CI-Einstellungen als geheime Variable gespeichert und im Veröffentlichungsschritt ohne erneute Registrierung verwendet. Beispiel für GitHub Actions:

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

Wichtig: Das Token gewährt vollständigen Zugriff auf die Verwaltung der mit dem Konto verknüpften Pods. Veröffentlichen Sie es niemals in öffentlichen Repositories oder geben Sie es an Dritte weiter. Bei Kompromittierung kann das Token über pod trunk remove-session widerrufen oder durch Löschen aller Sitzungen über das Kontrollfeld der CocoaPods-Website entfernt werden.

Podspec vorbereiten

Die Podspec-Datei (.podspec oder .podspec.json) ist das Manifest der Bibliothek, das Metadaten, Abhängigkeiten, Plattforminformationen und Quellcodedetails enthält. Trunk verwendet diese Datei zur Validierung und Pod-Registrierung. Eine minimale Podspec für die Veröffentlichung sieht so aus:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Kurzbeschreibung der Bibliothek'
  s.description  = 'Detaillierte Beschreibung mit Erläuterung der Funktionen'
  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

Schlüsselfelder der Podspec:

• name — der Pod-Name, muss in der Trunk-Registry eindeutig sein. Namen werden nach dem Prinzip „Wer zuerst kommt, mahlt zuerst" registriert — ist der Name vergeben, wird die Veröffentlichung abgelehnt.
• version — semantische Version im Format MAJOR.MINOR.PATCH. Trunk akzeptiert keine erneute Veröffentlichung derselben Version — die Nummer muss erhöht werden.
• source — Link zum Git-Repository und Tag. Trunk speichert den Quellcode nicht, daher muss das Repository zum Klonen verfügbar sein.
• platform — Zielplattform (iOS, macOS, tvOS, watchOS) und minimale SDK-Version.
• license — Lizenztyp. Es wird empfohlen, MIT, Apache-2.0, BSD oder eine andere Open-Source-Lizenz anzugeben.

Vor der Veröffentlichung die Podspec mit dem Linter auf Korrektheit prüfen:

pod lib lint MyLibrary.podspec

Der Linter überprüft Syntax, Pflichtfelder, Korrektheit der Dateipfade und Auflösbarkeit von Abhängigkeiten. Wenn beim Linting private Quellen verwendet werden, wird das Flag --sources hinzugefügt. Zum Überspringen von Netzwerkdownloads (nur lokale Prüfung) wird das Flag --local-only verwendet.

Veröffentlichung über pod trunk push

Der Hauptbefehl zum Veröffentlichen eines Pods ist pod trunk push. Er sendet die Podspec-Datei an den Trunk-Server, wo sie einer vollständigen Validierung unterzogen und in der öffentlichen Registry registriert wird. Syntax:

pod trunk push MyLibrary.podspec

Das Flag --allow-warnings erlaubt die Veröffentlichung bei Vorhandensein von Warnungen. Standardmäßig blockieren Warnungen die Veröffentlichung. Wenn Ihre Bibliothek bekannte Warnungen hat, die die Funktionalität nicht beeinträchtigen, können Sie dieses Flag verwenden. Wichtig: Fehler blockieren die Veröffentlichung immer, unabhängig von den Flags.

Das Flag --synchronous macht die Anfrage synchron — das Terminal wartet auf den Abschluss der serverseitigen Validierung. Standardmäßig gibt der Befehl die Kontrolle sofort nach dem Senden zurück, und der Server verarbeitet die Veröffentlichung asynchron. Der synchrone Modus ist in CI/CD nützlich, wenn der nächste Pipeline-Schritt vom Erfolg der Veröffentlichung abhängt.

Das Flag --skip-import-validation überspringt die Überprüfung des Bibliotheksimports in ein Testprojekt. Dies beschleunigt die Veröffentlichung, garantiert jedoch nicht, dass die Bibliothek tatsächlich kompiliert. Verwenden Sie dieses Flag nur, wenn Sie sich der Build-Korrektheit sicher sind.

Beispiel einer Veröffentlichung mit typischen Optionen:

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

Nach erfolgreicher Veröffentlichung gibt Trunk ein JSON mit Details zurück:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Die Bibliothek steht zur Installation über Podfile in jedem iOS- oder macOS-Projekt zur Verfügung. Normalerweise wird der CocoaPods-Suchindex innerhalb weniger Minuten aktualisiert, in seltenen Fällen kann die Indizierung bis zu einer Stunde dauern.

Wichtige Einschränkung: Ein einmal veröffentlichter Pod kann nicht gelöscht werden. Dies dient dazu, Projekte, die diese Version bereits verwenden, nicht zu beschädigen. War die Veröffentlichung fehlerhaft, können Sie die nächste Version mit der Korrektur veröffentlichen, aber ein Rollback ist unmöglich. Die Ausnahme ist pod trunk delete, das nur CocoaPods-Mitarbeitern zur Verfügung steht und in extremen Fällen (Lizenzverletzung, bösartiger Code) angewendet wird.

Releases und Zugriff verwalten

CocoaPods Trunk bietet mehrere Befehle zur Verwaltung veröffentlichter Pods:

Besitzer hinzufügen

Um die Veröffentlichungsrechte eines Pods an einen anderen Entwickler zu übertragen, verwenden Sie den Befehl:

pod trunk add-owner MyLibrary developer@email.com

Nach der Ausführung erhält der neue Besitzer vollen Zugriff auf die Pod-Verwaltung: Veröffentlichen neuer Versionen, Hinzufügen und Entfernen anderer Besitzer, Markieren des Pods als veraltet. Jeder registrierte Trunk-Benutzer kann Besitzer sein — eine vorherige Registrierung ist erforderlich.

Besitzer entfernen

Wenn ein Entwickler das Projekt verlassen hat oder keinen Zugriff mehr auf den Pod haben sollte:

pod trunk remove-owner MyLibrary developer@email.com

Nur ein aktueller Besitzer kann einen Besitzer entfernen. Der letzte Besitzer eines Pods kann nicht entfernt werden — zuerst muss ein neuer hinzugefügt werden. Dies verhindert, dass ein Pod besitzerlos und verwahrlost wird.

Pod als veraltet markieren

Wenn eine Bibliothek nicht mehr gewartet wird, können Sie sie als veraltet (deprecated) markieren. Dies entfernt den Pod nicht aus der Registry, fügt aber eine Warnung für Benutzer bei der Installation hinzu:

pod trunk deprecate MyLibrary

Optional können Sie einen Ersatz-Pod angeben:

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

Bei der Installation eines veralteten Pods zeigt CocoaPods eine Warnung im Terminal an und empfiehlt, zum angegebenen Ersatz zu wechseln. Dies ist die korrekte Methode, um die Unterstützung einer Bibliothek zu beenden, ohne bestehende Projekt-Builds zu beschädigen.

Pod-Informationen anzeigen

Pod-Informationen sind über den Befehl pod trunk info verfügbar:

pod trunk info MyLibrary

Der Befehl zeigt alle Pod-Versionen, Veröffentlichungsdaten, die Besitzerliste und den Status (aktiv/veraltet) an. Um Details einer bestimmten Version anzuzeigen, verwenden Sie pod spec cat MyLibrary 0.1.0.

Fehler und Lösungen

Bei der Arbeit mit Trunk stoßen Entwickler häufig auf typische Fehler. Betrachten wir die häufigsten:

Authentifizierungsfehler

Symptom: [!] Authentication failed. You need to register a session first.
Ursache: Fehlendes oder abgelaufenes Sitzungstoken. Token haben eine begrenzte Gültigkeitsdauer (standardmäßig 30 Tage ohne Aktivität).
Lösung: Führen Sie erneut pod trunk register your@email.com 'Your Name' aus. Wenn Sie CI verwenden, überprüfen Sie die Aktualität der Umgebungsvariable COCOAPODS_TRUNK_TOKEN und generieren Sie bei Bedarf ein neues Token.

Versionskonflikt

Symptom: [!] You have already pushed version 0.1.0 for MyLibrary.
Ursache: Versuch der erneuten Veröffentlichung einer vorhandenen Version. Trunk erlaubt das Überschreiben von Versionen nicht.
Lösung: Erhöhen Sie die Version in der Podspec gemäß der semantischen Versionierung. Wenn Sie einen Fehler in der Podspec gemacht haben, veröffentlichen Sie die nächste Version mit der Korrektur.

Podspec-Validierungsfehler

Symptom: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Ursache: Falscher Pfad zu den Quelldateien im Feld source_files.
Lösung: Überprüfen Sie die Pfade in der Podspec, führen Sie pod lib lint lokal aus, bis alle Fehler behoben sind, und wiederholen Sie dann die Veröffentlichung. Verwenden Sie Glob-Muster: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Verbindungszeitüberschreitung

Symptom: [!] Connection to trunk.cocoapods.org failed. Timeout.
Ursache: Netzwerkprobleme oder vorübergehende Nichtverfügbarkeit des Trunk-Servers.
Lösung: Überprüfen Sie die Serververfügbarkeit: curl -I https://trunk.cocoapods.org. Wenn der Server antwortet, wiederholen Sie den Befehl in einigen Minuten. Ihre IP könnte blockiert sein — versuchen Sie es über eine andere Verbindung oder ein VPN.

Kein Zugriff auf den Pod

Symptom: [!] You do not have permission to push to MyLibrary.
Ursache: Sie sind nicht der Besitzer des Pods. Dies passiert, wenn jemand bereits einen Pod mit diesem Namen registriert hat.
Lösung: Kontaktieren Sie den aktuellen Pod-Besitzer (ermitteln Sie ihn über pod trunk info MyLibrary) und bitten Sie ihn, Sie über pod trunk add-owner hinzuzufügen. Wenn der Pod-Name vergeben ist, ziehen Sie einen alternativen Namen in Betracht.