Carthage / Carthage

Carthage 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 Quick Start • Get Carthage by running or choose another installation method • Create a [Cartfile][] in the same directory where your or is • List the desired dependencies in the [Cartfile][], for example: • Run • A file and a directory will appear in the same directory where your or is • Drag the built bundles from into the "Frameworks and Libraries" section of your application’s Xcode project. • If you are using Carthage for an application, select "Embed & Sign", otherwise "Do Not Embed". For an in depth guide, read on from Adding frameworks to an application Installing Carthage There are multiple options for installing Carthage: • **Installer:** Download and run the file for the latest release, then follow the on-screen instructions. If you are installing the pkg via CLI, you might need to run first. • **Homebrew:** You can use Homebrew and install the tool on your system simply by running and . (note: if you previously installed the binary version of Carthage, you should delete ). • **MacPorts:** You can use MacPorts and install the tool on your system simply by running and . (note: if you previously installed the binary version of Carthage, you should delete ). • **From source:** If you’d like to run the latest development version (which may be highly unstable or incompatible), simply clone the branch of the repository, then run . Requires Xcode 10.0 (Swift 4.2). Adding frameworks to an application 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). 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 . 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 • Delete your folder to remove any existing framework bundles. • Build new XCFrameworks by running . Any other arguments you build with can be provided like normal. • 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 build phase, if present. • 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. Building platform-specific framework bundles (default for Xcode 11 and below) **Xcode 12+ incompatibility**: Multi-architecture platforms are not supported when building framework bundles in Xcode 12 and above. Prefer building with XCFrameworks. If you need to build discrete framework bundles, use a workaround xcconfig file. If you're building for macOS macOS-specific instructions • Create a [Cartfile][] that lists the frameworks you’d like to use in your project. • Run . 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,…