Repository files navigation

Carthage is intended to be the simplest way to add frameworks to your Cocoa application.

Carthage builds your dependencies and provides you with binary frameworks, but you retain full control over your project structure and setup. Carthage does not automatically modify your project files or your build settings.

• Quick Start
• Installing Carthage
• Adding frameworks to an application
  • Getting started
    • Building platform-independent XCFrameworks
      • Migrating a project from framework bundles to XCFrameworks
    • Building platform-specific framework bundles
      • If you're building for macOS
      • If you're building for iOS, tvOS, or watchOS
    • For all platforms
    • (Optionally) Add build phase to warn about outdated dependencies
    • Swift binary framework download compatibility
  • Running a project that uses Carthage
  • Adding frameworks to unit tests or a framework
  • Upgrading frameworks
    • Experimental Resolver
  • Nested dependencies
  • Using submodules for dependencies
  • Automatically rebuilding dependencies
  • Caching builds
  • Bash/Zsh/Fish completion
• Supporting Carthage for your framework
  • Share your Xcode schemes
  • Resolve build failures
  • Tag stable releases
  • Archive prebuilt frameworks into zip files
    • Use travis-ci to upload your tagged prebuilt frameworks
  • Build static frameworks to speed up your app’s launch times
  • Declare your compatibility
• Known issues
  • DWARFs symbol problem
• CarthageKit
• Differences between Carthage and CocoaPods
• License

1. Get Carthage by runningbrew install carthage or chooseanother installation method

2. Create aCartfile in the same directory where your.xcodeproj or.xcworkspace is

3. List the desired dependencies in theCartfile, for example:

   github "Alamofire/Alamofire" ~> 5.5

4. Runcarthage update --use-xcframeworks

5. ACartfile.resolved file and aCarthage directory will appear in the same directory where your.xcodeproj or.xcworkspace is

6. Drag the built.xcframework bundles fromCarthage/Build into the "Frameworks and Libraries" section of your application’s Xcode project.

7. If you are using Carthage for an application, select "Embed & Sign", otherwise "Do Not Embed".

For an in depth guide, read on fromAdding frameworks to an application

There are multiple options for installing Carthage:

• Installer: Download and run theCarthage.pkg file for the latestrelease, 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 useHomebrew and install thecarthage 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 useMacPorts and install thecarthage 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 themaster branch of the repository, then runmake install. Requires Xcode 10.0 (Swift 4.2).

Once you have Carthageinstalled, you can begin adding frameworks to your project. Note that Carthage only supports dynamic frameworks, which areonly available on iOS 8 or later (or any version of OS X).

1. Create aCartfile that lists the frameworks you’d like to use in your project.
2. Runcarthage update --use-xcframeworks. This will fetch dependencies into aCarthage/Checkouts folder and build each one or download a pre-compiled XCFramework.
3. On your application targets’General settings tab, in theFrameworks, Libraries, and Embedded Content section, drag and drop each XCFramework you want to use from theCarthage/Build folder on disk.

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:

Xcode 12+ incompatibility: Multi-architecture platforms are not supported when building framework bundles in Xcode 12 and above. Preferbuilding with XCFrameworks. If you need to build discrete framework bundles,use a workaround xcconfig file.

Along the way, Carthage will have created somebuild artifacts. The most important of these is theCartfile.resolved file, which lists the versions that were actually built for each framework.Make sure to commit yourCartfile.resolved, because anyone else using the project will need that file to build the same framework versions.

You can add a Run Script phase to automatically warn you when one of your dependencies is out of date.

1. 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-warnings2>/dev/null

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 ofxcrun 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 defaultswift forcarthage bootstrap is to use the following command:

TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap

After you’ve finished the above steps and pushed your changes, other users of the project only need to fetch the repository and runcarthage bootstrap to get started with the frameworks you’ve added.

Using Carthage for the dependencies of any arbitrary target is fairly similar tousing Carthage for an application. The main difference lies in how the frameworks are actually set up and linked in Xcode.

Because unit test targets are missing theLinked Frameworks and Libraries section in theirGeneral settings tab, you must instead drag thebuilt frameworks to theLink Binaries With Libraries build phase.

In the Test target under theBuild Settings tab, add@loader_path/Frameworks to theRunpath Search Paths if it isn't already present.

In rare cases, you may want to also copy each dependency into the build product (e.g., to embed dependencies within the outer framework, or make sure dependencies are present in a test bundle). To do this, create a newCopy Files build phase with theFrameworks destination, then add the framework reference there as well. You shouldn't use thecarthage copy-frameworks command since test bundles don't need frameworks stripped, and running concurrent instances ofcopy-frameworks (with parallel builds turn on) is not supported.

If you’ve modified yourCartfile, or you want to update to the newest versions of each framework (subject to the requirements you’ve specified), simply run thecarthage update command again.

If you only want to update one, or specific, dependencies, pass them as a space-separated list to theupdate command. e.g.

carthage update Box

or

carthage update Box Result

A rewrite of the logic for upgrading frameworks was done with the aim of increasing speed and reducing memory usage. It is currently an opt-in feature. It can be used by passing--new-resolver to the update command, e.g.,

carthage update --new-resolver Box

If you are experiencing performance problems during updates, please give the new resolver a try

If the framework you want to add to your project has dependencies explicitly listed in aCartfile, Carthage will automatically retrieve them for you. You will then have todrag them yourself into your project from theCarthage/Build folder.

If the embedded framework in your project has dependencies to other frameworks you mustlink them to application target (even if application target does not have dependency to that frameworks and never uses them).

By default, Carthage will directlycheck out 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 runcarthage update orcarthage 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.

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 beusing submodules before doing this, because plain checkoutsshould not be modified directly.

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 onversion files 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.

Auto completion of Carthage commands and options are available as documented inBash/Zsh/Fish Completion.

Carthage only officially supports dynamic frameworks. Dynamic frameworks can be used on any version of OS X, but only oniOS 8 or later. Additionally, since version 0.30.0 Carthage supportsstatic frameworks.

Because Carthage has no centralized package list, and no project specification format,most frameworks should build automatically.

The specific requirements of any framework project are listed below.

Carthage will only build Xcode schemes that are shared from your.xcodeproj. You can see if all of your intended schemes build successfully by runningcarthage build --no-skip-current, then checking theCarthage/Build folder.

If an important scheme is not built when you run that command, open Xcode and make sure that thescheme is marked asShared, so Carthage can discover it.

If you encounter build failures incarthage build --no-skip-current, try runningxcodebuild -scheme SCHEME -workspace WORKSPACE build orxcodebuild -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), usexcode-select to change which version Carthage uses.

If you’re still not able to build your framework with Carthage, pleaseopen an issue and we’d be happy to help!

Carthage determines which versions of your framework are available by searching through the tags published on the repository, and trying to interpret each tag name as asemantic version. For example, in the tagv1.2, the semantic version is 1.2.0.

Tags without any version number, or with any characters following the version number (e.g.,1.2-alpha-1) are currently unsupported, and will be ignored.

Carthage can automatically use prebuilt frameworks, instead of building from scratch, if they are attached to aGitHub Release on your project’s repository or via a binary project definition file.

To offer prebuilt frameworks for a specific tag, the binaries forall supported platforms should be zipped up together intoone archive, and that archive should be attached to a published Release corresponding to that tag. The attachment should include.framework in its name (e.g.,ReactiveCocoa.framework.zip), to indicate to Carthage that it contains binaries. The directory structure of the archive is free form but,frameworks should only appear once in the archive as they will be copiedtoCarthage/Build/<platform> based on their name (e.g.ReactiveCocoa.framework).

To offer prebuilt XCFrameworks, build with--use-xcframeworks and follow the same process to zip up all XCFrameworks into one archive. Include.xcframework in the attachment name. Starting in version 0.38.0, Carthage prefers downloading.xcframework attachments when--use-xcframeworks is passed.

You can perform the archiving operation with carthage itself using:

-carthage build --no-skip-current-carthage archive YourFrameworkName

or alternatively

carthage build --archive

Draft Releases will be automatically ignored, even if they correspond to the desired tag.

It is possible to use travis-ci in order to build and upload your tagged releases.

1. Install travis CLI withgem install travis

2. Setup travis-ci for your repository (Steps 1 and 2)

3. Create.travis.yml file at the root of your repository based on that template. SetFRAMEWORK_NAME to the correct value.

   Replace PROJECT_PLACEHOLDER and SCHEME_PLACEHOLDER

   If you are using aworkspace instead of aproject remove the xcode_project line and uncomment the xcode_workspace line.

   The project should be in the format: MyProject.xcodeproj

   The workspace should be in the format: MyWorkspace.xcworkspace

   Feel free to update thexcode_sdk value to another SDK, note that testing on iphoneos SDK would require you to upload a code signing identity

   For more informations you can visittravis docs for objective-c projects

   language:objective-cosx_image:xcode7.3xcode_project:<PROJECT_PLACEHOLDER># xcode_workspace: <WORKSPACE_PLACEHOLDER>xcode_scheme:<SCHEME_PLACEHOLDER>xcode_sdk:iphonesimulator9.3env:global:    -FRAMEWORK_NAME=<THIS_IS_A_PLACEHOLDER_REPLACE_ME>before_install:  -brew update  -brew outdated carthage || brew upgrade carthagebefore_script:# bootstrap the dependencies for the project# you can remove if you don't have dependencies  -carthage bootstrapbefore_deploy:  -carthage build --no-skip-current  -carthage archive $FRAMEWORK_NAME

4. Runtravis setup releases, follow documentationhere

   This command will encode your GitHub credentials into the.travis.yml file in order to let travis upload the release to GitHub.comWhen prompted for the file to upload, enter$FRAMEWORK_NAME.framework.zip

5. Update the deploy section to run on tags:

   In.travis.yml locate:

   on:repo:repo/repo

   And addtags: true andskip_cleanup: true:

   skip_cleanup:trueon:repo:repo/repotags:true

   That will let travis know to create a deployment when a new tag is pushed and prevent travis to cleanup the generated zip file

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.

Since version 0.30.0 Carthage project rolls out support for statically linked frameworks written in Swift or Objective-C, support for which has been introduced in Xcode 9.4. Please note however that it specifically saysframeworks, hence Darwin bundles with.framework extension and statically linked object archives inside. Carthage does not currently support staticlibrary schemes, nor are there any plans to introduce their support in the future.

The workflow differs barely:

• You still need to tick your Carthage-compliant project's schemes asshared inProduct > Scheme > Manage Schemes..., just as with dynamic binaries
• You still need to link against static.frameworks in your project'sBuild Phases just as with dynamic binaries

However:

• In your Carthage-compliant project's Cocoa Framework target'sBuild Settings,Linking section, setMach-O Type toStatic Library
• Your statically linked frameworks will be built at./Carthage/Build/$(PLATFORM_NAME)/Static
• You should not add any of static frameworks as input/output files incarthage copy-frameworksBuild Phase

See theStaticFrameworks doc for details.

Please note that a few caveats apply to this approach:

• Swift static frameworks are not officially supported by Apple
• This is an advanced workflow that is not built into Carthage, YMMV

Want to advertise that your project can be used with Carthage? You can add a compatibility badge:

… to yourREADME, by simply inserting the following Markdown:

[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

Pre-built framework cannot be debugged using step execution on other machine than on which the framework was built. Simplycarthage bootstrap/build/update --no-use-binaries should fix this, but for more automated workaround, see#924. Duperdar://23551273 if you want Apple to fix the root cause of this problem.

Most of the functionality of thecarthage 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 theCarthageKit source code to see if the API fits your needs.

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 usingxcodebuild, 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 itsREADME 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 adecentralized 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’sTrending pages or similar.

CocoaPods projects must also have what’s known as apodspec file, which includes metadata about the project and specifies how it should be built. Carthage usesxcodebuild 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.

Carthage is released under theMIT License.

Header backdrop photo is released under theCC BY-NC-SA 2.0 license. Original photo byRichard Mortel.