Carthage
0.40.0
Carthage est destiné à être le moyen le plus simple d'ajouter des frameworks à votre application Cocoa.
Carthage construit vos dépendances et vous fournit des frameworks binaires, mais vous conservez le contrôle total sur la structure et la configuration de votre projet. Carthage ne modifie pas automatiquement vos fichiers de projet ou vos paramètres de construction.
Obtenez Carthage en exécutant brew install carthage ou choisissez une autre méthode d'installation
Créez un Cartfile dans le même répertoire où se trouve votre .xcodeproj ou .xcworkspace
Lister les dépendances souhaitées dans le Cartfile, par exemple :
github "Alamofire/Alamofire" ~> 5.5
Exécutez carthage update --use-xcframeworks
Un fichier Cartfile.resolved et un répertoire Carthage apparaîtront dans le même répertoire où se trouve votre .xcodeproj ou .xcworkspace
Faites glisser les bundles .xcframework construits depuis Carthage/Build vers la section « Frameworks and Libraries » du projet Xcode de votre application.
Si vous utilisez Carthage pour une application, sélectionnez « Intégrer et signer », sinon « Ne pas intégrer ».
Pour un guide détaillé, lisez la suite de Ajout de frameworks à une application
Il existe plusieurs options pour installer Carthage :
Programme d'installation : téléchargez et exécutez le fichier Carthage.pkg pour la dernière version, puis suivez les instructions à l'écran. Si vous installez le paquet via CLI, vous devrez peut-être d'abord exécuter sudo chown -R $(whoami) /usr/local .
Homebrew : Vous pouvez utiliser Homebrew et installer l'outil carthage sur votre système simplement en exécutant brew update et brew install carthage . (remarque : si vous avez déjà installé la version binaire de Carthage, vous devez supprimer /Library/Frameworks/CarthageKit.framework ).
MacPorts : Vous pouvez utiliser MacPorts et installer l'outil carthage sur votre système simplement en exécutant sudo port selfupdate et sudo port install carthage . (remarque : si vous avez déjà installé la version binaire de Carthage, vous devez supprimer /Library/Frameworks/CarthageKit.framework ).
Depuis les sources : si vous souhaitez exécuter la dernière version de développement (qui peut être très instable ou incompatible), clonez simplement la branche master du référentiel, puis exécutez make install . Nécessite Xcode 10.0 (Swift 4.2).
Une fois Carthage installé, vous pouvez commencer à ajouter des frameworks à votre projet. Notez que Carthage ne prend en charge que les frameworks dynamiques, qui ne sont disponibles que sur iOS 8 ou version ultérieure (ou sur toute version d'OS X).
carthage update --use-xcframeworks . Cela récupérera les dépendances dans un dossier Carthage/Checkouts et construira chacune d'elles ou téléchargera un XCFramework précompilé.Nous encourageons l'utilisation de XCFrameworks à partir de la version 0.37.0 (janvier 2021) et exigeons XCFrameworks lors de la construction sur un Mac Apple Silicon. Le passage des bundles de framework discrets à XCFrameworks nécessite quelques modifications dans votre projet :
Carthage/Build pour supprimer tous les bundles de framework existants.carthage build --use-xcframeworks . Tous les autres arguments avec lesquels vous construisez peuvent être fournis comme d’habitude.carthage copy-frameworks de la cible, si elle est présente.Incompatibilité Xcode 12+ : les plates-formes multi-architectures ne sont pas prises en charge lors de la création de bundles de framework dans Xcode 12 et versions ultérieures. Préférez construire avec XCFrameworks. Si vous devez créer des bundles de framework discrets, utilisez un fichier xcconfig de solution de contournement.
carthage update --platform macOS . Cela récupérera les dépendances dans un dossier Carthage/Checkouts et construira chacune d'elles ou téléchargera un framework précompilé.De plus, vous devrez copier les symboles de débogage pour le débogage et les rapports de plantage sous OS X.
Créez un Cartfile qui répertorie les frameworks que vous souhaitez utiliser dans votre projet.
Exécutez carthage update . Cela récupérera les dépendances dans un dossier Carthage/Checkouts, puis construira chacune d'elles ou téléchargera un framework précompilé.
Ouvrez l'onglet Paramètres généraux de vos cibles d'application. Pour Xcode 11.0 et supérieur, dans la section « Frameworks, bibliothèques et contenu intégré », faites glisser et déposez chaque framework que vous souhaitez utiliser depuis le dossier Carthage/Build sur le disque. Ensuite, dans la section « Intégrer », sélectionnez « Ne pas intégrer » dans le menu déroulant pour chaque élément ajouté. Pour Xcode 10.x et versions antérieures, dans la section « Frameworks et bibliothèques liés », faites glisser et déposez chaque framework que vous souhaitez utiliser depuis le dossier Carthage/Build sur le disque.
Dans l'onglet Paramètres des phases de construction de vos cibles d'application, cliquez sur l'icône + et choisissez Nouvelle phase d'exécution du script . Créez un Run Script dans lequel vous spécifiez votre shell (ex : /bin/sh ), ajoutez le contenu suivant à la zone de script sous le shell :
/usr/local/bin/carthage copy-frameworks Créez un fichier nommé input.xcfilelist et un fichier nommé output.xcfilelist
Ajoutez les chemins d'accès aux frameworks que vous souhaitez utiliser à votre input.xcfilelist . Par exemple:
$(SRCROOT)/Carthage/Build/iOS/Result.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework
Ajoutez les chemins d'accès aux frameworks copiés au output.xcfilelist . Par exemple:
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework
Avec les fichiers de sortie spécifiés à côté des fichiers d'entrée, Xcode n'a besoin d'exécuter le script que lorsque les fichiers d'entrée ont changé ou que les fichiers de sortie sont manquants. Cela signifie que les builds sales seront plus rapides si vous n'avez pas reconstruit les frameworks avec Carthage.
Ajoutez le input.xcfilelist à la section "Listes de fichiers d'entrée" de la phase de script d'exécution de Carthage
Ajoutez le output.xcfilelist à la section "Listes de fichiers de sortie" de la phase de script d'exécution de Carthage.
Ce script fonctionne autour d'un bogue de soumission sur l'App Store déclenché par les binaires universels et garantit que les fichiers liés au bitcode et les dSYM nécessaires sont copiés lors de l'archivage.
Avec les informations de débogage copiées dans le répertoire des produits construits, Xcode pourra symboliser la trace de la pile chaque fois que vous vous arrêterez à un point d'arrêt. Cela vous permettra également de parcourir le code tiers dans le débogueur.
Lors de l'archivage de votre application pour soumission à l'App Store ou à TestFlight, Xcode copiera également ces fichiers dans le sous-répertoire dSYMs du bundle .xcarchive de votre application.
En chemin, Carthage aura créé des artefacts de construction. Le plus important d'entre eux est le fichier Cartfile.resolved, qui répertorie les versions réellement construites pour chaque framework. Assurez-vous de valider votre Cartfile.resolved , car toute autre personne utilisant le projet aura besoin de ce fichier pour créer les mêmes versions de framework.
Vous pouvez ajouter une phase Run Script pour vous avertir automatiquement lorsqu'une de vos dépendances est obsolète.
Build Phases de vos cibles d'application, cliquez sur l'icône + et choisissez New Run Script Phase . Créez un Run Script dans lequel vous spécifiez votre shell (ex : /bin/sh ), ajoutez le contenu suivant à la zone de script sous le shell : /usr/local/bin/carthage outdated --xcode-warnings 2> /dev/nullCarthage vérifiera que les frameworks Swift (et mixtes Objective-C/Swift) téléchargés ont été construits avec la même version de Swift que celle utilisée localement. En cas d'incompatibilité de version, Carthage procédera à la construction du framework à partir des sources. Si le cadre ne peut pas être construit à partir des sources, Carthage échouera.
Étant donné que Carthage utilise la sortie de xcrun swift --version pour déterminer la version locale de Swift, assurez-vous d'exécuter les commandes Carthage avec la chaîne d'outils Swift que vous avez l'intention d'utiliser. Pour de nombreux cas d’utilisation, rien de plus n’est nécessaire. Cependant, par exemple, si vous créez un projet Swift 2.3 à l'aide de Xcode 8.x, une approche pour spécifier votre swift par défaut pour carthage bootstrap consiste à utiliser la commande suivante :
TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap
Une fois que vous avez terminé les étapes ci-dessus et appliqué vos modifications, les autres utilisateurs du projet n'ont qu'à récupérer le référentiel et exécuter carthage bootstrap pour démarrer avec les frameworks que vous avez ajoutés.
Utiliser Carthage pour les dépendances de toute cible arbitraire est assez similaire à utiliser Carthage pour une application. La principale différence réside dans la manière dont les frameworks sont réellement configurés et liés dans Xcode.
Étant donné que les cibles de tests unitaires ne disposent pas de la section Cadres et bibliothèques liés dans leur onglet Paramètres généraux , vous devez plutôt faire glisser les cadres construits vers la phase de construction Lier les binaires aux bibliothèques .
Dans la cible de test sous l’onglet Paramètres de construction , ajoutez @loader_path/Frameworks aux chemins de recherche Runpath s’il n’est pas déjà présent.
Dans de rares cas, vous souhaiterez peut-être également copier chaque dépendance dans le produit de build (par exemple, pour intégrer les dépendances dans le framework externe, ou vous assurer que les dépendances sont présentes dans un bundle de test). Pour ce faire, créez une nouvelle phase de construction de copie de fichiers avec la destination Frameworks , puis ajoutez-y également la référence du framework. Vous ne devez pas utiliser la commande carthage copy-frameworks car les bundles de test n'ont pas besoin de supprimer les frameworks et l'exécution d'instances simultanées de copy-frameworks (avec les constructions parallèles activées) n'est pas prise en charge.
Si vous avez modifié votre fichier Cartfile ou si vous souhaitez mettre à jour vers les versions les plus récentes de chaque framework (sous réserve des exigences que vous avez spécifiées), exécutez simplement à nouveau la commande carthage update .
Si vous souhaitez uniquement mettre à jour une ou des dépendances spécifiques, transmettez-les sous forme de liste séparée par des espaces à la commande update . par exemple
carthage update Box
ou
carthage update Box Result
Une réécriture de la logique de mise à niveau des frameworks a été réalisée dans le but d'augmenter la vitesse et de réduire l'utilisation de la mémoire. Il s'agit actuellement d'une fonctionnalité facultative. Il peut être utilisé en passant --new-resolver à la commande update, par exemple :
carthage update --new-resolver Box
Si vous rencontrez des problèmes de performances lors des mises à jour, essayez le nouveau résolveur
Si le framework que vous souhaitez ajouter à votre projet possède des dépendances explicitement répertoriées dans un Cartfile, Carthage les récupérera automatiquement pour vous. Vous devrez ensuite les glisser vous-même dans votre projet depuis le dossier Carthage/Build.
Si le framework intégré dans votre projet a des dépendances avec d'autres frameworks, vous devez les lier à la cible de l'application (même si la cible de l'application n'a pas de dépendance envers ces frameworks et ne les utilise jamais).
Par défaut, Carthage extraira directement les fichiers sources des dépendances dans votre dossier de projet, vous laissant le choix de les valider ou de les ignorer. Si vous souhaitez plutôt avoir des dépendances disponibles en tant que sous-modules Git (peut-être pour pouvoir valider et appliquer des modifications à l'intérieur), vous pouvez exécuter carthage update ou carthage checkout avec l'option --use-submodules .
Lorsqu'il est exécuté de cette façon, Carthage écrira dans les fichiers .gitmodules et .git/config de votre référentiel et mettra automatiquement à jour les sous-modules lorsque les versions des dépendances changent.
Si vous souhaitez travailler sur vos dépendances pendant le développement et qu'elles soient automatiquement reconstruites lorsque vous construisez votre projet parent, vous pouvez ajouter une phase de construction Run Script qui appelle Carthage comme ceci :
/usr/local/bin/carthage build --platform " $PLATFORM_NAME " --project-directory " $SRCROOT "Notez que vous devez utiliser des sous-modules avant de faire cela, car les extractions simples ne doivent pas être modifiées directement.
Par défaut, Carthage reconstruira une dépendance, qu'il s'agisse ou non de la même version résolue qu'auparavant. Passer le --cache-builds empêchera Carthage de reconstruire une dépendance si cela est possible. Voir les informations sur les fichiers de version pour plus de détails sur la manière dont Carthage effectue cette mise en cache.
Remarque : Pour le moment, --cache-builds est incompatible avec --use-submodules . L’utilisation des deux entraînera une copie de travail et des modifications validées dans la dépendance de votre sous-module qui ne seront pas correctement reconstruites. Voir #1785 pour plus de détails.
La complétion automatique des commandes et options de Carthage est disponible comme documenté dans Achèvement Bash/Zsh/Fish.
Carthage ne prend officiellement en charge que les frameworks dynamiques . Les frameworks dynamiques peuvent être utilisés sur n'importe quelle version d'OS X, mais uniquement sur iOS 8 ou version ultérieure . De plus, depuis la version 0.30.0, Carthage prend en charge les frameworks statiques .
Étant donné que Carthage n'a pas de liste de packages centralisée ni de format de spécification de projet, la plupart des frameworks devraient être construits automatiquement .
Les exigences spécifiques de tout projet-cadre sont énumérées ci-dessous.
Carthage construira uniquement des schémas Xcode partagés à partir de votre .xcodeproj . Vous pouvez voir si tous vos schémas prévus se construisent avec succès en exécutant carthage build --no-skip-current , puis en vérifiant le dossier Carthage/Build.
Si un schéma important n'est pas construit lorsque vous exécutez cette commande, ouvrez Xcode et assurez-vous que le schéma est marqué comme Shared afin que Carthage puisse le découvrir.
Si vous rencontrez des échecs de construction dans carthage build --no-skip-current , essayez d'exécuter xcodebuild -scheme SCHEME -workspace WORKSPACE build ou xcodebuild -scheme SCHEME -project PROJECT build (avec les valeurs réelles) et voyez si le même échec s'y produit. Nous espérons que cela devrait fournir suffisamment d'informations pour résoudre le problème.
Si vous avez installé plusieurs versions des outils de développement Apple (une version bêta de Xcode, par exemple), utilisez xcode-select pour modifier la version utilisée par Carthage.
Si vous ne parvenez toujours pas à créer votre framework avec Carthage, veuillez ouvrir un ticket et nous serons heureux de vous aider !
Carthage détermine quelles versions de votre framework sont disponibles en recherchant dans les balises publiées sur le référentiel et en essayant d'interpréter chaque nom de balise comme une version sémantique. Par exemple, dans la balise v1.2 , la version sémantique est 1.2.0.
Les balises sans numéro de version ou avec des caractères suivant le numéro de version (par exemple, 1.2-alpha-1 ) ne sont actuellement pas prises en charge et seront ignorées.
Carthage peut utiliser automatiquement des frameworks prédéfinis, au lieu de les construire à partir de zéro, s'ils sont attachés à une version GitHub sur le référentiel de votre projet ou via un fichier de définition de projet binaire.
Pour proposer des frameworks prédéfinis pour une balise spécifique, les binaires de toutes les plates-formes prises en charge doivent être compressés ensemble dans une seule archive, et cette archive doit être jointe à une version publiée correspondant à cette balise. La pièce jointe doit inclure .framework dans son nom (par exemple, ReactiveCocoa.framework.zip ), pour indiquer à Carthage qu'elle contient des binaires. La structure des répertoires de l'archive est de forme libre mais les frameworks ne doivent apparaître qu'une seule fois dans l'archive car ils seront copiés dans Carthage/Build/<platform> en fonction de leur nom (par exemple ReactiveCocoa.framework ).
Pour proposer des XCFrameworks prédéfinis, construisez avec --use-xcframeworks et suivez le même processus pour compresser tous les XCFrameworks dans une seule archive. Incluez .xcframework dans le nom de la pièce jointe. À partir de la version 0.38.0, Carthage préfère télécharger les pièces jointes .xcframework lorsque --use-xcframeworks est passé.
Vous pouvez effectuer l'opération d'archivage avec Carthage lui-même en utilisant :
-carthage build --no-skip-current
-carthage archive YourFrameworkNameou bien
carthage build --archiveLes versions préliminaires seront automatiquement ignorées, même si elles correspondent à la balise souhaitée.
Il est possible d'utiliser travis-ci afin de créer et de télécharger vos versions taguées.
Installez travis CLI avec gem install travis
Configurez Travis-ci pour votre référentiel (étapes 1 et 2)
Créez un fichier .travis.yml à la racine de votre référentiel basé sur ce modèle. Définissez FRAMEWORK_NAME sur la valeur correcte.
Remplacez PROJECT_PLACEHOLDER et SCHEME_PLACEHOLDER
Si vous utilisez un espace de travail au lieu d'un projet, supprimez la ligne xcode_project et décommentez la ligne xcode_workspace.
Le projet doit être au format : MyProject.xcodeproj
L'espace de travail doit être au format : MyWorkspace.xcworkspace
N'hésitez pas à mettre à jour la valeur xcode_sdk vers un autre SDK, notez que les tests sur le SDK iphoneos vous obligeraient à télécharger une identité de signature de code
Pour plus d'informations, vous pouvez visiter Travis Docs pour les projets Objective-C.
language : objective-c
osx_image : xcode7.3
xcode_project : <PROJECT_PLACEHOLDER>
# xcode_workspace: <WORKSPACE_PLACEHOLDER>
xcode_scheme : <SCHEME_PLACEHOLDER>
xcode_sdk : iphonesimulator9.3
env :
global :
- FRAMEWORK_NAME=<THIS_IS_A_PLACEHOLDER_REPLACE_ME>
before_install :
- brew update
- brew outdated carthage || brew upgrade carthage
before_script :
# bootstrap the dependencies for the project
# you can remove if you don't have dependencies
- carthage bootstrap
before_deploy :
- carthage build --no-skip-current
- carthage archive $FRAMEWORK_NAME Exécutez travis setup releases , suivez la documentation ici
Cette commande encodera vos informations d'identification GitHub dans le fichier .travis.yml afin de permettre à Travis de télécharger la version sur GitHub.com. Lorsque vous êtes invité à télécharger le fichier, entrez $FRAMEWORK_NAME.framework.zip
Mettez à jour la section de déploiement pour qu'elle s'exécute sur les balises :
Dans .travis.yml localisez :
on :
repo : repo/repo Et ajoutez tags: true et skip_cleanup: true :
skip_cleanup : true
on :
repo : repo/repo
tags : trueCela permettra à Travis de créer un déploiement lorsqu'une nouvelle balise est poussée et empêchera Travis de nettoyer le fichier zip généré.
Si vous intégrez de nombreux frameworks dynamiques dans votre application, ses délais de lancement avant le lancement principal peuvent être assez lents. Carthage est en mesure de contribuer à atténuer ce problème en créant plutôt vos cadres dynamiques sous forme de cadres statiques. Les frameworks statiques peuvent être liés directement à votre application ou fusionnés dans un framework dynamique plus large avec quelques modifications simples à votre flux de travail, ce qui peut entraîner des réductions spectaculaires des délais de lancement avant le lancement principal.
Depuis la version 0.30.0, le projet Carthage déploie la prise en charge des frameworks liés statiquement écrits en Swift ou Objective-C, dont la prise en charge a été introduite dans Xcode 9.4. Veuillez noter cependant qu'il est spécifiquement indiqué frameworks , c'est pourquoi Darwin regroupe l'extension .framework et des archives d'objets liées statiquement à l'intérieur. Carthage ne prend pas actuellement en charge les schémas de bibliothèques statiques et il n'est pas non plus prévu d'introduire leur prise en charge à l'avenir.
Le flux de travail diffère à peine :
Cependant:
Voir la documentation StaticFrameworks pour plus de détails.
Veuillez noter que quelques mises en garde s'appliquent à cette approche :
Vous souhaitez annoncer que votre projet peut être utilisé avec Carthage ? Vous pouvez ajouter un badge de compatibilité :
… dans votre README , en insérant simplement le Markdown suivant :
[ ![ Carthage compatible ] ( https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat )] ( https://github.com/Carthage/Carthage ) Le framework prédéfini ne peut pas être débogué à l'aide d'une exécution par étapes sur une autre machine que celle sur laquelle le framework a été construit. Simplement carthage bootstrap/build/update --no-use-binaries devrait résoudre ce problème, mais pour une solution de contournement plus automatisée, voir #924. Dupe rdar://23551273 si vous souhaitez qu'Apple corrige la cause première de ce problème.
La plupart des fonctionnalités de l'outil de ligne de commande carthage sont en fait encapsulées dans un framework nommé CarthageKit.
Si vous souhaitez utiliser Carthage dans le cadre d'un autre outil, ou peut-être étendre les fonctionnalités de Carthage, jetez un œil au code source de CarthageKit pour voir si l'API répond à vos besoins.
CocoaPods est un gestionnaire de dépendances de longue date pour Cocoa. Alors pourquoi Carthage a-t-elle été créée ?
Premièrement, CocoaPods (par défaut) crée et met à jour automatiquement un espace de travail Xcode pour votre application et toutes les dépendances. Carthage construit des binaires de framework en utilisant xcodebuild , mais laisse la responsabilité de les intégrer à l'utilisateur. L'approche de CocoaPods est plus facile à utiliser, tandis que celle de Carthage est flexible et peu intrusive.
L'objectif de CocoaPods est répertorié dans son README comme suit :
… pour améliorer la découvrabilité et l’engagement dans les bibliothèques open source tierces, en créant un écosystème plus centralisé.
En revanche, Carthage a été créée comme un gestionnaire de dépendances décentralisé . Il n'existe pas de liste centrale de projets, ce qui réduit les travaux de maintenance et évite tout point central de défaillance. Cependant, la découverte de projets est plus difficile : les utilisateurs doivent recourir aux pages de tendances de GitHub ou similaires.
Les projets CocoaPods doivent également disposer de ce que l'on appelle un fichier podspec, qui inclut des métadonnées sur le projet et spécifie comment il doit être construit. Carthage utilise xcodebuild pour créer des dépendances, au lieu de les intégrer dans un seul espace de travail, il n'a pas de fichier de spécifications similaire mais vos dépendances doivent inclure leur propre projet Xcode qui décrit comment créer leurs produits.
En fin de compte, nous avons créé Carthage parce que nous voulions l'outil le plus simple possible : un gestionnaire de dépendances qui fait le travail sans assumer la responsabilité de Xcode et sans créer de travail supplémentaire pour les auteurs du framework. CocoaPods offre de nombreuses fonctionnalités étonnantes que Carthage n'aura jamais, au prix d'une complexité supplémentaire.
Carthage est publié sous licence MIT.
La photo de fond d'en-tête est publiée sous la licence CC BY-NC-SA 2.0. Photo originale de Richard Mortel.
