Swiftpack.co - Package - Carthage/Carthage

Carthage GitHub license GitHub release Reviewed by Hound

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

  1. Get Carthage by running brew install carthage or choose another installation method

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

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

    github "Alamofire/Alamofire" ~> 4.7.2
    
  4. Run carthage update

  5. A Cartfile.resolved file and a Carthage directory will appear in the same directory where your .xcodeproj or .xcworkspace is

  6. Drag the built .framework binaries from Carthage/Build/<platform> into your application’s Xcode project.

  7. If you are using Carthage for an application, follow the remaining steps, otherwise stop here.

  8. On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

    /usr/local/bin/carthage copy-frameworks
    
  • Add the paths to the frameworks you want to use under “Input Files". For example:

    $(SRCROOT)/Carthage/Build/iOS/Alamofire.framework
    
  • Add the paths to the copied frameworks to the “Output Files”. For example:

    $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Alamofire.framework
    

Another approach when having multiple dependencies is to use .xcfilelists. This is covered in If you're building for iOS, tvOS or watchOS

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 9.4 (Swift 4.1).

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

If you're building for macOS
  1. Create a Cartfile that lists the frameworks you’d like to use in your project.
  2. Run carthage update --platform macOS. This will fetch dependencies into a Carthage/Checkouts folder and build each one or download a pre-compiled framework.
  3. On your application targets’ General settings tab, in the Embedded Binaries section, drag and drop each framework you want to use from the Carthage/Build folder on disk.

Additionally, you'll need to copy debug symbols for debugging and crash reporting on OS X.

  1. On your application target’s Build Phases settings tab, click the + icon and choose New Copy Files Phase.
  2. Click the Destination drop-down menu and select Products Directory.
  3. For each framework you’re using, drag and drop its corresponding dSYM file.
If you're building for iOS, tvOS, or watchOS
  1. Create a Cartfile that lists the frameworks you’d like to use in your project.

  2. Run carthage update. This will fetch dependencies into a Carthage/Checkouts folder, then build each one or download a pre-compiled framework.

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

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

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

  8. Add the input.xcfilelist to the "Input File Lists" section of the Carthage run script phase

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

  1. On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:
/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

or

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 one zip file

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

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.

  1. Install travis CLI with gem install travis

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

  3. Create .travis.yml file at the root of your repository based on that template. 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
    
  4. 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

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

Carthage compatible

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

Github

link
Stars: 13828

Releases

0.35.0 - Carrageenan Cabaletta - 2020-06-18 21:25:40

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

Stability

Security Enhancing Breaking Change

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.

0.34.0 - Barometric Ballasting - 2019-10-21 17:43:58

⚠️ 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!

0.33.0 - Astrometric Associations - 2019-04-03 20:47:18

⚠️ 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!

0.32.0 - Weightless Warpspeed - 2019-02-01 05:25:34

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!

0.31.2 - Vocal Vortex - 2018-10-30 22:30:54

: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!

0.31.1 - Ubiquitous Upbeat - 2018-10-09 23:51:22

: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!

0.31.0 - Tough Tempo - 2018-09-24 22:58:38

: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!

0.30.1 - Static Staccato - 2018-07-02 13:30:08

: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!

0.30.0 - Static Staccato - 2018-07-02 11:03:54

⚠️

This release contains a potential security concern. Do not download

0.29.0 - Great Groove - 2018-03-19 19:55:44

: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!

0.28.0 - 2018-01-29 13:58:08

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!

0.27.0 - 2017-12-08 18:16:35

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

Thank you to @ikesyo, @zhongwuzw, @BobElDevil and @dtweston for improvements to the codebase! Thanks to @mdiep, @ikesyo, @NachoSoto and @jdhealy for reviewing pull requests!

0.26.2 - 2017-10-14 02:02:46

Fixed

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

Thanks to @mdiep for reviewing pull requests!

0.26.1 - 2017-10-13 04:56:24

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!

0.26 - 2017-10-11 00:12:35

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!

0.25: Quarterly Quandary - 2017-09-04 18:21:34

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!

0.24: Build Potion #9 - 2017-07-10 12:29:57

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:

0.23: Statically Speaking - 2017-05-19 12:51:32

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!

0.22: Invalid Invalidation - 2017-04-28 13:05:31

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.

0.21: Caches & Crashes - 2017-04-25 13:19:00

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.

0.20.1: Preexisting Conditional - 2017-03-11 18:38:47

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.

0.20: Unary, Binary, Ternary - 2017-02-27 13:25:21

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.

0.19.1: Wat Log - 2017-02-15 13:32:38

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.

0.19: Feels Dichotomy - 2017-02-14 21:40:10

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.

0.18.1: Redundant Redundancy - 2016-10-06 01:16:38

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!

0.18: Sierralization - 2016-09-11 01:49:57

Improved

  • Carthage itself now compiles with both Xcode 8 / Swift 2.3 and Xcode 7 / Swift 2.2 (#1395, #1397, #1398, #1404, #1410, #1442). Thanks @ikesyo!
  • Symlinks will now be created in Carthage/Checkouts/ for dependencies (#1421). Thanks @BobElDevil!
  • macOS is accepted as a value for --platform (#1390). Thanks @ikesyo!
  • appletvos and appletvsimulator are accepted as values for --platform (#1391). Thanks @ikesyo!
  • Output is now flushed at the end of each line (#1444). Thanks @slabko!

Fixed

  • xcodebuild hang when the target contains a core data model (#1447). Thanks @salling!
  • Redundant fetching of dependencies (#1429). Thanks @BobElDevil!
  • carthage archive incorrectly added absolute paths (#1386). Thanks @BernardGatt!
  • Crash when a repository wasn’t found (#1451). Thanks @mdiep!
  • PrivateHeaders weren’t stripped from copied frameworks (#1380). Thanks @erichoracek!
  • Issues working repositories that were in /tmp (#1459). Thanks @ikesyo!
  • Schemes weren’t escaped when invoking xcodebuild (#1389). Thanks @ikesyo!
  • Failure to get tags when the global Git config changed the output of git tag (#1463). Thanks @jalcine!

Thank you to @rondiamond and @evgeniyd for improvements to the documentation; to @ikesyo for improvements to the codebase; and to @mdiep and @NachoSoto for reviewing pull requests!

0.17.2: Zipper of Zippers - 2016-06-30 12:42:31

Improved

  • carthage copy-frameworks now strips headers from the framework (#1377). Thanks @ikesyo!

Fixed

  • carthage archive didn't respect --project-directory (#1373). Thanks @hamchapman!
  • carthage update would sometimes hang (#1376). Thanks @mdiep!

Thank you to @ikesyo and @mdiep for reviewing pull requests!

0.17.1: An Open Book - 2016-06-24 12:20:10

Fixed

  • Cartfile.private shouldn't be required (#1367, broken in 0.17). Thanks @mdiep!

Thanks to @ikesyo for reviewing the pull request!

0.17: Swift Marches On - 2016-06-22 12:51:51

Added

  • A --toolchain option to specify the Swift toolchain that should be used (#1303). Thanks @tkrajacic!

Improved

  • Frameworks will be built for the simulator only on platforms that require bitcode when bitcode is disabled (#1280). Thanks @phatblat!
  • Zsh will now autocomplete dependency names from the Cartfile.

Fixed

  • Carthage will error on carthage bootstrap <dependency> if dependency doesn’t exist in Cartfile.resolved (#1294). Thanks @mz2!
  • Carthage will error on carthage update <dependency> if dependency doesn’t exist in Cartfile (#1344). Thanks @ktakayama!
  • carthage archive no longer tries to copy XCTest files with test targets that have "Run" enabled in the build scheme (#1302). Thanks @BernardGatt!

Thank you to @ikesyo for improvements to the codebase! Thank you to @mdiep and @NachoSoto for reviewing pull requests!

0.16.2: A Side of Enterprise - 2016-04-13 12:37:14

Added

  • copy-frameworks will now ignore frameworks that don't have valid architectures (#1241). Thanks @coenert!

Fixed

  • GitHub Enterprise support (#1267). Thanks @mdiep!

Thank you to @ikesyo and @mdiep for reviewing pull requests!