Carthage: wat is het, gedecentraliseerde dependency manager

Wat is Carthage?

Carthage — een dependency manager met gedecentraliseerde architectuur, gemaakt in 2014 door ontwikkelaars uit de Swift-gemeenschap. Carthage gebruikt geen centraal specificatieregister — elke bibliotheek wordt rechtstreeks uit een Git-repository aangesloten via URL of naam op GitHub. Carthage downloadt de broncode, bouwt deze tot een binair framework (.xcframework of .framework) en levert de ontwikkelaar een kant-en-klaar artefact voor handmatige integratie in het Xcode-project.

De architectuur van Carthage omvat drie componenten: het CLI-hulpprogramma carthage, het configuratiebestand Cartfile en de map Carthage/Build/ met gebouwde frameworks. Het principiële verschil tussen Carthage en CocoaPods is het ontbreken van automatische wijziging van .xcodeproj. Carthage maakt geen .xcworkspace aan, configureert geen compilerflags en genereert geen Pods.xcconfig. De ontwikkelaar voegt frameworks handmatig aan het project toe via Xcode, wat volledige controle over het integratieproces geeft.

Carthage gebruikt parallel bouwen van dependencies, wat het proces aanzienlijk versnelt op multi-core processoren. Elke dependency wordt gebouwd als een apart target en Carthage lost automatisch de graaf van transitieve dependencies op door ze in de juiste volgorde te bouwen. Volgens community benchmarks bouwt Carthage 15-20 dependencies gemiddeld in 30-60 seconden op moderne Macs, wat sneller is dan CocoaPods voor projecten met veel bibliotheken. Carthage ondersteunt alle Apple-platforms: iOS, macOS, watchOS en tvOS, en vanaf versie 0.38+ — het bouwen van universele .xcframework voor ondersteuning van simulatoren en Apple Silicon-apparaten.

Hoe Carthage werkt

Carthage kloont de Git-repository van elke dependency, schakelt over naar de opgegeven versie (tag, commit of branch) en start xcodebuild om het framework te bouwen. Carthage bepaalt het type Xcode-project (framework, dynamic framework, statische bibliotheek) automatisch aan de hand van het buildschema. Als het project meerdere schema's bevat, gebruikt Carthage het standaardschema (eerste in alfabetische volgorde). Na het bouwen kopieert Carthage het voltooide framework naar Carthage/Build/ en maakt het bestand Cartfile.resolved aan met de exacte versies. Carthage ondersteunt caching van gebouwde frameworks — herbouwen zonder dependencywijzigingen wordt niet uitgevoerd.

Transitieve dependencies in Carthage worden afgehandeld via Cartfile.resolved: Carthage bouwt een graaf van alle benodigde dependencies en bouwt ze in de juiste volgorde. Als twee bibliotheken afhankelijk zijn van dezelfde externe bibliotheek, bouwt Carthage deze eenmalig en gebruikt deze voor beide. Carthage meldt buildfouten met vermelding van het specifieke target en de oorzaak — dit vereenvoudigt het diagnosticeren van problemen.

Cartfile: structuur, syntax en voorbeelden

Cartfile — een configuratiebestand in de taal Ruby (Cartfile-indeling) dat de dependencies van een Carthage-project definieert. Cartfile bevindt zich in de projectroot naast .xcodeproj. Elke regel in Cartfile beschrijft één dependency: bron (Git-URL, GitHub-repository) en versie. De syntax ondersteunt het vastleggen van versies via tags, commits en branches.

# Basisafhankelijkheden Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Het directive github "Owner/Repo" — een verkorte vorm voor GitHub-repository's. Carthage genereert automatisch de URL in de vorm https://github.com/Owner/Repo.git. Voor GitLab, Bitbucket en andere Git-hosts wordt de volledige URL gebruikt: git "https://gitlab.com/owner/repo.git". Versieoperators: ~> 5.9 (elke versie van 5.9 tot 6.0 exclusief 6.0), == 8.0.0 (exacte versie), >= 1.0 (minimale versie). Een specifieke commit kan worden aangesloten via github "owner/repo" "abc1234".

Volledig voorbeeld van Cartfile

Carthage ondersteunt meerdere mappen voor verschillende configuraties: Cartfile(hoofd), Cartfile.private (voor interne, niet-gepubliceerde dependencies) en Cartfile.resolved (automatisch gegenereerd). Private dependencies zijn nuttig voor bibliotheken die alleen in Development-builds worden gebruikt, zoals testframeworks.

# Cartfile — belangrijkste afhankelijkheden
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Volledige URL voor GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Ontwikkelingsbranch
github "marmelroy/PhoneNumberKit" "development"

github en git — twee soorten bronnen in Cartfile. De eerste is uitsluitend bedoeld voor GitHub en genereert automatisch de URL. De tweede — voor elke openbare of privé Git-repository met volledige URL. De versie kan worden opgegeven met een tag (== 2.1.1), semantisch bereik (~> 5.9), branchnaam ("development") of commit-hash ("a1b2c3d"). Het gebruik van semantische bereiken (~>) wordt aanbevolen voor dependencies die SemVer volgen — dit beschermt tegen breaking changes bij bijwerken.

Cartfile.resolved wordt automatisch gegenereerd na carthage update. Het legt de exacte versies vast van alle geïnstalleerde dependencies, inclusief transitieve. Het bestand moet in Git worden bewaard — zonder dit commando zal carthage bootstrap op een andere machine bibliotheken volgens dezelfde regels bouwen, maar de versies kunnen verschillen. carthage outdated toont een lijst van verouderde dependencies waarvoor nieuwe versies beschikbaar zijn.

Carthage installeren en configureren

Carthage wordt geïnstalleerd via Homebrew — de standaard pakketbeheerder voor macOS. Alternatieve methoden: installatie via het kant-en-klare .pkg-installatieprogramma van GitHub of bouwen uit broncode. Carthage vereist Xcode met Command Line Tools (inclusief xcodebuild), en op Apple Silicon Mac — Rosetta 2 voor sommige oudere dependencies.

# Installatie Carthage via Homebrew
brew install carthage

# Versie controleren
carthage version

# Installatie vanaf .pkg (als Homebrew niet beschikbaar is)
# Download Carthage.pkg van GitHub Releases en handmatig installeren

Na installatie begint de initialisatie van een Carthage-project met het aanmaken van Cartfile in de projectroot. Carthage heeft geen init-commando — het bestand wordt handmatig in een teksteditor aangemaakt. Na het vullen van Cartfile met dependencies, start de ontwikkelaar carthage bootstrap (als Cartfile.resolved al bestaat) of carthage update (eerste installatie of bijwerken). Carthage kloont repository's, bouwt frameworks en plaatst ze in Carthage/Build/.

Bijwerken van Carthage gebeurt via brew upgrade carthage. De versie wordt gecontroleerd met het commando carthage version. De laatste stabiele versie medio 2025 — 0.40 met standaard ondersteuning voor .xcframework, verbeterd parallel bouwen en volledige ondersteuning voor Swift 6. Vanaf versie 0.39 is Carthage gestopt met het bouwen van verouderde .framework zonder compatibiliteitsbrug — het wordt aanbevolen om expliciet --use-xcframeworks op te geven.

# Bijwerken Carthage via Homebrew
brew upgrade carthage

# Specifieke versie installeren
brew install carthage@0.39

# Volledige herinstallatie
brew uninstall carthage && brew install carthage

Let op: Carthage maakt geen .xcworkspace aan en wijzigt .xcodeproj niet. In tegenstelling tot CocoaPods laat Carthage volledige controle over de Xcode-configuratie aan de ontwikkelaar. Dit betekent dat na installatie van dependencies de frameworks handmatig in Xcode moeten worden toegevoegd (zie sectie «Carthage-frameworks integreren in Xcode»). Carthage vereist ook dat elke dependency een Xcode-project of workspace met een framework-target bevat — anders mislukt het bouwen.

Frameworks bouwen: bootstrap en update

Carthage biedt drie hoofdcommando's voor het werken met dependencies: bootstrap, update en build. carthage bootstrap bouwt dependencies uit bestaande Cartfile.resolved — aanbevolen voor CI-omgevingen en ontwikkelaars die zich bij het project voegen. carthage update werkt Cartfile.resolved bij naar de nieuwste versies (rekening houdend met Cartfile-beperkingen) en voert het bouwen uit. carthage build bouwt alle opgegeven dependencies zonder versies vast te leggen.

# Eerste installatie (werkt versies bij)
carthage update --use-xcframeworks --platform iOS

# Herbouwen volgens vaste versies
carthage bootstrap --use-xcframeworks --platform iOS

# Slechts één dependency bouwen
carthage build Alamofire --platform iOS

De vlag --use-xcframeworks geeft Carthage de opdracht om universele .xcframework te bouwen in plaats van verouderde .framework. Dit zorgt voor ondersteuning van zowel de simulator als het echte apparaat, evenals Apple Silicon Mac zonder extra scripts. De vlag --platform iOS beperkt het bouwen tot één iOS-platform — dit versnelt het proces aanzienlijk, vooral als er cross-platform bibliotheken in het project zijn opgegeven.

Carthage ondersteunt parallel bouwen via de vlag --cache-builds, die reeds gebouwde frameworks cached. Bij herbouwen controleert Carthage de Git commit-hash en slaat compilatie over als de code niet is gewijzigd. Voor CI-servers wordt aanbevolen de mappen Carthage/Build/ en ~/Library/Caches/carthage/ te cachen. Carthage ondersteunt ook --verbose voor gedetailleerde logging en --no-use-binaries voor geforceerd bouwen uit broncode (als de ontwikkelaar vooraf gebouwde binaries niet vertrouwt).

Carthage-frameworks integreren in Xcode

Integratie van Carthage-frameworks in Xcode wordt handmatig in vier stappen uitgevoerd. Na het uitvoeren van carthage update of bootstrap bevinden alle gebouwde frameworks zich in Carthage/Build/iOS/ (of het bijbehorende platform). De ontwikkelaar opent het Xcode-project, selecteert het app-target en voegt frameworks toe in General → Frameworks, Libraries, and Embedded Content. Voor runtime-frameworks (dynamische bibliotheken) moet «Embed & Sign» worden geselecteerd — anders crasht de app bij het starten met de fout «dyld: Library not loaded».

Carthage voor statische bibliotheken werkt eenvoudiger — ze vereisen geen embed-fase omdat ze rechtstreeks worden gekoppeld aan het uitvoerbare bestand van de app. Carthage bouwt echter standaard dynamische frameworks (behalve expliciet geconfigureerde statische bibliotheken). Voor projecten waar het minimaliseren van de app-grootte belangrijk is, wordt aanbevolen statische koppeling te gebruiken via Xcode-instellingen.

Extra stap — Input Files toevoegen in Build Phase → Run Script. Carthage vereist een script voor het verwijderen van simulatorartefacten uit het gebouwde framework (strip simulator architectures). Dit script is noodzakelijk voor App Store-builds:

# Run Script voor 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 vereist geen gebruik van .xcworkspace — alle dependencies zijn reeds gebouwd tot binaire frameworks. Carthage werkt rechtstreeks met .xcodeproj, in tegenstelling tot CocoaPods dat een workspace aanmaakt. Dit vereenvoudigt versiebeheer en CI-configuratie, omdat Carthage-dependencies de Xcode-projectconfiguratie niet wijzigen. De enige wijziging — het toevoegen van frameworks aan het target, wat wordt vastgelegd in .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods en Swift Package Manager (SPM) — de drie belangrijkste dependency managers in iOS-ontwikkeling. Carthage onderscheidt zich door een gedecentraliseerde aanpak, CocoaPods biedt een gecentraliseerd register, SPM — een ingebouwde oplossing van Apple. De keuze tussen hen hangt af van de projectvereisten, teamgrootte en het vereiste automatiseringsniveau.

Carthage wordt gekozen voor projecten waar minimale inmenging in de Xcode-configuratie en volledige controle over het integratieproces vereist zijn. Carthage is ideaal voor open bibliotheken en frameworks, waar de auteur gebruikers de mogelijkheid wil geven om dependencies zelf te bouwen. Carthage is ook populair in de gemeenschap van ontwikkelaars die de UNIX-filosofie waarderen: elk hulpmiddel doet één ding goed. CocoaPods blijft de standaard voor bedrijfsprojecten met tientallen dependencies waar automatisering belangrijk is. SPM — de keuze voor nieuwe projecten, omdat het is ingebouwd in Xcode en actief wordt ontwikkeld door Apple.

Migratie tussen managers vereist een verschillende aanpak. Carthage → SPM: verwijder frameworks uit Xcode, verwijder Cartfile en voeg Package Dependencies toe via File → Add Package Dependencies. Carthage → CocoaPods: verwijder Carthage-frameworks, maak Podfile aan, voeg dependencies toe en voer pod init && pod install uit. Bij migratie van Carthage naar CocoaPods of SPM verdwijnt de noodzaak om frameworks handmatig bij te werken — alle dependencies worden met één commando bijgewerkt. Carthage blijft relevant voor projecten waar het belangrijk is om vendor lock-in te vermijden en transparantie van dependency building te behouden.

Veelvoorkomende problemen en oplossingen

Carthage — een stabiel hulpmiddel, maar ontwikkelaars komen af en toe typische problemen tegen, vooral bij het bouwen op CI-servers, het bijwerken van Xcode of het wijzigen van Swift-versies. De meeste problemen worden opgelost door het wissen van de cache, correcte configuratie van --use-xcframeworks en controle van de minimale iOS-versie.

Fout «The file manager returned an error» — treedt op bij beschadiging van de Carthage-cache of bestandsrechtenconflict. Oplossing: verwijder de cache met het commando rm -rf ~/Library/Caches/carthage en herstart carthage bootstrap. Ook het verwijderen van de map Carthage/ in het project en herbouwen helpt. Op CI-servers moet de Carthage-cache alleen worden bijgewerkt bij wijziging van Cartfile.resolved.

Fout «No such module» — framework niet gevonden in Xcode, hoewel Carthage-build succesvol was. Oplossing: controleer het framework-pad in General → Frameworks, Libraries, and Embedded Content. Het framework moet in Carthage/Build/iOS/ staan. Zorg ervoor dat .xcframework correct is toegevoegd (opnieuw slepen). Voor dynamische frameworks controleer Embed & Sign. Als de fout aanhoudt — voeg FRAMEWORK_SEARCH_PATHS toe in Build Settings.

Bouwfout door Swift-incompatibiliteit — bibliotheek gebouwd voor een andere Swift-versie dan het project. Oplossing: gebruik carthage update --no-use-binaries voor geforceerd bouwen uit broncode met dezelfde Swift-versie. Als de bibliotheek niet compileert onder de huidige versie — gebruik .xcconfig om de Swift-versie op te geven of fork de bibliotheek. Sinds Carthage 0.39 bevat --use-xcframeworks automatisch de juiste Swift-versie in de binary.

Problemen met CI-build — Carthage op CI vereist correcte cachingconfiguratie. Oplossing: cache Carthage/Build/ en ~/Library/Caches/carthage/. Gebruik carthage bootstrap --use-xcframeworks --platform iOS in plaats van update op CI om versies niet te wijzigen. Voor GitHub Actions is een officiële Carthage-actie beschikbaar. Voor Jenkins — de CarthageBuild-plugin. Carthage kan crashen op macOS zonder GUI — oplossing: installeer brew install xcode-build-server of voeg de sleutel -UseModernBuildSystem=NO toe.