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
). -
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 9.0 (Swift 4.0).
Once you have Carthage installed, you can begin adding frameworks to your project. Note that Carthage only supports dynamic frameworks, which are only available on iOS 8 or later (or any version of OS X).
- Create a [Cartfile][] that lists the frameworks you’d like to use in your project.
- Run
carthage update
. This will fetch dependencies into a [Carthage/Checkouts][] folder and build each one or download a pre-compiled framework. - 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.
- On your application target’s Build Phases settings tab, click the + icon and choose New Copy Files Phase.
- Click the Destination drop-down menu and select Products Directory.
- For each framework you’re using, drag and drop its corresponding dSYM file.
-
Create a [Cartfile][] that lists the frameworks you’d like to use in your project.
-
Run
carthage update
. This will fetch dependencies into a [Carthage/Checkouts][] folder, then build each one or download a pre-compiled framework. -
On your application targets’ General settings tab, in the “Linked Frameworks and Libraries” section, drag and drop each framework you want to use from the [Carthage/Build][] folder on disk.
-
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:/usr/local/bin/carthage copy-frameworks
-
Add the paths to the frameworks you want to use under “Input Files”, e.g.:
$(SRCROOT)/Carthage/Build/iOS/Result.framework $(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework $(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework
-
Add the paths to the copied frameworks to the “Output Files”, e.g.:
$(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.
This script works around an App Store submission bug 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.
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.