Carthage : qu'est-ce que c'est, gestionnaire de dépendances décentralisé

Qu'est-ce que Carthage ?

Carthage est un gestionnaire de dépendances à architecture décentralisée, créé en 2014 par des développeurs de la communauté Swift. Carthage n'utilise pas de registre central de spécifications — chaque bibliothèque est connectée directement depuis un dépôt Git via une URL ou un nom GitHub. Carthage télécharge le code source, le compile en un framework binaire (.xcframework ou .framework) et fournit au développeur un artefact prêt pour une intégration manuelle dans un projet Xcode.

L'architecture de Carthage comprend trois composants : l'outil CLI carthage, le fichier de configuration Cartfile et le répertoire Carthage/Build/ avec les frameworks construits. La différence clé entre Carthage et CocoaPods est l'absence de modification automatique du .xcodeproj. Carthage ne crée pas de .xcworkspace, ne configure pas de flags de compilateur et ne génère pas de Pods.xcconfig. Le développeur ajoute manuellement les frameworks au projet via Xcode, offrant un contrôle total sur le processus d'intégration.

Carthage utilise la construction parallèle des dépendances, ce qui accélère considérablement le processus sur les processeurs multicœurs. Chaque dépendance est construite comme une cible séparée, et Carthage résout automatiquement le graphe des dépendances transitives, les construisant dans le bon ordre. Selon les benchmarks de la communauté, Carthage construit 15–20 dépendances en moyenne en 30–60 secondes sur les Mac modernes, ce qui est plus rapide que CocoaPods pour les projets avec de nombreuses bibliothèques. Carthage prend en charge toutes les plateformes Apple : iOS, macOS, watchOS et tvOS, et depuis la version 0.38+ — la construction de .xcframework universels pour la prise en charge du simulateur et des appareils Apple Silicon.

Comment fonctionne Carthage

Carthage clone le dépôt Git de chaque dépendance, bascule vers la version spécifiée (tag, commit ou branche) et exécute xcodebuild pour construire le framework. Carthage détermine automatiquement le type de projet Xcode (framework, dynamic framework, bibliothèque statique) par le schéma de construction. Si un projet a plusieurs schémas, Carthage utilise le schéma par défaut (premier dans l'ordre alphabétique). Après la construction, Carthage copie le framework terminé dans Carthage/Build/ et crée un fichier Cartfile.resolved avec le verrouillage des versions exactes. Carthage prend en charge la mise en cache des frameworks construits — la reconstruction sans modifications des dépendances est ignorée.

Les dépendances transitives dans Carthage sont gérées via Cartfile.resolved : Carthage construit un graphe de toutes les dépendances nécessaires et les construit dans le bon ordre. Si deux bibliothèques dépendent de la même bibliothèque tierce, Carthage la construit une fois et l'utilise pour les deux. Carthage signale les erreurs de construction en indiquant la cible spécifique et la cause — cela simplifie le diagnostic des problèmes.

Cartfile : structure, syntaxe et exemples

Cartfile est un fichier de configuration avec une syntaxe de type Ruby (format Cartfile) qui définit les dépendances d'un projet Carthage. Cartfile se trouve à la racine du projet à côté de .xcodeproj. Chaque ligne de Cartfile décrit une dépendance : la source (URL Git, dépôt GitHub) et la version. La syntaxe prend en charge le verrouillage des versions via des tags, des commits et des branches.

# Dépendances de base Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

La directive github "Owner/Repo" est une forme abrégée pour les dépôts GitHub. Carthage construit automatiquement l'URL https://github.com/Owner/Repo.git. Pour GitLab, Bitbucket et d'autres hôtes Git, l'URL complète est utilisée : git "https://gitlab.com/owner/repo.git". Opérateurs de version : ~> 5.9 (toute version de 5.9 à 6.0, excluant 6.0), == 8.0.0 (version exacte), >= 1.0 (version minimale). Un commit spécifique peut être verrouillé via github "owner/repo" "abc1234".

Exemple complet de Cartfile

Carthage prend en charge plusieurs répertoires pour différentes configurations : Cartfile (principal), Cartfile.private (pour les dépendances internes non publiées) et Cartfile.resolved (généré automatiquement). Les dépendances privées sont utiles pour les bibliothèques utilisées uniquement dans les constructions de développement, comme les frameworks de test.

# Cartfile — les dépendances principales
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

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

# Branche de développement
github "marmelroy/PhoneNumberKit" "development"

github et git sont deux types de sources dans Cartfile. Le premier est exclusivement pour GitHub et génère automatiquement l'URL. Le second est pour tout dépôt Git public ou privé avec une URL complète. Une version peut être spécifiée comme un tag (== 2.1.1), une plage sémantique (~> 5.9), un nom de branche ("development") ou un hash de commit ("a1b2c3d"). Les plages sémantiques (~>) sont recommandées pour les dépendances qui suivent SemVer — cela protège contre les changements cassants lors des mises à jour.

Cartfile.resolved est généré automatiquement après carthage update. Il fige les versions exactes de toutes les dépendances installées, y compris les transitives. Ce fichier doit être conservé dans Git — sans lui, la commande carthage bootstrap sur une autre machine construira les bibliothèques selon les mêmes règles, mais les versions peuvent différer. carthage outdated affiche une liste des dépendances obsolètes pour lesquelles de nouvelles versions sont disponibles.

Installation et configuration de Carthage

Carthage s'installe via Homebrew — le gestionnaire de paquets standard pour macOS. Méthodes alternatives : installation à partir d'un installateur .pkg compilé depuis GitHub ou compilation à partir du code source. Carthage nécessite Xcode avec Command Line Tools (y compris xcodebuild), et sur Mac Apple Silicon — Rosetta 2 pour certaines dépendances héritées.

# Installation Carthage via Homebrew
brew install carthage

# Vérification de version
carthage version

# Installation depuis .pkg (si Homebrew indisponible)
# Télécharger Carthage.pkg depuis GitHub Releases et installer manuellement

Après avoir installé Carthage, l'initialisation du projet commence par la création d'un Cartfile à la racine du projet. Carthage n'a pas de commande init — le fichier est créé manuellement dans un éditeur de texte. Après avoir rempli le Cartfile avec les dépendances, le développeur exécute carthage bootstrap (si Cartfile.resolved existe déjà) ou carthage update (installation initiale ou mise à jour). Carthage clone les dépôts, construit les frameworks et les place dans Carthage/Build/.

Mise à jour de Carthage se fait via brew upgrade carthage. La version est vérifiée avec carthage version. La dernière version stable à la mi-2025 est la 0.40 avec prise en charge par défaut de .xcframework, construction parallèle améliorée et prise en charge complète de Swift 6. À partir de la version 0.39, Carthage a cessé de construire les .framework hérités sans un shim de compatibilité — il est recommandé de spécifier explicitement --use-xcframeworks.

# Mise à jour Carthage via Homebrew
brew upgrade carthage

# Installer une version spécifique
brew install carthage@0.39

# Réinstallation complète
brew uninstall carthage && brew install carthage

Remarque : Carthage ne crée pas de .xcworkspace et ne modifie pas .xcodeproj. Contrairement à CocoaPods, Carthage laisse le contrôle total de la configuration Xcode au développeur. Cela signifie qu'après l'installation des dépendances, vous devez ajouter manuellement les frameworks à Xcode (voir la section « Intégration des frameworks Carthage dans Xcode »). Carthage exige également que chaque dépendance contienne un projet Xcode ou un workspace avec une cible de framework — sinon la construction échouera.

Construction de frameworks : bootstrap et update

Carthage propose trois commandes principales pour travailler avec les dépendances : bootstrap, update et build. carthage bootstrap construit les dépendances à partir d'un Cartfile.resolved existant — recommandé pour les environnements CI et les développeurs rejoignant le projet. carthage update met à jour Cartfile.resolved vers les dernières versions (en respectant les contraintes de Cartfile) et effectue la construction. carthage build construit toutes les dépendances spécifiées sans sauvegarder les versions.

# Installation initiale (met à jour les versions)
carthage update --use-xcframeworks --platform iOS

# Reconstruction avec versions figées
carthage bootstrap --use-xcframeworks --platform iOS

# Construire une seule dépendance
carthage build Alamofire --platform iOS

Le flag --use-xcframeworks indique à Carthage de construire des .xcframework universels au lieu des .framework hérités. Cela garantit la prise en charge à la fois du simulateur et d'un appareil réel, ainsi que des Mac Apple Silicon sans scripts supplémentaires. Le flag --platform iOS limite la construction à une seule plateforme iOS — cela accélère considérablement le processus, surtout si le projet inclut des bibliothèques multiplateformes.

Carthage prend en charge la construction parallèle via le flag --cache-builds, qui met en cache les frameworks déjà construits. Lors de la reconstruction, Carthage vérifie le hash du commit Git et, si le code n'a pas changé, saute la compilation. Pour les serveurs CI, il est recommandé de mettre en cache le répertoire Carthage/Build/ et ~/Library/Caches/carthage/. Carthage prend également en charge --verbose pour une journalisation détaillée et --no-use-binaries pour une construction forcée à partir du code source (si le développeur ne fait pas confiance aux binaires préconstruits).

Intégration des frameworks Carthage dans Xcode

L'intégration des frameworks Carthage dans Xcode se fait manuellement en quatre étapes. Après avoir exécuté carthage update ou bootstrap, tous les frameworks construits se trouvent dans Carthage/Build/iOS/ (ou la plateforme correspondante). Le développeur ouvre le projet Xcode, sélectionne la cible de l'application et ajoute les frameworks dans General → Frameworks, Libraries, and Embedded Content. Pour les frameworks d'exécution (bibliothèques dynamiques), vous devez sélectionner « Embed & Sign » — sinon l'application plantera au démarrage avec l'erreur « dyld : Library not loaded ».

Carthage pour les bibliothèques statiques est plus simple — elles ne nécessitent pas de phase d'incorporation car elles sont liées directement dans le fichier exécutable de l'application. Cependant, Carthage construit par défaut des frameworks dynamiques (sauf pour les bibliothèques statiques explicitement configurées). Pour les projets où la minimisation de la taille de l'application est importante, la liaison statique via les paramètres Xcode est recommandée.

Une étape supplémentaire consiste à ajouter des Input Files dans Build Phase → Run Script. Carthage nécessite un script pour supprimer les artefacts du simulateur du framework construit (strip simulator architectures). Ce script est nécessaire pour les builds App Store :

# Run Script pour 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 ne nécessite pas l'utilisation de .xcworkspace — toutes les dépendances sont déjà construites en frameworks binaires. Carthage fonctionne directement avec .xcodeproj, contrairement à CocoaPods qui crée un workspace. Cela simplifie le contrôle de version et la configuration CI, car les dépendances Carthage ne modifient pas la configuration du projet Xcode. Le seul changement est l'ajout de frameworks à la cible, qui est enregistré dans .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods et Swift Package Manager (SPM) sont les trois principaux gestionnaires de dépendances dans le développement iOS. Carthage se distingue par son approche décentralisée, CocoaPods offre un registre centralisé, et SPM est la solution intégrée d'Apple. Le choix entre eux dépend des exigences du projet, de la taille de l'équipe et du niveau d'automatisation souhaité.

Carthage est choisi pour les projets qui nécessitent une intervention minimale dans la configuration Xcode et un contrôle total sur le processus d'intégration. Carthage est idéal pour les bibliothèques et frameworks open source où l'auteur souhaite permettre aux utilisateurs de construire les dépendances indépendamment. Carthage est également populaire parmi les développeurs qui valorisent la philosophie UNIX : chaque outil fait bien une chose. CocoaPods reste la norme pour les projets d'entreprise avec des dizaines de dépendances où l'automatisation est importante. SPM est le choix pour les nouveaux projets car il est intégré à Xcode et activement développé par Apple.

La migration entre les gestionnaires nécessite différentes approches. Carthage → SPM : supprimer les frameworks de Xcode, supprimer Cartfile et ajouter les dépendances de package via File → Add Package Dependencies. Carthage → CocoaPods : supprimer les frameworks Carthage, créer un Podfile, ajouter les dépendances et exécuter pod init && pod install. Lors de la migration de Carthage vers CocoaPods ou SPM, le besoin de mettre à jour manuellement les frameworks disparaît — toutes les dépendances sont mises à jour avec une seule commande. Carthage reste pertinent pour les projets où il est important d'éviter le verrouillage fournisseur et de maintenir la transparence de la construction des dépendances.

Problèmes courants et leurs solutions

Carthage est un outil stable, mais les développeurs rencontrent périodiquement des problèmes typiques, surtout lors de la construction sur des serveurs CI, de la mise à jour de Xcode ou du changement de versions de Swift. La plupart des problèmes sont résolus en vidant le cache, en configurant correctement --use-xcframeworks et en vérifiant la version minimale d'iOS.

Erreur « The file manager returned an error » — se produit lorsque le cache de Carthage est corrompu ou qu'il y a un conflit de permissions de fichiers. Solution : supprimer le cache avec rm -rf ~/Library/Caches/carthage et redémarrer carthage bootstrap. Supprimer le répertoire Carthage/ dans le projet et reconstruire aide également. Sur les serveurs CI, le cache Carthage ne doit être mis à jour que lorsque Cartfile.resolved change.

Erreur « No such module » — le framework n'est pas trouvé dans Xcode bien que la construction Carthage ait réussi. Solution : vérifier le chemin du framework dans General → Frameworks, Libraries, and Embedded Content. Le framework doit se trouver dans Carthage/Build/iOS/. Assurez-vous que .xcframework est ajouté correctement (glissez-le à nouveau). Pour les frameworks dynamiques, vérifiez Embed & Sign. Si l'erreur persiste, ajoutez FRAMEWORK_SEARCH_PATHS dans Build Settings.

Erreur de construction due à une incompatibilité Swift — la bibliothèque a été construite pour une version de Swift différente de celle du projet. Solution : utilisez carthage update --no-use-binaries pour forcer la construction à partir du code source avec la même version de Swift. Si la bibliothèque ne compile pas sous la version actuelle, utilisez .xcconfig pour spécifier la version Swift ou faites un fork de la bibliothèque. Depuis Carthage 0.39, --use-xcframeworks inclut automatiquement la bonne version de Swift dans le binaire.

Problèmes de construction CI — Carthage sur CI nécessite une configuration de cache appropriée. Solution : mettre en cache Carthage/Build/ et ~/Library/Caches/carthage/. Utilisez carthage bootstrap --use-xcframeworks --platform iOS au lieu de update sur CI pour éviter de changer les versions. Une action officielle Carthage est disponible pour GitHub Actions. Pour Jenkins — le plugin CarthageBuild. Carthage peut planter sur macOS sans GUI — solution : installer brew install xcode-build-server ou ajouter le flag -UseModernBuildSystem=NO.