A simple, decentralized dependency manager for Cocoa

Carthage

Last update: Dec 29, 2022

Related tags

Overview

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
Supporting Carthage for your framework
Known issues
- DWARFs symbol problem
CarthageKit
Differences between Carthage and CocoaPods
License

Quick Start

Get Carthage by running brew install carthage or choose another installation method
Create a Cartfile in the same directory where your .xcodeproj or .xcworkspace is
List the desired dependencies in the Cartfile, for example:
```
github "Alamofire/Alamofire" ~> 4.7.2
```
Run carthage update --use-xcframeworks
A Cartfile.resolved file and a Carthage directory will appear in the same directory where your .xcodeproj or .xcworkspace is
Drag the built .xcframework bundles from Carthage/Build 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 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 run sudo chown -R $(whoami) /usr/local first.
Homebrew: You can use Homebrew and install the carthage tool on your system simply by running brew update and brew 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 running sudo port selfupdate and sudo 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 run make install. 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 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

Delete your Carthage/Build folder to remove any existing framework bundles.
Build new XCFrameworks by running carthage build --use-xcframeworks. 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 carthage copy-frameworks 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 carthage update --platform macOS. 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.

If you're building for iOS, tvOS, or watchOS

Platform-specific instructions

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.
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.
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
```
Create a file named input.xcfilelist and a file named output.xcfilelist

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

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.
Add the input.xcfilelist to the "Input File Lists" section of the Carthage run script phase
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 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. 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 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 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.

Adding frameworks to unit tests or a framework

Using Carthage for the dependencies of any arbitrary target is fairly similar to using 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 the Linked Frameworks and Libraries section in their General settings tab, you must instead drag the built frameworks to the Link Binaries With Libraries build phase.

In the Test target under the Build Settings tab, add @loader_path/Frameworks to the Runpath 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 new Copy Files build phase with the Frameworks destination, then add the framework reference there as well. You shouldn't use the carthage copy-frameworks command since test bundles don't need frameworks stripped, and running concurrent instances of copy-frameworks (with parallel builds turn on) is not supported.

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

carthage update Box Result

Experimental Resolver

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

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

Supporting Carthage for your framework

Carthage only officially supports dynamic frameworks. Dynamic frameworks can be used on any version of OS X, but only on iOS 8 or later. Additionally, since version 0.30.0 Carthage supports static 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.

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!

Tag stable releases

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 a semantic version. For example, in the tag v1.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.

Archive prebuilt frameworks into zip files

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

To offer prebuilt frameworks for a specific tag, the binaries for all supported platforms should be zipped up together into one 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 copied to Carthage/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.

Use travis-ci to upload your tagged prebuilt frameworks

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

Install travis CLI with gem install travis
Setup travis-ci for your repository (Steps 1 and 2)
Create .travis.yml file at the root of your repository based on that template. Set FRAMEWORK_NAME to the correct value.

Replace PROJECT_PLACEHOLDER and SCHEME_PLACEHOLDER

If you are using a workspace instead of a project 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 the xcode_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 visit travis docs for objective-c projects
```
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
```
Run travis setup releases, follow documentation here

This command will encode your GitHub credentials into the .travis.yml file in order to let travis upload the release to GitHub.com When prompted for the file to upload, enter $FRAMEWORK_NAME.framework.zip
Update the deploy section to run on tags:

In .travis.yml locate:
```
on:
  repo: repo/repo
```
And add tags: true and skip_cleanup: true:
```
skip_cleanup: true
on:
  repo: repo/repo
  tags: 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

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.

Carthage 0.30.0 or higher

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 says frameworks, hence Darwin bundles with .framework extension and statically linked object archives inside. Carthage does not currently support static library 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 as shared in Product > Scheme > Manage Schemes..., just as with dynamic binaries
You still need to link against static .frameworks in your project's Build Phases just as with dynamic binaries

However:

In your Carthage-compliant project's Cocoa Framework target's Build Settings, Linking section, set Mach-O Type to Static 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 in carthage copy-frameworks Build Phase

Carthage 0.29.0 or lower

See the StaticFrameworks 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

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.

License

Carthage is released under the MIT License.

Header backdrop photo is released under the CC BY-NC-SA 2.0 license. Original photo by Richard Mortel.

Comments

Carthage builds fail at xcrun lipo on Xcode 12 beta (3,4,5...)

carthage install method: [ ] .pkg, [x] homebrew, [x] source
which carthage: /usr/local/bin/carthage
carthage version: 0.35.0
xcodebuild -version: 12A8169g
Are you using --no-build? No
Are you using --no-use-binaries? No
Are you using --use-submodules? No
Are you using --cache-builds? No
Are you using --new-resolver? No

Cartfile

github "LoungeBuddy/Auth0.swift" "feature/decouple-keychain-manager"
binary "https://raw.githubusercontent.com/Instabug/Instabug-iOS/master/Instabug.json"

Carthage Output

> carthage build --platform iOS

*** xcodebuild output can be found in /var/folders/jm/pyy6p95j177_btm91tj0mkdm0000gn/T/carthage-xcodebuild.WPi9jL.log
*** Downloading binary-only framework Instabug at "https://raw.githubusercontent.com/Instabug/Instabug-iOS/master/Instabug.json"
*** Building scheme "JWTDecode-iOS" in JWTDecode.xcodeproj
Build Failed
	Task failed with exit code 1:
	/usr/bin/xcrun lipo -create /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Intermediates.noindex/ArchiveIntermediates/JWTDecode-iOS/IntermediateBuildFilesPath/UninstalledProducts/iphoneos/JWTDecode.framework/JWTDecode /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Products/Release-iphonesimulator/JWTDecode.framework/JWTDecode -output /Volumes/Shared/LoungeBuddy/consumer-ios-app/Carthage/Build/iOS/JWTDecode.framework/JWTDecode

This usually indicates that project itself failed to compile. Please check the xcodebuild log for more details: /var/folders/jm/pyy6p95j177_btm91tj0mkdm0000gn/T/carthage-xcodebuild.WPi9jL.log

Running the problem command:

> /usr/bin/xcrun lipo -create /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Intermediates.noindex/ArchiveIntermediates/JWTDecode-iOS/IntermediateBuildFilesPath/UninstalledProducts/iphoneos/JWTDecode.framework/JWTDecode /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Products/Release-iphonesimulator/JWTDecode.framework/JWTDecode -output /Volumes/Shared/LoungeBuddy/consumer-ios-app/Carthage/Build/iOS/JWTDecode.framework/JWTDecode

fatal error: /Applications/Xcode-12-beta-3.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/lipo: /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Intermediates.noindex/ArchiveIntermediates/JWTDecode-iOS/IntermediateBuildFilesPath/UninstalledProducts/iphoneos/JWTDecode.framework/JWTDecode and /Users/swarn1/Library/Caches/org.carthage.CarthageKit/DerivedData/12.0_12A8169g/JWTDecode.swift/2.4.1/Build/Products/Release-iphonesimulator/JWTDecode.framework/JWTDecode have the same architectures (arm64) and can't be in the same fat output file

Actual outcome

Carthage fails to build any dependencies.
Carthage advises to look at a build log which ends with ** BUILD SUCCEEDED **

Expected outcome

Carthage should not fail to build.
On failures outside of xcodebuild, Carthage should not direct you to the build log.

Workaround I guess the architecture for iphonesimulator has changed such that it now collides with iphoneos? Not sure how this stuff works. Either way, I've been able to work around the problem by changing Sources/CarthageKit/Xcode.swift:742 to argsForBuilding.onlyActiveArchitecture = true. Obviously, this is not a great solution.

bug help wanted possible-workaround

opened by sam-w 271

Consider module stability when building frameworks
Don't fail builds because the local Swift version doesn't match the framework Swift version if both are module stable

[x] Consider whether the framework is built for distribution

[x] Bikeshed naming

[x] Reformat spaces to tabs

[x] Discuss better approaches with reviewers

[x] Update tests
opened by DavidBrunow 73
Allow builds to skip iOS and watchOS device SDKs when the codesigning identity is not installed

This addresses issues #576, #235, and #281, by adding a new --simulator-only flag, and also properly treating the iphonesimulator and watchsimulator values for the --platform flag.

I added associated value for Platform and BuildPlatform attached to the .iOS and .watchOS values, in addition to passing a simulatorOnly parameter around between functions. After adding the associated values, I also had to implement the == overload to keep the enums Equatable and allow them to be used in switch statements.

opened by abbeycode 62
iOS frameworks built with Carthage cannot be submitted to the App Store

From @soffes in https://github.com/Carthage/Carthage/issues/174#issuecomment-65187702:

I've been dragging the projects into my project and setting up dependencies in Xcode for building. You can't submit iOS frameworks with x86. Couldn't find a way to do a "release build" in carthage so that was my work around.

IOW, our fat binary is inadmissable to the App Store, apparently.
bug build

opened by jspahrsummers 60
Create XCFrameworks and retain project compatibility
Hey! I want to propose an alternate xcframeworks implementation to #2801 and #2881. This PR fixes #3019 by combining built frameworks into an xcframework when supported.

I don't mean to steal @tmspzz's thunder here, just wanted to give us another implementation to consider. I'm trying to keep the PR small and retain full compatibility with existing projects.

I've tested this in a large iOS+watchOS project (the Yelp app) and on some smaller multiplatform projects. I'm sure there are edge cases I'm missing -- would love for others to try this branch out and let me know what you find 🙂

Summary of changes

By default, all frameworks built for a dependency will be merged into an xcframework in Carthage/Build.

Building the same dependency multiple times with different --platform is supported -- new build products will be merged into an existing xcframework.

Similarly, rebuilding a dependency replaces previous builds for that platform in the xcframework.

xcframework creation can be disabled with --no-create-xcframework, and is disabled by default on systems without Xcode 12.

No configuration changes required for existing dependencies to support xcframeworks.

The xcframework is created using -allow-internal-distribution , which prevents it from requiring the usual BUILD_LIBRARY_FOR_DISTRIBUTION=YES / SKIP_INSTALL=NO.

When building, Carthage extracts platform-specific frameworks to a temporary directory and passes that directory to Xcode. This allows frameworks to link against nested dependencies without adding xcframeworks to their project.

Xcode 12 is required when creating an xcframework

This allows Carthage to embed dSYMs and bcsymbolmaps into the xcframework bundle, so we don't have to do additional work to manage multiple dSYMs.

Version file (--cache-builds) support is complete.

Each entry in a version file still corresponds to one framework bundle, but frameworks contained in xcframeworks have additional container and identifier fields that describe their location within the .xcframework directory.

Cache tools like Rome can support xcframeworks by caching the container directory when present.

No copy-frameworks support. Users should embed xcframeworks directly in Xcode instead of using copy-frameworks.

enhancement
opened by elliottwilliams 57
Static *framework* support

I know that Carthage only support dynamic frameworks at the moment. I realize it's significantly more difficult to support plain static libraries because you need to keep track of both the binary library and the headers, but has there been much thought about support static frameworks?

Xcode doesn't provide a template for this out of the box, but if you create a dynamic framework target and then change the Mach-O type to static library, the compiled product is then a .framework, with proper modulemap and headers. I've been playing around with this today and it seems to work pretty well when just dropping the framework into a project. Here is a test framework that I made and used lipo to create a universal iOS binary: http://cl.ly/3s332V3g0S08. You can drop it into any project (both framework and app) and import like any other framework. Even in a Swift project. (AThing.coolThing() if you want to try and use the code in the framework.)

Note that there is one big downside to static frameworks in that they can not contain assets like images, but I would bet a large majority of libraries don't use assets.

I've been thinking about this quit a bit after attending WWDC 2016 Session 406 "Optimizing App Startup Time". In that talk they discuss how dynamic frameworks can slow down the launch of your app because of the work needed to link the libraries. According to the session, static libraries don't have this issue because the work is done at compile time.
question

opened by davbeck 54
Exclude specific schemes via Cartfile.ignore
Closes #1227, #437 and maybe more.

Goal

My goal ist to ensure that with a Cartfile that looks like this:

github "Moya/Moya"

Which would normally build Moya, RxMoya, ReactiveMoya, Alamofire, Result, RxSwift and ReactiveSwift. To introduce a new file named Cartfile.ignore with something like this content:

# Ignore RxSwift variant of Moya scheme "RxMoya" scheme "RxSwift" # Ignore ReactiveSwift variant of Moya scheme "ReactiveMoya" scheme "ReactiveSwift"

Which leads to Carthage only building Moya, Alamofire and Result.

In detail the structure of the Cartfile.ignore is highly inspired by the structure of the current existing Cartfile. Instead keys like github and git the .ignore file should only support scheme.

scheme

This is the first step I want to reach – to ensure all schemes with the name specified after a scheme entry within the Cartfile.ignore are not built when running Carthage tasks. Note that the user is being notified about this with something like *** Ignoring scheme "RxMoya" in Moya.xcworkspace.

UPDATE NOTE: Originally I also had the suggestion to introduce a project keyword which would then even prevent from downloading the dependency. See the section "Where to go from here" below where I consider an alternative for that which can be added later on, in a subsequent PR.

Please also note, that since this change is purely additive, there should be no side effects whatsoever to any Carthage users who don't specifically create a Cartfile.ignore to use this feature.

Use the Cartfile.ignore right now via Carthage-Pro

I created a fork of Carthage until this gets merged (which might take years) which includes this feature already. Please read this comment further below for additional details.

Where to go from here

Here are a few "Next Steps" possible after this PR is merged to go further into this direction:

[ ] Add the possibility to ignore a dependency even during dependency graph resolution by adding support for entries like github "ReactiveCocoa/ReactiveSwift"

[ ] Consider the Cartfile.ignore in dependencies during dependency graph resolution so framework authors can improve the build time for their Carthage users without extra-work for them

enhancement
opened by Jeehut 50
BITCODE support
Reading the release notes, I stumbled upon this:

ENABLE_BITCODE should be consistently turned on for all the targets. If you use a library or framework provided by a third party, please contact the vendor for an updated version which contains bitcode.

Given that Carthage is simply built on top of xcodebuild (yay!), it's likely that nothing will need to be changed. When compiling frameworks for dependencies using Xcode 7 (which hopefuly will have ENABLE_BITCODE set to true by default), it will do the right thing.

I figured I'd open an issue to keep track of this though :)

Happy Swifting!
help wanted build
opened by NachoSoto 50
Support xcframeworks
Implement support for #2799

This feature involves:

[x] supporting creation of xcframeworks in build

[x] supporting creation of archives with xcframeworks

[x] supporting binary xcframeworks

[ ] avoiding xcframeworks in copy-frameworks

[ ] dSYMs ?

enhancement
opened by tmspzz 49
Correct framework DWARFs and symbols to workaround broken debugging 🔥
This is a follow up to #832 with details on a possible solution.

The story:

We've all been aware since the very beginning that debugging projects that include pre-compiled (Carthage) frameworks has been very broken. As Apple promised that this got better in Xcode 7.2, a few people on #832 did the test (I still can't test it myself because reasons), and realized that it's still just as broken.

Upon further investigation, looks like DWARF files use absolute paths everywhere, based on when they were compiled.

Using dwarfdump:

As you can see, they're full of paths to the derived data directory of the user who built the framework. Needless to say, it's not just a problem because we can't share these frameworks with other devs, but also for personal use, given how extremely frequent one must clear derived data to work around Xcode.

This is why I finally decided to file a radar, because after two years this is still utterly broken: http://www.openradar.me/23551273.

Of course, I don't expect this to be fixed (ever?), so we need a solution.

Proposed solutions

Abandon Carthage:

We can go back to working like animals, adding all dependencies as submodules. However, this just doesn't cut it, Apple, when will you see this?

Swift compilation times are already insanely long. Khan Academy was taking 15 minutes for a clean build before I changed Swift dependencies to pre-compiled frameworks.

Nested dependencies: this solution would not be feasible if you have multiple dependencies that depend on a common one. This is one of the reasons why CocoaPods was born:

CocoaPods

(Yeah, I went there, but I wanted to analyze this too)

Obviously deals with the dependency graph problem.

It's invasive and very complex, which is why Carthage was born.

It's still not what we want for development. It's the year 2015, we want to be able to distribute built dependencies and compile our applications in the order of seconds, not minutes.

Work around it in Carthage

I have an idea that might work. Distributing pre-compiled frameworks would still be broken (so --no-use-binaries would have to be the only option), but we'd be able to compile once and forget:

xcodebuild -sdk $SDK -project $PROJECT -configuration Release -scheme $SCHEME ONLY_ACTIVE_ARCH=NO SYMROOT=$DIR/Carthage/Build/$PLATFORM/$FRAMEWORK clean build

Notice the SYMROOT parameter. In my tests compiling with this option correctly sets the absolute paths in the DWARF to that path, instead of derived data! Which means that debugging should hopefully work.

With this, the recommended approach would be to .gitignore Carthage/Build, and using carthage update to build the frameworks.

Once we do that, one can freely clear derived data, and that won't affect the compiled frameworks.

It's still not clear that this is enough, though. It's possible that we'll also need OBJROOT, and putting everything in Carthage/Build:

Prolonged sigh.
bug help wanted
opened by NachoSoto 49
Unable to find iOS Simulators (Post Xcode 10.2 install)
carthage install method: [ ] .pkg, [x] homebrew, [ ] source

which carthage: /usr/local/bin/carthage

carthage version: 0.31.2

xcodebuild -version: 10.1

After installing Xcode 10.2, Carthage fails to build any project due to Could not find any available simulators for iOS. I've tried a number of different things to resolve it:

Build a project in Xcode 10.2 on a simulator (suggested in #2690)

Use Xcode.app and Xcode-beta.appfor xcode-select.

Reset all my simulators etc.

I think the problem is the keys that are in the output of simctl. Looking through Simulator.swift in CarthageKit I can see that it expects to find a platform prefix for the key (i.e. iOS) - my keys however are formatted like this: com.apple.CoreSimulator.SimRuntime.iOS-12-1.

Is this a problem with my installation? Or is it something that has changed in Xcode 10.2 and should be supported in Carthage?

Example xcrun simctl list devices --json output:

"com.apple.CoreSimulator.SimRuntime.iOS-12-1" : [ { "availability" : "(available)", "state" : "Shutdown", "isAvailable" : true, "name" : "iPhone 5s", "udid" : "9AC9332D-7DB0-4F2E-8615-61EE86E363CA", "availabilityError" : "" }, { "availability" : "(available)", "state" : "Shutdown", "isAvailable" : true, "name" : "iPhone 6", "udid" : "B1DA5CFF-D918-467B-8E49-04B6172B9456", "availabilityError" : "" } ]
opened by msaps 48

With XCode 14, Carthage throwing Command PhaseScript Execution failed with non zero exit code

carthage install method: [ ] .pkg, [ ✅ ] homebrew, [ ] source
which carthage: /usr/local/bin/carthage
carthage version: 0.38.0
xcodebuild -version: XCode 14.2 Build Version 14C18
Are you using --no-build? NO
Are you using --no-use-binaries? NO
Are you using --use-submodules? NO
Are you using --cache-builds? NO
Are you using --new-resolver? NO
Are you using --use-xcframeworks? YES

Carthage Output

exit code 0

Actual outcome Carthage compiles successfully When we build and run on simulator, the code throws 'Command Phase Script execution failed with non zero exit code' This happen when it tries to run the script for 'Remove unwanted architecture from Carthage'

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

For every dependancies we get the error:

Executable is Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith
Extracting x86_64 from Locksmith
fatal error: lipo: input file (Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith) must be a fat file when the -extract option is specified
Merging extracted architectures: x86_64
fatal error: lipo: can't open input file: Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith-x86_64 (No such file or directory)
rm: Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith-x86_64: No such file or directory
Replacing original executable with thinned version
mv: rename Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith-merged to Build/Products/Debug-iphonesimulator/MyApp.app/Frameworks/Locksmith.framework/Locksmith: No such file or directory

🚀 When we enable the Run Script for 'For install builds only', we are able to build and run the code. 🚀 _ ❌ The above didnt work on our CircleCI pipelines ❌ _

Expected outcome Xcode should be able to build and run the code without any error during debug and archive builds.

Need help on how to make this work on the latest XCode.

opened by amit-thakur-S 1

When using Carthage to build, xcodebuild error "Unhandled/unexpected case where no run destinations were produced."

carthage install method: [ ] .pkg, [ x] homebrew, [ ] source
which carthage: /opt/homebrew/bin/carthage
carthage version: 0.38.0
xcodebuild -version: Xcode 14.0.1 Build version 14A400
Are you using --no-build? no
Are you using --no-use-binaries? no
Are you using --use-submodules? no
Are you using --cache-builds? no
Are you using --new-resolver? no
Are you using --use-xcframeworks? yes

Cartfile

github "wordpress-mobile/AztecEditor-iOS" "develop"

Carthage Output

❯ carthage update --use-xcframeworks
*** Fetching AztecEditor-iOS
*** Checking out AztecEditor-iOS at "b7d8a70582133a329b6e4502e437b7a3cdd4ffb6"
*** xcodebuild output can be found in /var/folders/2c/py4twb5x471gqdhp0khhkz600000gn/T/carthage-xcodebuild.AUeT5z.log
A shell task (/usr/bin/xcrun xcodebuild -project /Users/tim/src/ios/sharpen.git/Carthage/Checkouts/AztecEditor-iOS/Aztec.xcodeproj -scheme Carthage\ Update -configuration Release CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= CARTHAGE=YES archive -showBuildSettings -skipUnavailableActions) failed with exit code 6:
2022-10-05 15:17:16.472 xcodebuild[41334:40820482] [MT] DVTAssertions: ASSERTION FAILURE in /System/Volumes/Data/SWE/Apps/DT/BuildRoots/BuildRoot2/ActiveBuildRoot/Library/Caches/com.apple.xbs/Sources/IDEFrameworks/IDEFrameworks-21336/IDEFoundation/Execution/RunDestinations/IDERunDestinationCLI.m:566
Details:  Unhandled/unexpected case where no run destinations were produced.
Object:   <IDERunDestinationCLI>
Method:   +resolveRunDestinationsWithWorkspace:scheme:buildAction:schemeCommand:schemeTask:destinationSpecifications:architectures:timeout:runDestinationManager:deviceManager:fallbackPreferredSDK:fallbackPreferredArchitectures:skipUnsupportedDestinations:shouldSkipRunDestinationValidation:didDisambiguate:disambiguatedMatches:disambiguatedMatchesDescription:error:
Thread:   <_NSMainThread: 0x600000ab4240>{number = 1, name = main}
Hints:

Backtrace:
  0   -[DVTAssertionHandler handleFailureInMethod:object:fileName:lineNumber:assertionSignature:messageFormat:arguments:] (in DVTFoundation)
  1   _DVTAssertionHandler (in DVTFoundation)
  2   _DVTAssertionFailureHandler (in DVTFoundation)
  3   _sortDevicesForDisplay (in IDEFoundation)
  4   -[Xcode3CommandLineBuildTool _resolveRunDestinationsForBuildAction:] (in Xcode3Core)
  5   -[Xcode3CommandLineBuildTool _resolveInputOptionsWithTimingSection:] (in Xcode3Core)
  6   -[Xcode3CommandLineBuildTool run] (in Xcode3Core)
  7   XcodeBuildMain (in libxcodebuildLoader.dylib)
  8   start (in dyld)

Actual outcome Carthage did not build

Expected outcome Carthage should build

I looked at the command line generated by Carthage:

/usr/bin/xcrun xcodebuild -project /Users/tim/src/ios/sharpen.git/Carthage/Checkouts/AztecEditor-iOS/Aztec.xcodeproj -scheme Carthage\ Update -configuration Release CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= CARTHAGE=YES archive -showBuildSettings -skipUnavailableActions

if I remove all the parameters, the project builds. I suspect the issue is with "-scheme Carthage\ Update" but it might also be related to the other parameters - I tried removing one or two parameters and couldn't find a magic combo. Removing all parameters causes the project to build properly.

opened by teemobean 8

How can I declare a dependency for Binary Project Specification dependencies?
I have A.xcframework which depends on B.xcframework. Both are prebuilt.

I wrote a spec file so that my consumers could consume A:

{ "1.0.0": "https://raw.githubusercontent.com/A/a/1.0.0/A.xcframework.zip" }

But the thing is, A needs B and I would like to declare this dependency - and I was wondering, how could I do that?

I want my consumers of A to also download B.
opened by isaac-weisberg 1
Issue when inside framework have another module (pods)
carthage install method: [ ] .pkg, [ X] homebrew, [ ] source

which carthage: opt/homebrew/bin/carthage

carthage version: 0.38.0

xcodebuild -version: XCode 13.4.1 - Build version 13F100

Are you using --no-build? No

Are you using --no-use-binaries? No

Are you using --use-submodules? No

Are you using --cache-builds? No

Are you using --new-resolver? No

Are you using --use-xcframeworks? Yes

Actual outcome It's ok and can be running well and ok when build. But unfortunately, after the simulator run and it got an error dyld: Library not loaded. And also I have pods inside my framework like alamofire, etc. I want to know if I have a third party inside my framework how can I upload it and can be running well on my simulator? Thank you

Expected outcome This issue should be running well on my simulator or my iphone.
opened by udemy-freelance 0

Releases(0.38.0)

0.38.0(May 7, 2021)
Fixed

Building XCFrameworks with nested dependencies no longer requires a platform-specific Build directory (i.e. Carthage/Build/iOS) to exist (#3135).

Added

Prebuilt dependencies (for binary only frameworks and GitHub release assets) may use XCFrameworks, which are checked for compatibility and extracted into the Build folder (#3123). See the section below on compatibility information for framework authors. Thanks @igstewart3! :tada:

Project lookup is faster for dependencies which contain multiple xcodeprojs (#3076).

Known issues

carthage archive does not archive built XCFrameworks

Support for making an xcframework archive will be added in a future release. For now, manually create archives by building twice: once with the --use-xcframeworks option, and once without. Then, create a zip from the Carthage/Build folder.

How to distribute XCFrameworks while retaining backwards compatibility

Since Carthage lets users choose whether they want discrete frameworks or XCFrameworks, we recommend supporting both distribution formats in your binary assets. Replacing discrete frameworks with XCFrameworks in your assets is a breaking change, since it will require users to reintegrate the framework with their project.

Create separate .framework.zip and .xcframework.zip archives

Starting in 0.38.0, Carthage follows a naming convention to distinguish between XCFrameworks and plain framework bundles:

A release asset with .xcframework in the name is considered to contain XCFrameworks

An asset with .framework in the name is considered to contain plain framework bundles

Carthage looks to narrow download candidates when comparable filenames are found → the comparison is ‘do the filenames match after removing one «.framework» or one «.xcframework» found string from the filename?'. This allows to Carthage to narrow down to one comparison-matched download, basing direction on whether --use-xcframeworks is flagged. Sets entirely 'not-matching-comparison' will see no removal of download candidates.

GitHub release assets: Upload both archives to the release

GitHub releases can have multiple files attached to them. Upload both zip files to your release following the above naming convention. See the README for more information.

Binary only frameworks: Specify both archives in the binary spec URL using an alt= parameter.

Binary project specifications are JSON documents which map one download URL to one version. To provide multiple asset URLs, join the URLs with an alt= query parameter. For example:

{ "1.2.3": "https://example.com/releases/MyFramework-v1.2.3.framework.zip?alt=https://example.com/releases/MyFramework-v1.2.3.xcframework.zip" }

Older versions of Carthage will request the whole URL and will receive the first framework zip (since HTTP servers ignore unknown query parameters). Starting in 0.38.0, Carthage will parse out any alt URLs and request them as well, using the same naming convention we use for GitHub assets.

For optimal backwards compatibility:

Create an upload a framework zip and an xcframework zip, and give them the same basename, i.e. MyFramework-v1.2.3.framework.zip and MyFramework-v1.2.3.xcframework.zip.

Publish the binary spec JSON with the framework zip's URL first, followed by an alt= parameter with the xcframework zip's URL.

Example workflow

Suppose we're releasing v1.2.3 of a project called MyFramework:

Create an xcframeworks build using --use-xcframeworks:

carthage build --use-xcframeworks --no-skip-current zip -r MyFramework-v1.2.3.xcframework.zip Carthage/Build

Create a plain frameworks build:

carthage build --no-skip-current zip -r MyFramework-v1.2.3.framework.zip Carthage/Build

Upload both archives, MyFramework-v1.2.3.xcframework.zip and MyFramework-v1.2.3.framework.zip.

For projects on GitHub, create a release and include both archives.

For a binary-only framework, publish a new version to its spec JSON. Point to the xcframework archive using an alt= parameter:

{ // ... "1.2.3": "https://example.com/releases/MyFramework-v1.2.3.framework.zip?alt=https://example.com/releases/MyFramework-v1.2.3.xcframework.zip" }

Prefer building with module stability

Carthage compares the Swift compiler version used to build an XCFramework with the currently selected Swift version — allowing the XCFramework to supercede a local-machine build if the downloaded XCFramework:

contains no bundles with «.swiftmodule»-suffixed files, or

any bundle with «.swiftmodule»-suffixed files contains Swift components built under BUILD_LIBRARIES_FOR_DISTRIBUTION build setting and the current Swift compiler version is greater than 5.1, or

any bundle not passing the above was built with the current compiler version.

〜 Carthage falls back to building a dependency from source if the prebuilt version is rejected.
〜 Note: see particulars on Carthage’s determining factors for BUILD_LIBRARIES_FOR_DISTRIBUTION.

✨ This matches Carthage's existing behavior, but is notably different from Swift Package Manager’s behavior, which requires that all XCFrameworks are built for distribution. When you're creating XCFrameworks for a GitHub release, be mindful of this, and consider setting BUILD_LIBRARIES_FOR_DISTRIBUTION=YES in your project. Future versions of Carthage's archive command may encourage this setting.

If you choose to publish an XCFramework without module stability (a.k.a. BUILD_LIBRARIES_FOR_DISTRIBUTION build setting) enabled, consider a naming convention like *-carthage-abi-unstable.xcframework to indicate this to your users.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(4.82 MB)
0.37.0(Feb 1, 2021)
Fixed

Building a framework using Xcode 12 fails with a build error from xcrun lipo (https://github.com/Carthage/Carthage/issues/3019). Fix by passing --use-xcframeworks and re-integrating your dependencies as XCFrameworks, or by using a workaround xcconfig on Intel-based Macs.

Added

Carthage produces XCFrameworks instead of universal frameworks when --use-xcframeworks is passed. (https://github.com/Carthage/Carthage/pull/3071). Thanks @elliottwilliams!

XCFrameworks contain multiple discrete framework bundles. Unlike universal frameworks (produced by lipo), an XCFramework can contain multiple versions of a framework which share the same processor architecture. Since Xcode 12 added Apple Silicon support to its simulator platforms, the device and simulator versions of a framework both build for arm64, hence requiring an XCFramework.

To build XCFrameworks into your app, run Carthage with --use-xcframeworks and drag the produced XCFrameworks into your Xcode target’s Embedded binaries section, without using a carthage copy-frameworks script phase. ﹡See the README﹡ for information on how to upgrade to XCFrameworks.

XCFrameworks are the only supported way to build Carthage frameworks for Apple Silicon-based Macs.

Known issues

--use-xcframeworks does not produce an XCFramework for github dependencies which download binaries.

Workaround: Pass --no-use-binaries to make Carthage rebuild the dependency from source, which will produce an XCFramework.

carthage archive does not archive built XCFrameworks, and --use-xcframeworks does not produce an xcframework for binary dependencies.

Support for binary xcframeworks will be added in a future release. For now, continue integrating binary dependencies using the strategy of platform-specific frameworks.

Notes

Under --use-xcframeworks, Carthage aims to accommodate something long relied upon: targets that 〈think about targets such as your dependencies ⋯ subdependencies ⋯ dependencies vended by others〉 …that link against «.framework»s in the directory of Carthage/Build ﹡as opposed to linking against «.framework»s in Per-configuration Build Products Path (CONFIGURATION_BUILD_DIR).﹡

Such targets will see Carthage extract — for each platform the target builds for — such-platform’s «.framework» bundles from all XCFrameworks, copying them into a temporary directory, and then — via build setting injection into FRAMEWORK_SEARCH_PATHS — allowing the xcodebuild run an at-the-end-of-FRAMEWORK_SEARCH_PATHS opportunity to link those extracted-into-temporary-directory «.framework»s (and fulfill a successful compilation).

Well, to be more precise…

〜 Well, to be more precise, any scheme where the Carthage-focused target with build setting value for FRAMEWORK_SEARCH_PATHS specifically containing a subdirectory of Carthage/Build will have the at-the-end-of-FRAMEWORK_SEARCH_PATHS opportunity.

This behavior works for framework targets in most cases, since they link against but generally do not embed their framework dependencies, but requires changes if any part of a target’s build process requires the exact path of the framework bundle. If you (or developers consuming your framework) encounter build errors when using carthage build --use-xcframeworks, you have a few options:

Update your project to link and embed XCFrameworks from Carthage/Build, then read the extracted framework from CONFIGURATION_BUILD_DIR. You won’t rely on the above ‘at-the-end-of-FRAMEWORK_SEARCH_PATHS opportunity’ behavior, but ﹡you will break compatibility with users who aren’t using the --use-xcframeworks flag﹡, so consider other options, proceed with caution, and consider versioning this as a breaking change.

If Carthage fails while building a scheme that contains non-framework targets, break it up into multiple schemes, so that Carthage only builds the framework targets.

Modify your build phases to parse the FRAMEWORK_SEARCH_PATHS build setting and search each directory in order to find a Carthage framework, rather than hard-coding its path to a Carthage/Build/<platform> directory.

If you’re struggling to figure out how Carthage focuses on a target…

〜 If you’re struggling to figure out how Carthage focuses on a target within a Xcode project/workspace within a repo and subsequently widens out to choose a scheme based on that, head to https://github.com/Carthage/Carthage/issues/new and attach the label «focused-target» or just mention «focused-target» in the issue’s body text; please make the body text detailed, and priority will be given to issues regarding open source repositories.

Acknowledgements

Thanks @olejnjak, @philipphofmann, and @daisuke-t-jp for their work on documenting the xcconfig workaround. More broadly, we appreciate the community of users who communicated about the problem, came up with a temporary workaround, and were patient while we architected a fix.

Thanks @tmspzz, @gjeck, @nighthawk, @chrisballinger, @renep, and @elliottwilliams for their work reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(4.80 MB)
0.36.1(Jan 14, 2021)
:information_source: This is a maintenance release to support integrating frameworks on Xcode 12.3 and above.

:information_source: This release does not include forthcoming support for building XCFrameworks. Expect XCFrameworks in the next release, 0.37.0.

Fixed

carthage build disables a validation added in Xcode 12.3 which prevents some Carthage-built frameworks from being embedded (https://github.com/Carthage/Carthage/pull/3095).

Xcode 12.3 warns when a target embeds framework with slices labeled for multiple platforms (even when the slices are all housed under different architectures); except, some slight sets of platform pairs are permitted. Typically, Carthage's multi-arch frameworks are stripped at build time using carthage copy-frameworks, but they may be copied whole in test targets and other rare circumstances.

When warnings-as-errors is enabled, this validation warning may fail the build. Carthage disables it internally by setting VALIDATE_WORKSPACE=NO.

If you see an error like Building for iOS Simulator, but the linked and embedded framework 'REDACTED.framework' was built for iOS + iOS Simulator, set VALIDATE_WORKSPACE=NO in your project's build settings.

Fixed carthage creating too many tempoary directories during copy-frameworks phase (Carthage/Carthage#3066). Thanks @tmspzz

Thanks @olejnjak, @philipphofmann for improving the documentation since the last release.

Note

Xcode (at the era of 12.3) does very little when Validate Workspace is enabled. If truly encompassing this facet is important to you…
…try copying a Carthage Checkouts/Build directory to another location, editing Xcode projects to remove any targets that (aside from through `carthage copy-frameworks`) embed Carthage-built things, and copy the xcodebuild invocation from a run of `carthage … --verbose` and modify-it, removing VALIDATE_WORKSPACE=NO.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(4.75 MB)
0.36.0(Sep 18, 2020)
⚠️ This version doesn't fix the issue with Xcode 12. See https://github.com/Carthage/Carthage/issues/3019 ⚠️

Fixed

Prevent cross device issues in copy-frameworks (#3047). Thanks @rudedogdhc!

Thank you to @nixnoughtnothing for improvements to the code base! Thank you to @tmspzz for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(1.72 MB)
0.35.1(Sep 16, 2020)
⚠️ This version doesn't fix the issue with Xcode 12. See https://github.com/Carthage/Carthage/issues/3019 ⚠️

Fixed

Fixed copying files across different volumes (#3025). Thanks @rudedogdhc!

Added

Sort frameworks so changes in .version files are easier to spot (#3015). Thanks @peteranny!

Support NO_PROXY or no_proxy environment variable (#2991). Thanks @okaverin!

Prevent re-downloading module stable binaries (#3040). Thanks @justAnotherDev!

Remove leftovers of failed archives unzips (#3035). Thanks @tattn!

Improved

Spelling mistakes in README (#3021). Thanks @thomasaw!

Reflect carthage build requirements in README (#3045). Thanks @chrstphrchvz!

Installing carthage outside of protected folders no longer requires sudo (#3024). Thanks @cfelder!

Remove invalid archs by intersecting VALID_ARCHS and ARCHS (#2987). Thanks @jerbob92!

Thank you to @jdhealy @tmspzz for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(1.72 MB)
0.35.0(Jun 18, 2020)
Carthage now elides a certain warning about Swift compiler versions upon truths from three sources:

Swift compiler version (as queried by local machine’s xcode-select and possible TOOLCHAINS environment variable) being greater than 5.1

that particular framework’s recorded Swift compiler being greater than 5.1

that particular framework matching (somewhat) a glob (working from framework-bundle-root–level) of Modules/*swiftmodule*/*.swiftinterface

note: only one directory matching Modules/*swiftmodule*/ will continue querying inside of it — with FileManager.default.contentsOfDirectory defining that

note: presence of particular architectures (armv7, i386, x86_64, etc.) are not taken into account

Note: As .swiftinterface files emission “currently [as of Swift 5.X] requires library evolution support” — take warning of the Swift Compiler Team’s message that “Library evolution trades off performance for flexibility” and comes with caveats. • :warning: Not every library vendor will desire to enable BUILD_LIBRARY_FOR_DISTRIBUTION in their project’s build settings, or even to field questions on bugs resulting from those adding that scope. Be kind to library vendors that might weigh their potential maintenance/ongoing-qa-debugging work differently then your BUILD_LIBRARY_FOR_DISTRIBUTION desires.

〜 Thanks @DavidBrunow for this feature!

Dynamic Intelligent Platform Parsing

Previously, Carthage would propagate errors upon reading non-compiled-in values from SUPPORTED_PLATFORMS or PLATFORM_NAME.

Carthage 0.35.0 supports SUPPORTED_PLATFORMS or PLATFORM_NAME dynamically with intelligent parsing from xcodebuild -showsdks -json.

Carthage’s --platform argument takes the same input of 2019-era SDKs — however, in alignment with the above: the default (a.k.a. “all”) parameter will allow dynamically-parsed SDKs to propagate.

carthage archive still uses the hardcoded four 2019-era SDKs.

The carthage cleanup command — existing on-master, but unshipped-in-tags — no longer makes sense (when set of SDKs are non-fixed across Xcode versions) and has been removed.

Dynamic Platform Parsing can occur from xcodebuild -showsdks -json with fallbacks to BuildSetting extraction from a Xcode-bundled xcodeproj, and beyond that falling back to hardcoded 2019-era values.

⤵️ Note: the dynamic parsing will omit SDKs — such as DriverKit — where JSON-derived canonicalName and platform do not share a common prefix · DriverKit has an ouptut canonicalName similar to «driverkit.macosx19.0».

Other Breaking Changes

Track static frameworks in .version files. Thanks @elliottwilliams!

Old carthage versions will still behave erroneous — but not propagate errors — after parsing sets of newer .version files output for Swift static frameworks.

To guarantee output of newer .version files for affected Swift static frameworks, change Swift versions and rerun Carthage with the --cache-builds flag (even temporarily), or delete .framework bundles for affected Swift static ones and rerun Carthage with the --cache-builds flag.

For GitHub Release assets, expand permitted MIME types to include application/x-zip-compressed. Thanks @MatkovIvan!

Reject invalid binary archives containing the same framework multiple times. Thanks @tmspzz!

For binary-spec-ed dependencies and GitHub Release downloads, copy dSYMs if any architecture matches current binary — also affects CarthageKit consumers. Thanks @hlineholm!

Conflict less in concurrent strip-framework–dedicated Carthage process invocations via different underlying copying — rather than overwrite straight from process, now temp directory usage prevents conflicts on certain same-file/same-path writes. Thanks @kalkwarf!

Fallback to dSYM version parsing for more cases before invalidating cached builds. Thanks @kmcbride!

Add --use-netrc flag under which basic ~/.netrc files facilitate binary-specified framework download authentication. Thanks @mollyIV!

Stability

Fix various cases of «Segmentation Fault 11». Thanks @taisukeh!

Extend error messages when reading certain binaries. Thanks @hlineholm!

Security Enhancing Breaking Change

Prevent directory traversal through additional sanitization of git-specified repository URL components — specifically nul characters (\u{0000}) and periods (\u{0023}). Thanks @manicmaniac!

Replacement strings include repeated «Full Width Full Stops» (\u{FF0E}) and replacement ␀ (\u{2400}).

URL components not starting with periods (\u{0023}) will not see inserted «Full Width Full Stops» (\u{FF0E}).

Breaking — For Apps Importing Carthage Kit and XCDBLD

For Apps Importing Carthage Kit and XCDBLD

Removed: XCDBLD.Platform — replaced (not one-for-one) by struct SDK with new method SDK.platformSimulatorlessFromHeuristic.

Removed: XCDBLD’s enum-based SDK — replaced by struct SDK.

Removed: XCDBLD.SDK.platform and XCDBLD.SDK.allSDKs.

Changed: Hashing and equality for XCDBLD.SDK is case-insensitive.

Canonical casing for SDK names available through SDK.knownIn2019YearSDKs and SDK.setFromJSONShowSDKs.

Changed: Various type signature changes removing XCDBLD.Platform and incorporating XCDBLD.SDK.

Removed: SDK.from(string:) — replaced by SDK.init(name:simulatorHeuristic).

Passing an empty string as simulatorHeuristic is usually the foremost codepath.

SDK.init(rawValue:) is not intended for wide spread use · as it’s limited to only 2019-era hardcoded SDKs.

Removed: BuildSettings.buildSDKs: SignalProducer<SDK, CarthageError> — replaced with BuildSettings.buildSDKRawNames: Set<String>.

Made Public: Various VersionFile-related API. Thanks @acecilia!

Thanks to all Contributors

Thank you to @CosynPa, @sidepelican, @chuganzy, @sstadelman (#2781), @giginet (#2761), @ikesyo (#2886, #2785, #2784), @DavidBrunow (#2966, #2967), @mvalentiner, @gubikmic, @sticksen, @nteissler, @ismetanin, @brandonlee503, @yhkaplan, and @tmspzz for improvements to the codebase, tests, and documentation.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(4.73 MB)
0.34.0(Oct 21, 2019)
⚠️ Carthage source only builds on Xcode 10.0+, thus requiring macOS High Sierra 10.13.6. ⚠️

Additional workarounds to enable Xcode 11.0, 11.1, and 11.2 betas have been added; see below.

Fixed

ASCII alphabet for Semantic Version pre-release and build metadata components now includes uppercase and lowercase W, fixing an omission and completing the alphabet (#2805 #2806). Thanks @drakerr!

Workaround Swift 5.1 compiler crash bug to allow the compilation of Carthage itself on Xcode 11, Xcode 11.1, and Xcode 11.2 betas (#2859). Thanks @michaelmcguire!

Breaking — For Apps Importing Carthage Kit

Removed — as a library dependency — SwiftPM and llbuild and reinstated struct CarthageKit.SemanticVersion.

A bug in the-tool-SwiftPM's package resolution resulted in disregard for the (crucial) ‘resolved file’ when resolving branch-based dependencies.

Which would put us in the position of needing any commit of apple/swift-package-manager that didn’t specify its dependency on apple/swift-llbuild in the branch-based style.

Also criteria for the above, working Swift 4.2.X manifests and compilation and working Swift 5.X manifests and compilation.

No such commit of apple/swift-package-manager could be found.

In addition, some confusion around llbuild's sqlite3 linkage made criteria even more confusing.

Some initializers and methods on struct Carthage.SemanticVersion have differences from the previous incarnation found in v0.33.0.

Reinstate struct CarthageKit.SemanticVersion in all callsites in codebase and tests, removing SPMUtility.Version.

No longer necessary to import struct Foundation.URL with the removed import of SPMUtility.

Makefile removes complications which previously supported llbuild's sqlite3 linkage.

Working Swift 4.2.X compilation is necessary to support building for macOS High Sierra on Homebrew bottling infrastructure.

Important

Future updates will address Catalyst and building of XCFrameworks. Thank you for your patience.

Thank you to @jdhealy, @sstadelman, @tmspzz, @giginet, @olejnjak, and @ikesyo for improvements to the codebase and the infrastructure.

Thank you to @mdiep, @tmspzz, @giginet, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(4.68 MB)
0.33.0(Apr 3, 2019)
⚠️ Carthage source only builds on Xcode 10.0+, thus requiring macOS High Sierra. ⚠️

In particular, carthage compiles under Swift 4.2 and 5.0 with Xcode 10.1 and 10.2.

Fixed

In cases where device and simulator destined builds are merged into a single bundle, also merge -Swift.h header files from each with active inclusion of target conditionals (#2723, #2748). Thanks @DavidBrunow, @VictorNouvellet, and @buranmert!

Currently limited to a single pair of -Swift.h-suffixed files. Should be sufficient for the vast majority of frameworks.

Under --cache-builds mode —

Support headerless Swift-containing frameworks via dSYM parsing (#2622). Thanks @blender!

When run with --no-skip-current, produce .version files for those additional frameworks (#2636). Thanks @blender!

In support of community tooling, embed partial toolchain information (often swiftlang and clang versions) in .version files for Swift-containing frameworks. Expect these .version files to contain different output between Carthage v0.33.0 and previous Carthage versions (#2585, #2707). Thanks @giginet and @kenji21!

Notable

For file system objects at some level of Carthage/Checkouts/DependencyX, delete with FileManager.removeItem(at:) if using --use-submodules and something exists there that’s not a directory housing a .git subdirectory. This matches Carthage’s existing deletion behavior of checkouts without --use-submodules. Use caution. (#2654).

In Cartfiles, specifications with github at the beginning of the line now error when followed by non-http-or-https-schemed URLs (often ssh:// or git:// schemed). We long-standing queried these with web requests, so now errors output earlier in the process with more helpful messaging (#2379). Thanks @ikesyo!

Static frameworks under --cache-builds mode highly likely to proceed errantly cache-valid ≈ late caught bug —

Will be correctly cache-invalid upon a version-specification change (including changing the specified SHA); also, upon a toolchain change for a Swift-containing static framework (including after a different xcode-select).

The first run of a never-modified-by-Carthage-v0.33.0 .version file for a Swift-containing static framework under Carthage v0.33.0 will also cache-invalidate it.

carthage build <framework> without --cache-builds will always attempt rebuilding it and it's dependencies.

Note for Apps Importing CarthageKit.framework

Carthage (the CLI executable) is now built exclusively with SwiftPM. In effect, the Cartfile supporting CarthageKit.framework has been removed. Consuming CarthageKit is now done through SwiftPM and CarthageKit is now a static library.

On environment variable GIT_SSH_COMMAND

An SSH prompt (invisble to a carthage user) could stop progression when encountering a host not yet public-key-fingerprint verified by the user. Carthage now outputs proper messaging at that point, at the expense of GIT_SSH_COMMAND no longer being honored (#2734). Thanks @jlawton!

Improved

Report read errors from files pointed to by SCRIPT_INPUT_FILE_LIST_ variables (#2668). Thanks @ferranpujolcamins!

More efficient, less errant querying of git’s representation of file system objects via ls-tree (#2617). Thanks @CosynPa!

More efficient git submodule sync over multiple dependencies (#2643). Thanks @mdiep!

Thank you to @FranklinYu, @DivineDominion, @musbaalbaki, and @salbertson for improvements to the documentation.

Thank you to @mxcl, @giginet, @olejnjak, and @ikesyo for improvements to the codebase and the infrastructure.

Thank you to @blender, @mdiep, @giginet, @DavidBrunow, @VictorNouvellet, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(7.08 MB)
0.32.0(Feb 1, 2019)
Fixed

More resiliency towards xcrun simctl list devices --json outputting com.apple.CoreSimulator.SimRuntime in keys whose values are available simulator devices (#2693, #2696). Thanks @kmcbride and @DavidBrunow!

Thank you to @giginet, @taher-mosbah, @ikesyo, and @blender for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.17 MB)
CarthageKit.framework.zip(8.03 MB)
0.31.2(Oct 30, 2018)
:warning: Carthage will only consider targets that support the archive action. (#2507 & #2515) :warning: :warning: Carthage does not support Xcode 6 anymore. (#2561) :warning: :warning: Carthage source only builds on Xcode 9.4+, thus requiring macOS High Sierra. :warning:

Fixed

More resiliency towards xcrun simctl list devices --json outputting isAvailable as String, isAvailable as Bool, or availability as String depending upon whether Xcode 10B61 has been installed, or an Xcode 10.1 beta has been installed (#2630). Thanks @ olejnjak!

Thank you to @artemnovichkov for improvements to the documentation.

Thank you to @ikesyo and @giginet for improvements to the codebase and the infrastructure.

Thank you to @blender, @mdiep, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.17 MB)
CarthageKit.framework.zip(8.02 MB)
0.31.1(Oct 9, 2018)
:warning: Carthage will only consider targets that support the archive action. (#2507 & #2515) :warning: :warning: Carthage does not support Xcode 6 anymore. (#2561) :warning: :warning: Carthage source only builds on Xcode 9.4+, thus requiring macOS High Sierra. :warning:

Fixed

Resiliency towards xcrun simctl list devices --json outputting availability or isAvailable depending upon whether an Xcode 10.1 beta has been installed (#2606). Thanks @giginet!

Added

Add support for *.xcfilelist file in carthage copy-frameworks (#2591). Thanks @kishikawakatsumi!

Thank you to @ikesyo and @giginet for improvements to the codebase and the infrastructure.

Thank you to @blender, @mdiep, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.17 MB)
CarthageKit.framework.zip(8.02 MB)
0.31.0(Sep 24, 2018)
:warning: Carthage will only consider targets that support archive action .(#2507 & #2515 ) :warning: :warning: Carthage does not support Xcode 6 anymore (#2561) :warning: :warning: Carthage source only builds on Xcode 9.4, thus requiring macOS High Sierra :warning:

Fixed

Ignore targets that don't support archive (#2507). Thanks @chuganzy !

Watch OS targets won't build in Xcode 10 (#2561). Thanks @giginet !

Fix SemVer parsing with too many dots (#2518). Thanks @marcoconti83 !

Fix timeout in carthage version check (#2546). Thanks @Sebastian-Hojas !

Added

Symlink the Build folder for binary downloads (#2551). Thanks @jasonboyle !

Implement carthage validate to validate the correctness of the Cartfile.resolved (#2523). Thanks @jasonboyle !

Add support for .xz archives (#2548). Thanks @carolanitz !

Improved

Improve handling of binaries with no Info.plist (#2542). Thanks @ikesyo !

Thank you to @3lvis (#2524), @brentleyjones (#2537), @sgl0v (#2556), @martnst (#2563) for improvements to the documentation!

Thank you to @ikesyo (#2520, #2522, #2535, #2527, #2538, #2574, #2571) for improvements to the code base! Thank you to @ikesyo @jdhealy (#2510) for improving the infrastructure!

Thank you to @mdiep @jdhealy @ikesyo @blender for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(7.80 MB)
CarthageKit.framework.zip(7.67 MB)
0.30.1(Jul 2, 2018)
:warning: This release improves support for Semantic Versions. You might experience changes to dependency resolution when running update. See (#2412) :warning:

Fixed

Use correct URL format when using Proxies (#2428). Thanks @blender !

Filter out improper directories passing as frameworks (#2436). Thanks @blender !

Fix symlinks on APFS volumes (#2445). Thanks @cmittendorf !

Consider XCODE_PRODUCT_BUILD_VERSION alongside EXPANDED_CODE_SIGN_IDENTITY to address Xcode 10’s empty build setting behavior (#2476). Thanks @jdhealy !

Make use of --new-resolver flag in bootstrap command (#2486). Thanks @blender !

Added

Support for building static frameworks (#2415, #1935). Thanks @Aranoledur @ikesyo !

Improved

Semantic Version Support Enhancements (#2412 , #1553). Thanks @marcoconti83 !

Add --archive option to build command (#2438). Thanks @sunshinejr !

Generate a version file for projects with no shared schemes (#2450). Thanks @jasonboyle !

Relative Path Support In Cartfile.resolved (#2383). Thanks @dmiluski !

Allow Github releases archieves with application/octect-stream MIME type (#2448). Thanks @bwhiteley !

Truncate log file before writing new one (#2474). Thanks @ChristopherRogers !

Allow binary dependencies with no Info.plist (#2502). Thanks @blender !

Thank you to @blender ( #2386, #2399, #2447), @TwiterZX (#2396), @valeriyvan ( #2385), @DanTheColoradan (#2426), @walshie4 (#2463), @dimazen (#2471), @isaac-weisberg (#2499) for improvements to the documentation!

Thank you to @ikesyo (#2413) for improving the infrastructure!

Thank you to @ikesyo ( #2431, #2434, #2435), @ChristopherRogers (#2475) for improvements to the code base!

Thank you to @mdiep @jdhealy @ikesyo @blender @kballard @artemnovichkov for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.32 MB)
CarthageKit.framework.zip(8.15 MB)
0.30.0(Jul 2, 2018)

⚠️

This release contains a potential security concern. Do not download
Source code(tar.gz)
Source code(zip)
0.29.0(Mar 19, 2018)
:warning: This release raises the deployment target to macOS 10.11 El Capitan :warning:

Fixed

Fix dSYM generation (#2334). Thanks @abrindam!

Fix update X's dependencies when running carthage update X (#2321). Thanks @jwutke!

Fix segmentation fault when bootstrapping (#2376). Thanks @vytis!

Fix a bug involving carthage outdated fail (#2328). Thanks @chuganzy!

Fix a bug involving tvOS binary releases (#2346). Thanks @blender!

Added

Optionally strip debug symbols in carthage copy-frameworks (#2361). Thanks @abrindam!

Support relative file path for binary dependencies (#2360). Thanks @dmiluski!

Don't create Carthage/Build symlink if project doesn't use Carthage (#2368). Thanks @mdiep!

Add support for proxied environments (#2371). Thanks @jakeadams!

Improved

Limit Parallelism in scheme discovery (#2343). Thanks @flovilmart!

Speed up scheme discovery (#2344) (#2372). Thanks @flovilmart!

Move binary download to build process (#2342). Thanks @chuganzy!

:warning: Users should add --no-use-binaries to carthage build executions where necessary.

Thank you to @yoching for improvements to the code base! Thank you to @mdiep @jdhealy @ikesyo @blender @47014106 @tbrannam @awgeorge @hyperspacemark for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.30 MB)
CarthageKit.framework.zip(8.14 MB)
0.28.0(Jan 29, 2018)
Fixed

Use of Swift toolchains that report a prerelease version (#2282). Thanks @tonyarnold!

Added

Support for downloading static binaries with binary dependencies (#2235). Thanks @blender!

Improved

outdated now lists all dependencies, even those that will not be updated because of the specified version in the Cartfile (#2254). Thanks @iv-mexx!

ouddated now includes color output (#2257). Thanks @iv-mexx!

Thank you to @ikesyo and @chuganzy for improvements to the codebase! Thank you to @mdiep, @NachoSoto, and @jdhealy for reviewing PRs!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.29 MB)
CarthageKit.framework.zip(8.12 MB)
0.27.0(Dec 8, 2017)
Fixed

Incorrectly named .xcarchive folders are no longer created (#2239). Thanks @kishikawakatsumi!

Some git errors will now be fully printed (#2252). Thanks @iv-mexx!

Added

A new resolver algorithm is available with the --new-resolver flag for carthage update (#2122). Thanks @BobElDevil!

Building Carthage (the tool itself) now uses Xcode's new build system (#2269). Thanks @ikesyo!

Changed

Potentially alleviate situations where (despite prior versions of Carthage upgrading) a downgrade or lack of upgrade occurs for dependencies (and/or subdependencies of those) specified by branch or no given version requirement (#2260).

⚠️ Relative paths for local repositories (git './…' … or git '../…' …) will have a reversion in behavior. See workaround and re-opened issue here.

Thank you to @ikesyo, @zhongwuzw, @BobElDevil and @dtweston for improvements to the codebase! Thanks to @mdiep, @ikesyo, @NachoSoto and @jdhealy for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(8.28 MB)
CarthageKit.framework.zip(8.11 MB)
0.26.2(Oct 14, 2017)
Fixed

CocoaPods-generated projects support when running archive action (#2213). Thanks @ikesyo!

Thanks to @mdiep for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(7.99 MB)
CarthageKit.framework.zip(7.83 MB)
0.26.1(Oct 13, 2017)
Fixed

Building frameworks whose SKIP_INSTALL build setting is set to NO (#2210). Thanks @ikesyo!

Added

--xcode-warnings option to the outdated command to output Xcode-compatible warnings (#2209). Thanks @dtweston!

Thanks to @mdiep for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(7.99 MB)
CarthageKit.framework.zip(7.83 MB)
0.26.0(Oct 11, 2017)
Carthage now requires Swift 4.0 / Xcode 9.

Fixed

jsonDecodingError is incorrectly reported when downloading binaries (#2182). Thanks @ikesyo!

Improved

Use archive action when building device SDKs to disable LLVM Instrumentation (#2158). Thanks @ikesyo!

Thank you to @kas-kad for improvements to documentation. Thank you to @ikesyo and @mdiep for improvements to the codebase! Thanks to @BobElDevil, @ikesyo, @jdhealy, @mdiep and @NachoSoto for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(7.99 MB)
CarthageKit.framework.zip(7.83 MB)
0.25.0(Sep 4, 2017)
Fixed

Carthage now builds with Xcode 9.

Homebrew installations will no longer mistakenly use previously installed versions of CarthageKit.framework (#2059). Thanks @ikesyo!

Fetching of local repositories with relative paths (#2125). Thanks @ikesyo!

Added

Support for .bz2 archives (#2092). Thanks @lswith!

Support for .tgz archives (#2109). Thanks @ikesyo!

Support for file:/// URLs with binary dependencies (#2140, #2142). Thanks @ikesyo, @phimage!

Improved

Carthage’s derived data folder is now split by Xcode version (#2102). Thanks @ikesyo!

The Swift version string used to compare versions now includes the major version of the compiler (#2052). Thanks @ikesyo!

Carthage’s Makefile is now more robust (#2054, #2098, #2108). Thanks @waffleboot, @zhongwuzw, @jdhealy!

Thank you to @ikesyo and @jdhealy for improvements to the codebase! Thanks to @mdiep, @BobElDevil, @jdhealy, @andersio, @norio-nomura, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.46 MB)
CarthageKit.framework.zip(6.27 MB)
0.24.0(Jul 10, 2017)
Carthage now requires Swift 3.1.

Fixed

Worked around copy bug on APFS volumes (#2032). Thanks @BobElDevil!

Improper cache invalidation with Xcode 9 (#1984). Thanks @BobElDevil!

Trashing of folders in Carthage/Checkouts/ (#2027). Thanks @BobElDevil!

Building for multiple SDKs with the new Xcode build system (#2053). Thanks @BobElDevil!

Broken --log-path option (#1958). Thanks @michaelmcguire!

Potential hang when unzipping invalid archives (#1997). Thanks @ikesyo!

Improved

GitHub dependencies will be the same when specified with git (#1995). Thanks @blender!

Building will now use checked out Cartfiles instead of getting them from Git (#2041). Thanks @BobElDevil!

Thank you to @ikesyo and @Dschee for improvements to the codebase! :tada: Thank you to @ikesyo, @mdiep, @jdhealy, and @BobElDevil for reviewing pull requests. :sparkles:
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.37 MB)
CarthageKit.framework.zip(6.18 MB)
0.23.0(May 19, 2017)
Improved

carthage checkout now checks out dependencies concurrently for a nice speedup (#1910). Thanks @erichoracek!

The notification that there’s a new Carthage version available is now printed to stderr instead of stdout (#1918). Thanks @BobElDevil!

Carthage can now handle frameworks that have no debug symbols (#1932). Thanks @erichoracek!

Thank you to @ikesyo, @mdiep, and @erichoracek for improvements to the codebase! Thank you to @mdiep, @ikesyo, @jdhealy, and @BobElDevil for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.34 MB)
CarthageKit.framework.zip(6.15 MB)
0.22.0(Apr 28, 2017)
Fixed

Error when a file is passed multiple times to copy-frameworks (#1902). Thanks @erichoracek!

Improper cache invalidation when using --toolchain (#1906). Thanks @klundberg!

Thank you to @ikesyo for improvements to the codebase. Thank you to @mdiep for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.36 MB)
CarthageKit.framework.zip(6.17 MB)
0.21.0(Apr 25, 2017)
Fixed

Improper cache invalidation for nested dependencies (#1831). Thanks @BobElDevil!

Improper cache invalidation for prebuilt binaries (#1850). Thanks @erichoracek!

Crash from Swift 3.1 compiler issue (#1866). Thanks @jdhealy!

Crash from unwrapping of URLs from git (#1806). Thanks @jdhealy!

Optional description in error output (#1884). Thanks @Nirma!

Added

Support for custom log paths (#1863). Thanks @aaroncrespo!

Improved

copy-frameworks now copies frameworks concurrently (#1841). Thanks @erichoracek!

--cache-builds now uses the Swift version of the framework instead of the Xcode version (#1896). Thanks @erichoracek!

Thank you to @ikesyo, @mdiep, @scottrhoyt, and @erichoracek for improvements to the codebase! Thank you to @mdiep for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.36 MB)
CarthageKit.framework.zip(6.17 MB)
0.20.1(Mar 11, 2017)
Fixed

Error when running checkout due to a preexisting symlink (#1805). Thanks @jdhealy!

Error when a project has no shared schemes for a given platform (#1827). Thanks @mdiep!

Carthage will no longer report draft Carthage releases when checking for a new Carthage release (#1795). Thanks @ikesyo!

Improved

--use-cache will now use SHA-256 for hashing (#1811). Thanks @ffittschen!

Thank you to @scottrhoyt for improvements to documentation. Thank you to @ikesyo and @BobElDevil for improvements to the code base. Thank you to @mdiep, @ikesyo, and @jdhealy for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.40 MB)
CarthageKit.framework.zip(6.19 MB)
0.20.0(Feb 27, 2017)
Added

--cache-builds flag (off by default for now) to cache builds locally (#1489). Thanks @baek-jinoo, @jasonboyle, and @BobElDevil!

Support for .tar.gz binary archives (#1786). Thanks @dcaunt!

Improved

Pre-built Swift binaries will only be used if they were built with the same version of the Swift compiler (#1755). Thanks @scottrhoyt!

Carthage projects will be built with individual, per-version DerivedData directories (#1419). Thanks @ikesyo!

The .pkg installer will no longer let you install to volumes without macOS (#1772). Thanks @dcaunt!

Submodules checked out with Carthage will get symlinks for their dependencies (#1715). Thanks @jdhealy!

Fixed

The PackageInfo for the .pkg install will have the correct version (#1773). Thanks @mdiep!

Thank you to @johnmckerrell, @dcaunt, @louisdh, and @scottrhoyt for improvements to documentation. Thank you to @ikesyo for improvements to the codebase. Thank you to @mdiep and @NachoSoto for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.37 MB)
CarthageKit.framework.zip(6.17 MB)
0.19.1(Feb 15, 2017)
Fixes

Failure to print xcodebuild output to the log file (#1761). Thanks @BobElDevil!

Printing of the URL to open a new issue on a project (#1764). Thanks @dcaunt!

Thanks to @mdiep for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.30 MB)
CarthageKit.framework.zip(6.10 MB)
0.19.0(Feb 14, 2017)
Added

Support for binary-only frameworks (#1760). Thanks @michaelmcguire!

Carthage now builds with Swift 3 (#1736 and many others). Thanks @ikesyo!

Check to see if a new version of Carthage has been released (#1533). Thanks @rodchile!

Improved

Longer Xcode timeout for slow machines (#1532). Thanks @yas375!

When checkout fails, the underlying Git error will be printed (#1519). Thanks @NachoSoto!

Cartfile.resolved is now sorted alphabetically to reduce conflicts (#1681). Thanks @mdiep!

Xcode warnings/errors are no longer passed through to Carthage stdout. This has been a source of confusion for many users. (#1718) Thanks @mdiep!

Fixed

Building projects that aren’t configured for the clean action (#1572). Thanks @zachwaugh!

Binary downloads are disabled if --toolchain option is given (#1585). Thanks @ikesyo!

Thank you to @Nirma, @ikesyo, and @mdiep for improvements to the code base. Thank you to @mdiep and @ikesyo for reviewing pull requests.
Source code(tar.gz)
Source code(zip)
Carthage.pkg(6.30 MB)
CarthageKit.framework.zip(6.10 MB)
0.18.1(Oct 6, 2016)
Fixed

Redundant builds when building a scheme that contains multiple targets (#1512). Thanks @mdiep!

Errors when using GitHub Enterprise repos with a Carthage built with Swift 2.3 (#1505). Thanks @ikesyo!

Updated shell completion for recent changes (#1474). Thanks @nafu!

Improved

Consistent usage of ' in terminal output for consistent rendering (#1472, #1476). Thanks @nafu!

The help message for --platform now suggests macOS instead of Mac (#1499). Thanks @giginet!

Thank you to @mdiep, @NachoSoto, and @ikesyo for reviewing pull requests!
Source code(tar.gz)
Source code(zip)
Carthage.pkg(3.74 MB)
CarthageKit.framework.zip(3.51 MB)

A simple, decentralized dependency manager for Cocoa

Related tags

Overview

Carthage

Quick Start

Installing Carthage

Adding frameworks to an application

Getting started

Building platform-independent XCFrameworks (Xcode 12 and above)

Migrating a project from framework bundles to XCFrameworks

Building platform-specific framework bundles (default for Xcode 11 and below)

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

Carthage 0.30.0 or higher

Carthage 0.29.0 or lower

Declare your compatibility

Known issues

DWARFs symbol problem

CarthageKit

Differences between Carthage and CocoaPods

License

Comments

Summary of changes

Goal

scheme

Use the Cartfile.ignore right now via Carthage-Pro

Where to go from here

The story:

Proposed solutions

Abandon Carthage:

CocoaPods

Work around it in Carthage

Releases(0.38.0)

0.38.0(May 7, 2021)

How to distribute XCFrameworks while retaining backwards compatibility

Create separate .framework.zip and .xcframework.zip archives

GitHub release assets: Upload both archives to the release

Binary only frameworks: Specify both archives in the binary spec URL using an alt= parameter.

Prefer building with module stability

0.37.0(Feb 1, 2021)

0.36.1(Jan 14, 2021)

0.36.0(Sep 18, 2020)

⚠️ This version doesn't fix the issue with Xcode 12. See https://github.com/Carthage/Carthage/issues/3019 ⚠️

0.35.1(Sep 16, 2020)

⚠️ This version doesn't fix the issue with Xcode 12. See https://github.com/Carthage/Carthage/issues/3019 ⚠️

0.35.0(Jun 18, 2020)

0.34.0(Oct 21, 2019)

0.33.0(Apr 3, 2019)

0.32.0(Feb 1, 2019)

0.31.2(Oct 30, 2018)

0.31.1(Oct 9, 2018)

0.31.0(Sep 24, 2018)

0.30.1(Jul 2, 2018)

0.30.0(Jul 2, 2018)

⚠️

0.29.0(Mar 19, 2018)

0.28.0(Jan 29, 2018)

0.27.0(Dec 8, 2017)

0.26.2(Oct 14, 2017)

0.26.1(Oct 13, 2017)

0.26.0(Oct 11, 2017)

`scheme`

Abandon `Carthage`:

`CocoaPods`

Work around it in `Carthage`

Create separate `.framework.zip` and `.xcframework.zip` archives

Binary only frameworks: Specify both archives in the binary spec URL using an `alt=` parameter.