Carthage Deployment and Usage Guide

Prerequisites

macOS - Carthage is designed for macOS and requires Xcode for building frameworks
Xcode - Required for building frameworks (version 10.0 or later for development)
Swift - Required for building and running Carthage (version 4.2 or later)
Git - Required for dependency management (version 2.3.0 or later)
Package Manager - Choose one:
- Homebrew (recommended)
- MacPorts
- Manual installation from source

Installation

Using Homebrew (Recommended)

brew update
brew install carthage

Using MacPorts

sudo port selfupdate
sudo port install carthage

Using Installer

Download the latest Carthage.pkg from GitHub releases
Run the installer and follow on-screen instructions
If installing via CLI, run: sudo chown -R $(whoami) /usr/local first

From Source

# Clone the repository
git clone https://github.com/Carthage/Carthage.git

# Build and install
cd Carthage
make install

Configuration

Carthage requires minimal configuration:

Cartfile - Create in your project directory to list dependencies:
```
github "Alamofire/Alamofire" ~> 5.5
```
Environment Variables - Carthage uses these internally:
- GIT_TERMINAL_PROMPT=0 - Prevents credential prompts
- GIT_SSH_COMMAND="ssh -oBatchMode=yes" - Prevents SSH prompts
Git Configuration - Carthage requires Git 2.3.0 or later:
```
git --version
```

Build & Run

Adding Frameworks to an Application

Create Cartfile - List dependencies in your project directory:
```
github "Alamofire/Alamofire" ~> 5.5
```
Update Dependencies - Fetch and build dependencies:
```
carthage update --use-xcframeworks
```
Add to Xcode Project - Drag built .xcframework bundles from Carthage/Build into:
- General settings tab
- Frameworks, Libraries, and Embedded Content section
Set Embed Settings:
- For applications: Select "Embed & Sign"
- For frameworks: Select "Do Not Embed"

Building Platform-Specific Framework Bundles (Default for Xcode 11 and below)

For iOS, tvOS, or watchOS:

carthage update

For macOS:

carthage update --platform macos

Running a Project

Build Dependencies:
```
carthage build --platform iOS
```
Run Tests:
```
carthage test
```

Deployment

Carthage is a development tool, not a server application. Deployment involves:

CI/CD Integration - Add Carthage to your build pipeline:
- GitHub Actions: Use carthage command in your workflow
- Travis CI: Add Carthage to your .travis.yml
- Bitrise: Use Carthage step in your workflow
Pre-built Frameworks - Upload pre-built frameworks to GitHub releases:
```
carthage build --no-skip-current --archive
```
Framework Distribution - For framework authors:
- Tag stable releases
- Archive prebuilt frameworks into zip files
- Upload to GitHub releases

Troubleshooting

Common Issues and Solutions

Git Version Requirements

Issue: Carthage requires Git 2.3.0 or later Solution:

git --version
# If version is too old, update Git
brew install git

DWARF Symbol Problem

Issue: Symbol problems when building frameworks Solution: Ensure proper Xcode scheme configuration and shared schemes

Build Failures

Issue: Dependencies fail to build Solutions:

Check if dependencies have shared Xcode schemes
Verify platform compatibility
Try carthage update --no-use-binaries

Cache Issues

Issue: Outdated builds causing problems Solution:

# Clear Carthage cache
rm -rf Carthage
rm -rf ~/Library/Caches/org.carthage.CarthageKit

Permission Issues

Issue: Permission denied when installing Solution:

sudo chown -R $(whoami) /usr/local

Nested Dependencies

Issue: Dependencies of dependencies not resolving Solution: Use --use-xcframeworks flag or check dependency compatibility

Debug Mode

Enable verbose logging for troubleshooting:

carthage update --verbose

Environment Reset

Clear all Carthage state:

carthage cache clean
rm -rf Carthage

Framework Compatibility

Check framework compatibility with your project:

carthage outdated

Swift Binary Framework Download Compatibility

Ensure Swift toolchain versions match between Carthage and your project.

How to Deploy & Use Carthage/Carthage