Carthage: Was ist das, dezentraler Dependency-Manager

Was ist Carthage?

Carthage ist ein Dependency-Manager mit dezentraler Architektur, der 2014 von Entwicklern aus der Swift-Community erstellt wurde. Carthage verwendet keine zentrale Spezifikations-Registry — jede Bibliothek wird direkt aus einem Git-Repository per URL oder GitHub-Namen eingebunden. Carthage lädt den Quellcode herunter, erstellt daraus ein binäres Framework (.xcframework oder .framework) und stellt dem Entwickler ein fertiges Artefakt zur manuellen Integration in ein Xcode-Projekt zur Verfügung.

Die Architektur von Carthage umfasst drei Komponenten: das CLI-Tool carthage, die Konfigurationsdatei Cartfile und das Verzeichnis Carthage/Build/ mit den erstellten Frameworks. Der Hauptunterschied zwischen Carthage und CocoaPods ist das Fehlen automatischer Änderungen an .xcodeproj. Carthage erstellt kein .xcworkspace, konfiguriert keine Compiler-Flags und generiert kein Pods.xcconfig. Der Entwickler fügt die Frameworks manuell über Xcode zum Projekt hinzu, was volle Kontrolle über den Integrationsprozess bietet.

Carthage verwendet parallele Dependency-Builds, was den Prozess auf Mehrkernprozessoren erheblich beschleunigt. Jede Abhängigkeit wird als separates Target erstellt, und Carthage löst automatisch den Graphen transitiver Abhängigkeiten auf und erstellt sie in der richtigen Reihenfolge. Laut Community-Benchmarks erstellt Carthage 15–20 Abhängigkeiten in durchschnittlich 30–60 Sekunden auf modernen Macs, was für Projekte mit vielen Bibliotheken schneller ist als CocoaPods. Carthage unterstützt alle Apple-Plattformen: iOS, macOS, watchOS und tvOS, und seit Version 0.38+ — die Erstellung universeller .xcframework für Simulator- und Apple-Silicon-Geräteunterstützung.

Wie Carthage funktioniert

Carthage klont das Git-Repository jeder Abhängigkeit, wechselt zur angegebenen Version (Tag, Commit oder Branch) und führt xcodebuild aus, um das Framework zu erstellen. Carthage ermittelt automatisch den Xcode-Projekttyp (Framework, Dynamic Framework, Static Library) anhand des Build-Schemas. Wenn ein Projekt mehrere Schemas hat, verwendet Carthage das Standardschema (erstes in alphabetischer Reihenfolge). Nach dem Build kopiert Carthage das fertige Framework in Carthage/Build/ und erstellt eine Cartfile.resolved-Datei mit Fixierung genauer Versionen. Carthage unterstützt Caching erstellter Frameworks — ein erneuter Build ohne Änderungen an den Abhängigkeiten wird übersprungen.

Transitive Abhängigkeiten in Carthage werden über Cartfile.resolved verwaltet: Carthage erstellt einen Graphen aller benötigten Abhängigkeiten und baut sie in der richtigen Reihenfolge. Wenn zwei Bibliotheken von derselben Drittanbieter-Bibliothek abhängen, erstellt Carthage sie einmal und verwendet sie für beide. Carthage meldet Build-Fehler mit Angabe des spezifischen Targets und der Ursache — dies vereinfacht die Fehlerdiagnose.

Cartfile: Struktur, Syntax und Beispiele

Cartfile ist eine Konfigurationsdatei in Ruby-ähnlicher Syntax (Cartfile-Format), die die Abhängigkeiten eines Carthage-Projekts definiert. Cartfile befindet sich im Projektstammverzeichnis neben .xcodeproj. Jede Zeile des Cartfile beschreibt eine Abhängigkeit: die Quelle (Git-URL, GitHub-Repository) und die Version. Die Syntax unterstützt Versionsfixierung durch Tags, Commits und Branches.

# Basis-Abhängigkeiten Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Die Direktive github "Owner/Repo" ist eine Kurzform für GitHub-Repositories. Carthage erstellt automatisch die URL https://github.com/Owner/Repo.git. Für GitLab, Bitbucket und andere Git-Hosts wird die vollständige URL verwendet: git "https://gitlab.com/owner/repo.git". Versionsoperatoren: ~> 5.9 (jede Version von 5.9 bis 6.0, außer 6.0), == 8.0.0 (exakte Version), >= 1.0 (Mindestversion). Ein bestimmter Commit kann über github "owner/repo" "abc1234" fixiert werden.

Vollständiges Cartfile-Beispiel

Carthage unterstützt mehrere Verzeichnisse für verschiedene Konfigurationen: Cartfile (Hauptdatei), Cartfile.private (für interne, nicht veröffentlichte Abhängigkeiten) und Cartfile.resolved (automatisch generiert). Private Abhängigkeiten sind nützlich für Bibliotheken, die nur in Entwicklungs-Builds verwendet werden, wie Test-Frameworks.

# Cartfile — Hauptabhängigkeiten
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Vollständige URL für GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Entwicklungs-Branch
github "marmelroy/PhoneNumberKit" "development"

github und git sind zwei Quelltypen in Cartfile. Ersteres ist ausschließlich für GitHub und generiert automatisch die URL. Zweiteres ist für beliebige öffentliche oder private Git-Repositories mit vollständiger URL. Eine Version kann als Tag (== 2.1.1), semantischer Bereich (~> 5.9), Branch-Name ("development") oder Commit-Hash ("a1b2c3d") angegeben werden. Semantische Bereiche (~>) werden für Abhängigkeiten empfohlen, die SemVer folgen — dies schützt vor Breaking Changes bei Updates.

Cartfile.resolved wird automatisch nach carthage update generiert. Es fixiert die genauen Versionen aller installierten Abhängigkeiten, einschließlich transitiver. Diese Datei sollte in Git verwaltet werden — ohne sie wird der Befehl carthage bootstrap auf einem anderen Rechner die Bibliotheken nach denselben Regeln erstellen, aber die Versionen können abweichen. carthage outdated zeigt eine Liste veralteter Abhängigkeiten, für die neue Versionen verfügbar sind.

Installation und Konfiguration von Carthage

Carthage wird über Homebrew installiert — den Standard-Paketmanager für macOS. Alternative Methoden: Installation von einem erstellten .pkg-Installationsprogramm von GitHub oder Build aus dem Quellcode. Carthage benötigt Xcode mit Command Line Tools (einschließlich xcodebuild), und auf Apple Silicon Mac — Rosetta 2 für einige Legacy-Abhängigkeiten.

# Installation Carthage über Homebrew
brew install carthage

# Versionsprüfung
carthage version

# Installation über .pkg (wenn Homebrew nicht verfügbar ist)
# Herunterladen Carthage.pkg von GitHub Releases und manuell installieren

Nach der Installation von Carthage beginnt die Projektinitialisierung mit der Erstellung einer Cartfile im Projektstammverzeichnis. Carthage hat keinen init-Befehl — die Datei wird manuell in einem Texteditor erstellt. Nach dem Befüllen des Cartfile mit Abhängigkeiten führt der Entwickler carthage bootstrap (wenn Cartfile.resolved bereits existiert) oder carthage update (Erstinstallation oder Update) aus. Carthage klont die Repositories, erstellt die Frameworks und platziert sie in Carthage/Build/.

Aktualisierung von Carthage erfolgt über brew upgrade carthage. Die Version wird mit carthage version überprüft. Die neueste stabile Version Mitte 2025 ist 0.40 mit standardmäßiger .xcframework-Unterstützung, verbesserten parallelen Builds und vollständiger Swift 6-Unterstützung. Ab Version 0.39 hat Carthage aufgehört, Legacy-.framework ohne Kompatibilitäts-Shim zu erstellen — es wird empfohlen, explizit --use-xcframeworks anzugeben.

# Aktualisierung Carthage über Homebrew
brew upgrade carthage

# Bestimmte Version installieren
brew install carthage@0.39

# Komplette Neuinstallation
brew uninstall carthage && brew install carthage

Hinweis: Carthage erstellt kein .xcworkspace und ändert kein .xcodeproj. Im Gegensatz zu CocoaPods überlässt Carthage dem Entwickler die vollständige Kontrolle über die Xcode-Konfiguration. Das bedeutet, dass Sie nach der Installation der Abhängigkeiten die Frameworks manuell zu Xcode hinzufügen müssen (siehe Abschnitt «Integration von Carthage-Frameworks in Xcode»). Carthage erfordert außerdem, dass jede Abhängigkeit ein Xcode-Projekt oder Workspace mit einem Framework-Target enthält — andernfalls schlägt der Build fehl.

Framework-Build: bootstrap und update

Carthage bietet drei Hauptbefehle für die Arbeit mit Abhängigkeiten: bootstrap, update und build. carthage bootstrap erstellt Abhängigkeiten aus einer vorhandenen Cartfile.resolved — empfohlen für CI-Umgebungen und Entwickler, die zum Projekt stoßen. carthage update aktualisiert Cartfile.resolved auf die neuesten Versionen (unter Berücksichtigung der Cartfile-Einschränkungen) und führt den Build aus. carthage build erstellt alle angegebenen Abhängigkeiten ohne Versionen zu speichern.

# Erstinstallation (aktualisiert Versionen)
carthage update --use-xcframeworks --platform iOS

# Neubuild mit fixierten Versionen
carthage bootstrap --use-xcframeworks --platform iOS

# Nur eine Abhängigkeit erstellen
carthage build Alamofire --platform iOS

Das Flag --use-xcframeworks weist Carthage an, universelle .xcframework anstelle von Legacy-.framework zu erstellen. Dies gewährleistet Unterstützung sowohl für den Simulator als auch für ein echtes Gerät sowie für Apple Silicon Macs ohne zusätzliche Skripte. Das Flag --platform iOS beschränkt den Build auf eine einzelne iOS-Plattform — dies beschleunigt den Prozess erheblich, insbesondere wenn das Projekt plattformübergreifende Bibliotheken enthält.

Carthage unterstützt paralleles Bauen über das Flag --cache-builds, das bereits erstellte Frameworks zwischenspeichert. Bei einem erneuten Build überprüft Carthage den Git-Commit-Hash und überspringt die Kompilierung, wenn sich der Code nicht geändert hat. Für CI-Server wird empfohlen, das Verzeichnis Carthage/Build/ und ~/Library/Caches/carthage/ zwischenzuspeichern. Carthage unterstützt auch --verbose für detaillierte Protokollierung und --no-use-binaries für erzwungenes Bauen aus dem Quellcode (wenn der Entwickler vorab erstellten Binärdateien nicht vertraut).

Integration von Carthage-Frameworks in Xcode

Integration von Carthage-Frameworks in Xcode erfolgt manuell in vier Schritten. Nach dem Ausführen von carthage update oder bootstrap befinden sich alle erstellten Frameworks in Carthage/Build/iOS/ (oder der entsprechenden Plattform). Der Entwickler öffnet das Xcode-Projekt, wählt das App-Target aus und fügt die Frameworks in General → Frameworks, Libraries, and Embedded Content hinzu. Für Laufzeit-Frameworks (dynamische Bibliotheken) muss «Embed & Sign» ausgewählt werden — andernfalls stürzt die App beim Start mit dem Fehler «dyld: Library not loaded» ab.

Carthage für statische Bibliotheken ist einfacher — sie benötigen keine Einbettungsphase, da sie direkt in die ausführbare Datei der App eingebunden werden. Carthage erstellt jedoch standardmäßig dynamische Frameworks (außer bei explizit konfigurierten statischen Bibliotheken). Für Projekte, bei denen die Minimierung der App-Größe wichtig ist, wird eine statische Verknüpfung über die Xcode-Einstellungen empfohlen.

Ein zusätzlicher Schritt ist das Hinzufügen von Input Files in Build Phase → Run Script. Carthage benötigt ein Skript zum Entfernen von Simulator-Artefakten aus dem erstellten Framework (strip simulator architectures). Dieses Skript ist für App Store-Builds erforderlich:

# Run Script für App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthage erfordert keine Verwendung von .xcworkspace — alle Abhängigkeiten sind bereits in binäre Frameworks erstellt. Carthage arbeitet direkt mit .xcodeproj, im Gegensatz zu CocoaPods, das ein Workspace erstellt. Dies vereinfacht die Versionsverwaltung und CI-Einrichtung, da Carthage-Abhängigkeiten die Xcode-Projektkonfiguration nicht ändern. Die einzige Änderung ist das Hinzufügen von Frameworks zum Target, das in .pbxproj aufgezeichnet wird.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods und Swift Package Manager (SPM) sind die drei wichtigsten Dependency-Manager in der iOS-Entwicklung. Carthage zeichnet sich durch seinen dezentralen Ansatz aus, CocoaPods bietet eine zentrale Registry, und SPM ist die integrierte Lösung von Apple. Die Wahl zwischen ihnen hängt von den Projektanforderungen, der Teamgröße und dem gewünschten Automatisierungsgrad ab.

Carthage wird für Projekte gewählt, die minimale Eingriffe in die Xcode-Konfiguration und volle Kontrolle über den Integrationsprozess erfordern. Carthage ist ideal für Open-Source-Bibliotheken und Frameworks, bei denen der Autor den Benutzern die Freiheit geben möchte, Abhängigkeiten unabhängig zu erstellen. Carthage ist auch bei Entwicklern beliebt, die die UNIX-Philosophie schätzen: Jedes Werkzeug macht eine Sache gut. CocoaPods bleibt der Standard für Unternehmensprojekte mit Dutzenden von Abhängigkeiten, bei denen Automatisierung wichtig ist. SPM ist die Wahl für neue Projekte, da es in Xcode integriert ist und aktiv von Apple entwickelt wird.

Migration zwischen den Managern erfordert unterschiedliche Ansätze. Carthage → SPM: Frameworks aus Xcode entfernen, Cartfile löschen und Package Dependencies über File → Add Package Dependencies hinzufügen. Carthage → CocoaPods: Carthage-Frameworks entfernen, Podfile erstellen, Abhängigkeiten hinzufügen und pod init && pod install ausführen. Bei der Migration von Carthage zu CocoaPods oder SPM entfällt die Notwendigkeit, Frameworks manuell zu aktualisieren — alle Abhängigkeiten werden mit einem einzigen Befehl aktualisiert. Carthage bleibt relevant für Projekte, bei denen es wichtig ist, Vendor-Lock-In zu vermeiden und die Transparenz des Dependency-Builds zu wahren.

Häufige Probleme und ihre Lösungen

Carthage ist ein stabiles Werkzeug, aber Entwickler stoßen regelmäßig auf typische Probleme, insbesondere beim Bauen auf CI-Servern, beim Aktualisieren von Xcode oder beim Wechseln von Swift-Versionen. Die meisten Probleme werden durch Löschen des Caches, korrekte Konfiguration von --use-xcframeworks und Überprüfung der Mindest-iOS-Version gelöst.

Fehler «The file manager returned an error» — tritt auf, wenn der Carthage-Cache beschädigt ist oder ein Dateiberechtigungskonflikt vorliegt. Lösung: Cache mit rm -rf ~/Library/Caches/carthage löschen und carthage bootstrap neu starten. Hilfreich ist auch das Löschen des Carthage/-Verzeichnisses im Projekt und ein Neubuild. Auf CI-Servern sollte der Carthage-Cache nur aktualisiert werden, wenn sich Cartfile.resolved ändert.

Fehler «No such module» — das Framework wird in Xcode nicht gefunden, obwohl der Carthage-Build erfolgreich war. Lösung: Den Framework-Pfad in General → Frameworks, Libraries, and Embedded Content überprüfen. Das Framework sollte in Carthage/Build/iOS/ sein. Sicherstellen, dass .xcframework korrekt hinzugefügt wurde (erneut ziehen). Bei dynamischen Frameworks Embed & Sign überprüfen. Wenn der Fehler bestehen bleibt, FRAMEWORK_SEARCH_PATHS in Build Settings hinzufügen.

Build-Fehler aufgrund von Swift-Inkompatibilität — die Bibliothek wurde für eine andere Swift-Version als das Projekt erstellt. Lösung: carthage update --no-use-binaries verwenden, um das Bauen aus dem Quellcode mit derselben Swift-Version zu erzwingen. Wenn die Bibliothek unter der aktuellen Version nicht kompiliert, .xcconfig zur Angabe der Swift-Version verwenden oder die Bibliothek forken. Seit Carthage 0.39 fügt --use-xcframeworks automatisch die richtige Swift-Version in die Binärdatei ein.

CI-Build-Probleme — Carthage auf CI erfordert eine korrekte Cache-Konfiguration. Lösung: Carthage/Build/ und ~/Library/Caches/carthage/ zwischenspeichern. Auf CI statt update carthage bootstrap --use-xcframeworks --platform iOS verwenden, um Versionsänderungen zu vermeiden. Eine offizielle Carthage-Aktion ist für GitHub Actions verfügbar. Für Jenkins — das CarthageBuild-Plugin. Carthage kann auf macOS ohne GUI abstürzen — Lösung: brew install xcode-build-server installieren oder das Flag -UseModernBuildSystem=NO hinzufügen.