Carthage: vad är det, decentraliserad beroendehanterare

Vad är Carthage?

Carthage — en beroendehanterare med decentraliserad arkitektur, skapad 2014 av utvecklare från Swift-gemenskapen. Carthage använder inget centralt specifikationsregister — varje bibliotek ansluts direkt från Git-förvaret via URL eller namn på GitHub. Carthage laddar ner källkoden, bygger den till ett binärt ramverk (.xcframework eller .framework) och ger utvecklaren en färdig artefakt för manuell integration i Xcode-projektet.

Carthages arkitektur omfattar tre komponenter: CLI-verktyget carthage, konfigurationsfilen Cartfile och katalogen Carthage/Build/ med byggda ramverk. Den principiella skillnaden mellan Carthage och CocoaPods — frånvaron av automatisk modifiering av .xcodeproj. Carthage skapar inte .xcworkspace, konfigurerar inte kompilatorflaggor och genererar inte Pods.xcconfig. Utvecklaren lägger själv till ramverken i projektet via Xcode, vilket ger full kontroll över integrationsprocessen.

Carthage använder parallellbyggen av beroenden, vilket avsevärt snabbar upp processen på flerkärniga processorer. Varje beroende byggs som ett separat mål och Carthage löser automatiskt grafen av transitiva beroenden genom att bygga dem i rätt ordning. Enligt communityns mätningar bygger Carthage 15–20 beroenden i genomsnitt på 30–60 sekunder på moderna Mac-datorer, vilket är snabbare än CocoaPods för projekt med många bibliotek. Carthage stöder alla Apple-plattformar: iOS, macOS, watchOS och tvOS, och från version 0.38+ — byggande av universella .xcframework för stöd av simulatorer och Apple Silicon-enheter.

Hur Carthage fungerar

Carthage klonar Git-förvaret för varje beroende, växlar till den angivna versionen (tagg, commit eller gren) och startar xcodebuild för att bygga ramverket. Carthage bestämmer typen av Xcode-projekt (ramverk, dynamiskt ramverk, statiskt bibliotek) automatiskt enligt byggschemat. Om projektet innehåller flera scheman använder Carthage standardschemat (första i alfabetisk ordning). Efter bygget kopierar Carthage det färdiga ramverket till Carthage/Build/ och skapar filen Cartfile.resolved med fastställande av exakta versioner. Carthage stöder cachelagring av byggda ramverk — ombyggnad utan ändringar av beroenden utförs inte.

Transitiva beroenden i Carthage hanteras via Cartfile.resolved: Carthage bygger en graf över alla nödvändiga beroenden och bygger dem i rätt ordning. Om två bibliotek är beroende av samma tredjepartsbibliotek bygger Carthage det en gång och använder det för båda. Carthage meddelar byggfel med angivande av specifikt mål och orsak — detta förenklar diagnos av problem.

Cartfile: struktur, syntax och exempel

Cartfile — en konfigurationsfil på språket Ruby (Cartfile-format) som definierar beroenden för ett Carthage-projekt. Cartfile finns i projektroten bredvid .xcodeproj. Varje rad i Cartfile beskriver ett beroende: källa (Git-URL, GitHub-förvar) och version. Syntaxen stöder fastställande av versioner via taggar, commits och grenar.

# Grundläggande beroenden Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Direktivet github "Owner/Repo" — förkortad form för GitHub-förvar. Carthage skapar automatiskt URL i formen https://github.com/Owner/Repo.git. För GitLab, Bitbucket och andra Git-värdar används fullständig URL: git "https://gitlab.com/owner/repo.git". Versionsoperatorer: ~> 5.9 (valfri version från 5.9 till 6.0 exklusive 6.0), == 8.0.0 (exakt version), >= 1.0 (minsta version). Anslutning av en specifik commit kan göras via github "owner/repo" "abc1234".

Fullständigt exempel på Cartfile

Carthage stöder flera kataloger för olika konfigurationer: Cartfile(huvud), Cartfile.private (för interna, icke-publicerade beroenden) och Cartfile.resolved (genereras automatiskt). Privata beroenden är användbara för bibliotek som endast används i Development-byggen, till exempel testramverk.

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

# Fullständig URL för GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Utvecklingsgren
github "marmelroy/PhoneNumberKit" "development"

github och git — två typer av källor i Cartfile. Den första är avsedd enbart för GitHub och skapar automatiskt URL. Den andra — för alla offentliga eller privata Git-förvar med fullständig URL. Versionen kan anges med tagg (== 2.1.1), semantiskt intervall (~> 5.9), grennamn ("development") eller commit-hash ("a1b2c3d"). Användning av semantiska intervall (~>) rekommenderas för beroenden som följer SemVer — detta skyddar mot brytande ändringar vid uppdatering.

Cartfile.resolved genereras automatiskt efter carthage update. Den fastställer exakta versioner av alla installerade beroenden, inklusive transitiva. Filen bör förvaras i Git — utan den kommer kommandot carthage bootstrap på en annan maskin att bygga bibliotek enligt samma regler, men versionerna kan skilja sig. carthage outdated visar en lista över föråldrade beroenden för vilka nya versioner finns tillgängliga.

Installera och konfigurera Carthage

Carthage installeras via Homebrew — standardpakethanteraren för macOS. Alternativa metoder: installation från den färdiga .pkg-installationsprogrammet från GitHub eller bygga från källkod. Carthage kräver Xcode med Command Line Tools (inklusive xcodebuild), och på Apple Silicon Mac — Rosetta 2 för vissa äldre beroenden.

# Installation Carthage via Homebrew
brew install carthage

# Kontrollera version
carthage version

# Installation från .pkg (om Homebrew inte är tillgängligt)
# Ladda ner Carthage.pkg från GitHub Releases och installera manuellt

Efter installation börjar initialiseringen av ett Carthage-projekt med att skapa Cartfile i projektroten. Carthage har inget init-kommando — filen skapas manuellt i en textredigerare. Efter att ha fyllt Cartfile med beroenden startar utvecklaren carthage bootstrap (om Cartfile.resolved redan finns) eller carthage update (första installation eller uppdatering). Carthage klonar förvar, bygger ramverk och placerar dem i Carthage/Build/.

Uppdatering av Carthage görs via brew upgrade carthage. Versionen kontrolleras med kommandot carthage version. Den senaste stabila versionen i mitten av 2025 — 0.40 med standardstöd för .xcframework, förbättrat parallellbyggande och fullt stöd för Swift 6. Från och med version 0.39 slutade Carthage att bygga föråldrade .framework utan kompatibilitetsbrygga — det rekommenderas att explicit ange --use-xcframeworks.

# Uppdatering Carthage via Homebrew
brew upgrade carthage

# Installera specifik version
brew install carthage@0.39

# Fullständig ominstallation
brew uninstall carthage && brew install carthage

Observera: Carthage skapar inte .xcworkspace och ändrar inte .xcodeproj. Till skillnad från CocoaPods lämnar Carthage full kontroll över Xcode-konfigurationen till utvecklaren. Detta innebär att efter installation av beroenden måste man manuellt lägga till ramverken i Xcode (se avsnittet «Integrera Carthage-ramverk i Xcode»). Carthage kräver också att varje beroende innehåller ett Xcode-projekt eller workspace med ett ramverksmål — annars misslyckas bygget.

Bygga ramverk: bootstrap och update

Carthage erbjuder tre huvudkommandon för att arbeta med beroenden: bootstrap, update och build. carthage bootstrap bygger beroenden från befintlig Cartfile.resolved — rekommenderas för CI-miljöer och utvecklare som ansluter till projektet. carthage update uppdaterar Cartfile.resolved till de senaste versionerna (med hänsyn till Cartfile-begränsningar) och utför bygget. carthage build bygger alla angivna beroenden utan att spara versioner.

# Första installationen (uppdaterar versioner)
carthage update --use-xcframeworks --platform iOS

# Ombyggnad enligt fastställda versioner
carthage bootstrap --use-xcframeworks --platform iOS

# Bygg endast ett beroende
carthage build Alamofire --platform iOS

Flaggan --use-xcframeworks instruerar Carthage att bygga universella .xcframework istället för föråldrade .framework. Detta säkerställer stöd för både simulatorn och den verkliga enheten, samt Apple Silicon Mac utan ytterligare skript. Flaggan --platform iOS begränsar bygget till en enda iOS-plattform — detta snabbar avsevärt upp processen, särskilt om projektet innehåller plattformsoberoende bibliotek.

Carthage stöder parallellbyggen via flaggan --cache-builds, som cachelagrar redan byggda ramverk. Vid ombyggnad kontrollerar Carthage Git commit-hash och om koden inte har ändrats hoppar den över kompileringen. För CI-servrar rekommenderas att cachelagra katalogen Carthage/Build/ och ~/Library/Caches/carthage/. Carthage stöder också --verbose för detaljerad loggning och --no-use-binaries för tvingat bygge från källkod (om utvecklaren inte litar på förbyggda binärer).

Integrera Carthage-ramverk i Xcode

Integration av Carthage-ramverk i Xcode görs manuellt i fyra steg. Efter att ha utfört carthage update eller bootstrap finns alla byggda ramverk i Carthage/Build/iOS/ (eller motsvarande plattform). Utvecklaren öppnar Xcode-projektet, väljer applikationsmål och lägger till ramverken i General → Frameworks, Libraries, and Embedded Content. För körningsramverk (dynamiska bibliotek) måste «Embed & Sign» väljas — annars kraschar appen vid start med felet «dyld: Library not loaded».

Carthage för statiska bibliotek fungerar enklare — de kräver ingen embed-fas eftersom de länkas direkt till applikationens körbara fil. Carthage bygger dock som standard dynamiska ramverk (förutom explicit konfigurerade statiska bibliotek). För projekt där det är viktigt att minimera applikationsstorleken rekommenderas statisk länkning via Xcode-inställningar.

Ytterligare steg — lägg till Input Files i Build Phase → Run Script. Carthage kräver ett skript för att ta bort simulatorartefakter från det byggda ramverket (strip simulator architectures). Detta skript är nödvändigt för App Store-byggen:

# 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 kräver inte användning av .xcworkspace — alla beroenden är redan byggda till binära ramverk. Carthage arbetar direkt med .xcodeproj, till skillnad från CocoaPods som skapar workspace. Detta förenklar versionshantering och CI-konfiguration eftersom Carthage-beroenden inte ändrar Xcode-projektets konfiguration. Den enda ändringen — tillägg av ramverk till målet, som registreras i .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods och Swift Package Manager (SPM) — de tre huvudsakliga beroendehanterarna inom iOS-utveckling. Carthage utmärker sig genom ett decentraliserat tillvägagångssätt, CocoaPods erbjuder ett centraliserat register, SPM — en inbyggd lösning från Apple. Valet mellan dem beror på projektkraven, teamstorleken och den önskade automatiseringsnivån.

Carthage väljs för projekt där minimal inblandning i Xcode-konfigurationen och fullständig kontroll över integrationsprocessen krävs. Carthage är idealiskt för öppna bibliotek och ramverk, där författaren vill ge användarna möjlighet att själva bygga beroenden. Carthage är också populärt i utvecklargemenskapen som värdesätter UNIX-filosofin: varje verktyg gör en sak bra. CocoaPods förblir standarden för företagsprojekt med dussintals beroenden där automatisering är viktig. SPM — valet för nya projekt, eftersom det är inbyggt i Xcode och aktivt utvecklas av Apple.

Migrering mellan hanterare kräver olika tillvägagångssätt. Carthage → SPM: ta bort ramverken från Xcode, ta bort Cartfile och lägg till Package Dependencies via File → Add Package Dependencies. Carthage → CocoaPods: ta bort Carthage-ramverken, skapa Podfile, lägg till beroenden och utför pod init && pod install. Vid migrering från Carthage till CocoaPods eller SPM försvinner behovet av manuell uppdatering av ramverk — alla beroenden uppdateras med ett kommando. Carthage förblir relevant för projekt där det är viktigt att undvika vendor lock-in och bibehålla transparens i beroendebyggandet.

Vanliga problem och lösningar

Carthage — ett stabilt verktyg, men utvecklare stöter då och då på typiska problem, särskilt vid byggen på CI-servrar, uppdatering av Xcode eller byte av Swift-versioner. De flesta problem löses genom att rensa cacheminnet, korrekt konfiguration av --use-xcframeworks och kontroll av minsta iOS-version.

Fel «The file manager returned an error» — uppstår vid skada på Carthage-cachen eller konflikt om filrättigheter. Lösning: ta bort cachen med kommandot rm -rf ~/Library/Caches/carthage och starta om carthage bootstrap. Att ta bort katalogen Carthage/ i projektet och bygga om hjälper också. På CI-servrar bör Carthage-cachen endast uppdateras vid ändring av Cartfile.resolved.

Fel «No such module» — ramverket hittades inte i Xcode, trots att Carthage-bygget lyckades. Lösning: kontrollera ramverkets sökväg i General → Frameworks, Libraries, and Embedded Content. Ramverket bör finnas i Carthage/Build/iOS/. Se till att .xcframework har lagts till korrekt (dra det igen). För dynamiska ramverk kontrollera Embed & Sign. Om felet kvarstår — lägg till FRAMEWORK_SEARCH_PATHS i Build Settings.

Byggfel på grund av Swift-inkompatibilitet — biblioteket är byggt för en annan Swift-version än projektet. Lösning: använd carthage update --no-use-binaries för tvingat bygge från källkod med samma Swift-version. Om biblioteket inte kompileras under den aktuella versionen — använd .xcconfig för att ange Swift-version eller forka biblioteket. Från Carthage 0.39 inkluderar --use-xcframeworks automatiskt rätt Swift-version i binären.

Problem med CI-bygge — Carthage på CI kräver korrekt cachekonfiguration. Lösning: cachelagra Carthage/Build/ och ~/Library/Caches/carthage/. Använd carthage bootstrap --use-xcframeworks --platform iOS istället för update på CI för att inte ändra versioner. För GitHub Actions finns en officiell Carthage-action. För Jenkins — pluginprogrammet CarthageBuild. Carthage kan krascha på macOS utan GUI — lösning: installera brew install xcode-build-server eller lägg till nyckeln -UseModernBuildSystem=NO.