Installing Carthage
There are multiple options for installing Carthage:
Installer: Download and run the
Carthage.pkg
file for the latest release, then follow the on-screen instructions. If you are installing the pkg via CLI, you might need to runsudo chown -R $(whoami) /usr/local
first.Homebrew: You can use Homebrew and install the
carthage
tool on your system simply by runningbrew update
andbrew install carthage
. (note: if you previously installed the binary version of Carthage, you should delete/Library/Frameworks/CarthageKit.framework
).MacPorts: You can use MacPorts and install the
carthage
tool on your system simply by runningsudo port selfupdate
andsudo port install carthage
. (note: if you previously installed the binary version of Carthage, you should delete/Library/Frameworks/CarthageKit.framework
).From source: If you’d like to run the latest development version (which may be highly unstable or incompatible), simply clone the
master
branch of the repository, then runmake install
. Requires Xcode 10.0 (Swift 4.2).
Getting started
Building platform-independent XCFrameworks (Xcode 12 and above)
- Create a [Cartfile][] that lists the frameworks you’d like to use in your project.
- Run
carthage update --use-xcframeworks
. This will fetch dependencies into a [Carthage/Checkouts][] folder and build each one or download a pre-compiled XCFramework. - On your application targets’ General settings tab, in the Frameworks, Libraries, and Embedded Content section, drag and drop each XCFramework you want to use from the [Carthage/Build][] folder on disk.
Migrating a project from framework bundles to XCFrameworks
We encourage using XCFrameworks as of version 0.37.0 (January 2021), and require XCFrameworks when building on an Apple Silicon Mac. Switching from discrete framework bundles to XCFrameworks requires a few changes to your project:
Migration steps
1. Delete your `Carthage/Build` folder to remove any existing framework bundles. 1. Build new XCFrameworks by running `carthage build --use-xcframeworks`. Any other arguments you build with can be provided like normal. 1. Remove references to the old frameworks in each of your targets: - Delete references to Carthage frameworks from the target's _Frameworks, Libraries, and Embedded Content_ section and/or its _Link Binary with Libraries_ build phase. - Delete references to Carthage frameworks from any _Copy Files_ build phases. - Delete the target's `carthage copy-frameworks` build phase, if present. 1. Add references to XCFrameworks in each of your targets: - For an application target: In the _General_ settings tab, in the _Frameworks, Libraries, and Embedded Content_ section, drag and drop each XCFramework you use from the [Carthage/Build][] folder on disk. - For a framework target: In the _Build Phases_ tab, in a _Link Binary with Libraries_ phase, drag and drop each XCFramework you use from the [Carthage/Build][] folder on disk.If you’re building for macOS
macOS-specific instructions
1. Create a [Cartfile][] that lists the frameworks you’d like to use in your project. 1. Run `carthage update --platform macOS`. This will fetch dependencies into a [Carthage/Checkouts][] folder and build each one or download a pre-compiled framework. 1. On your application targets’ _General_ settings tab, in the _Embedded Binaries_ section, drag and drop each framework you want to use from the [Carthage/Build][] folder on disk. Additionally, you'll need to copy debug symbols for debugging and crash reporting on OS X. 1. On your application target’s _Build Phases_ settings tab, click the _+_ icon and choose _New Copy Files Phase_. 1. Click the _Destination_ drop-down menu and select _Products Directory_. 1. For each framework you’re using, drag and drop its corresponding dSYM file.If you’re building for iOS, tvOS, or watchOS
Platform-specific instructions
1. Create a [Cartfile][] that lists the frameworks you’d like to use in your project. 1. Run `carthage update`. This will fetch dependencies into a [Carthage/Checkouts][] folder, then build each one or download a pre-compiled framework. 1. Open your application targets’ _General_ settings tab. For Xcode 11.0 and higher, in the "Frameworks, Libraries, and Embedded Content" section, drag and drop each framework you want to use from the [Carthage/Build][] folder on disk. Then, in the "Embed" section, select "Do Not Embed" from the pulldown menu for each item added. For Xcode 10.x and lower, in the "Linked Frameworks and Libraries" section, drag and drop each framework you want to use from the [Carthage/Build][] folder on disk. 1. On your application targets’ _Build Phases_ settings tab, click the _+_ icon and choose _New Run Script Phase_. Create a Run Script in which you specify your shell (ex: `/bin/sh`), add the following contents to the script area below the shell: ```sh /usr/local/bin/carthage copy-frameworks ``` 1. Create a file named `input.xcfilelist` and a file named `output.xcfilelist` 1. Add the paths to the frameworks you want to use to your `input.xcfilelist`. For example: ``` $(SRCROOT)/Carthage/Build/iOS/Result.framework $(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework $(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework ``` 1. Add the paths to the copied frameworks to the `output.xcfilelist`. For example: ``` $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework ``` With output files specified alongside the input files, Xcode only needs to run the script when the input files have changed or the output files are missing. This means dirty builds will be faster when you haven't rebuilt frameworks with Carthage. 1. Add the `input.xcfilelist` to the "Input File Lists" section of the Carthage run script phase 1. Add the `output.xcfilelist` to the "Output File Lists" section of the Carthage run script phase This script works around an [App Store submission bug](http://www.openradar.me/radar?id=6409498411401216) triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving. With the debug information copied into the built products directory, Xcode will be able to symbolicate the stack trace whenever you stop at a breakpoint. This will also enable you to step through third-party code in the debugger. When archiving your application for submission to the App Store or TestFlight, Xcode will also copy these files into the dSYMs subdirectory of your application’s `.xcarchive` bundle.For all platforms
Along the way, Carthage will have created some [build artifacts][Artifacts]. The most important of these is the [Cartfile.resolved][] file, which lists the versions that were actually built for each framework. Make sure to commit your [Cartfile.resolved][], because anyone else using the project will need that file to build the same framework versions.
(Optionally) Add build phase to warn about outdated dependencies
You can add a Run Script phase to automatically warn you when one of your dependencies is out of date.
- On your application targets’
Build Phases
settings tab, click the+
icon and chooseNew Run Script Phase
. Create a Run Script in which you specify your shell (ex:/bin/sh
), add the following contents to the script area below the shell:
/usr/local/bin/carthage outdated --xcode-warnings 2>/dev/null
Swift binary framework download compatibility
Carthage will check to make sure that downloaded Swift (and mixed Objective-C/Swift) frameworks were built with the same version of Swift that is in use locally. If there is a version mismatch, Carthage will proceed to build the framework from source. If the framework cannot be built from source, Carthage will fail.
Because Carthage uses the output of xcrun swift --version
to determine the local Swift version, make sure to run Carthage commands with the Swift toolchain that you intend to use. For many use cases, nothing additional is needed. However, for example, if you are building a Swift 2.3 project using Xcode 8.x, one approach to specifying your default swift
for carthage bootstrap
is to use the following command:
TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap
Running a project that uses Carthage
After you’ve finished the above steps and pushed your changes, other users of the project only need to fetch the repository and run carthage bootstrap
to get started with the frameworks you’ve added.
Upgrading frameworks
If you’ve modified your [Cartfile][], or you want to update to the newest versions of each framework (subject to the requirements you’ve specified), simply run the carthage update
command again.
If you only want to update one, or specific, dependencies, pass them as a space-separated list to the update
command. e.g.
carthage update Box
or
carthage update Box Result
Nested dependencies
If the framework you want to add to your project has dependencies explicitly listed in a [Cartfile][], Carthage will automatically retrieve them for you. You will then have to drag them yourself into your project from the [Carthage/Build] folder.
If the embedded framework in your project has dependencies to other frameworks you must link them to application target (even if application target does not have dependency to that frameworks and never uses them).
Using submodules for dependencies
By default, Carthage will directly [check out][Carthage/Checkouts] dependencies’ source files into your project folder, leaving you to commit or ignore them as you choose. If you’d like to have dependencies available as Git submodules instead (perhaps so you can commit and push changes within them), you can run carthage update
or carthage checkout
with the --use-submodules
flag.
When run this way, Carthage will write to your repository’s .gitmodules
and .git/config
files, and automatically update the submodules when the dependencies’ versions change.
Automatically rebuilding dependencies
If you want to work on your dependencies during development, and want them to be automatically rebuilt when you build your parent project, you can add a Run Script build phase that invokes Carthage like so:
/usr/local/bin/carthage build --platform "$PLATFORM_NAME" --project-directory "$SRCROOT"
Note that you should be using submodules before doing this, because plain checkouts [should not be modified][Carthage/Checkouts] directly.
Caching builds
By default Carthage will rebuild a dependency regardless of whether it’s the same resolved version as before. Passing the --cache-builds
will cause carthage to avoid rebuilding a dependency if it can. See information on [version files][VersionFile] for details on how Carthage performs this caching.
Note: At this time --cache-builds
is incompatible with --use-submodules
. Using both will result in working copy and committed changes to your submodule dependency not being correctly rebuilt. See #1785 for details.
Bash/Zsh/Fish completion
Auto completion of Carthage commands and options are available as documented in [Bash/Zsh/Fish Completion][Bash/Zsh/Fish Completion].
Share your Xcode schemes
Carthage will only build Xcode schemes that are shared from your .xcodeproj
. You can see if all of your intended schemes build successfully by running carthage build --no-skip-current
, then checking the [Carthage/Build][] folder.
If an important scheme is not built when you run that command, open Xcode and make sure that the scheme is marked as Shared, so Carthage can discover it.
Resolve build failures
If you encounter build failures in carthage build --no-skip-current
, try running xcodebuild -scheme SCHEME -workspace WORKSPACE build
or xcodebuild -scheme SCHEME -project PROJECT build
(with the actual values) and see if the same failure occurs there. This should hopefully yield enough information to resolve the problem.
If you have multiple versions of the Apple developer tools installed (an Xcode beta, for example), use xcode-select
to change which version Carthage uses.
If you’re still not able to build your framework with Carthage, please open an issue and we’d be happy to help!
Build static frameworks to speed up your app’s launch times
If you embed many dynamic frameworks into your app, its pre-main launch times may be quite slow. Carthage is able to help mitigate this by building your dynamic frameworks as static frameworks instead. Static frameworks can be linked directly into your application or merged together into a larger dynamic framework with a few simple modifications to your workflow, which can result in dramatic reductions in pre-main launch times.
Declare your compatibility
Want to advertise that your project can be used with Carthage? You can add a compatibility badge:
… to your README
, by simply inserting the following Markdown:
[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
Known issues
DWARFs symbol problem
Pre-built framework cannot be debugged using step execution on other machine than on which the framework was built. Simply carthage bootstrap/build/update --no-use-binaries
should fix this, but for more automated workaround, see #924. Dupe rdar://23551273 if you want Apple to fix the root cause of this problem.
CarthageKit
Most of the functionality of the carthage
command line tool is actually encapsulated in a framework named CarthageKit.
If you’re interested in using Carthage as part of another tool, or perhaps extending the functionality of Carthage, take a look at the [CarthageKit][] source code to see if the API fits your needs.
Differences between Carthage and CocoaPods
CocoaPods is a long-standing dependency manager for Cocoa. So why was Carthage created?
Firstly, CocoaPods (by default) automatically creates and updates an Xcode workspace for your application and all dependencies. Carthage builds framework binaries using xcodebuild
, but leaves the responsibility of integrating them up to the user. CocoaPods’ approach is easier to use, while Carthage’s is flexible and unintrusive.
The goal of CocoaPods is listed in its README as follows:
… to improve discoverability of, and engagement in, third party open-source libraries, by creating a more centralized ecosystem.
By contrast, Carthage has been created as a decentralized dependency manager. There is no central list of projects, which reduces maintenance work and avoids any central point of failure. However, project discovery is more difficult—users must resort to GitHub’s Trending pages or similar.
CocoaPods projects must also have what’s known as a podspec file, which includes metadata about the project and specifies how it should be built. Carthage uses xcodebuild
to build dependencies, instead of integrating them into a single workspace, it doesn’t have a similar specification file but your dependencies must include their own Xcode project that describes how to build their products.
Ultimately, we created Carthage because we wanted the simplest tool possible—a dependency manager that gets the job done without taking over the responsibility of Xcode, and without creating extra work for framework authors. CocoaPods offers many amazing features that Carthage will never have, at the expense of additional complexity.