Carthageとは：分散型依存関係マネージャー

Carthageとは？

Carthageは、2014年にSwiftコミュニティの開発者によって作成された分散型アーキテクチャの依存関係マネージャーです。Carthageは中央の仕様レジストリを使用しません — 各ライブラリはURLまたはGitHub名を介してGitリポジトリから直接接続されます。Carthageはソースコードをダウンロードし、バイナリフレームワーク（.xcframeworkまたは.framework）にビルドし、開発者にXcodeプロジェクトへの手動統合用の準備済みアーティファクトを提供します。

Carthageのアーキテクチャは3つのコンポーネントで構成されています：CLIツールcarthage、設定ファイルCartfile、ビルド済みフレームワークを含むCarthage/Build/ディレクトリ。CarthageとCocoaPodsの主な違いは、.xcodeprojの自動変更がないことです。Carthageは.xcworkspaceを作成せず、コンパイラフラグを設定せず、Pods.xcconfigを生成しません。開発者はXcodeを介してプロジェクトに手動でフレームワークを追加し、統合プロセスを完全に制御できます。

Carthageは並列依存関係ビルドを使用し、マルチコアプロセッサでの処理を大幅に高速化します。各依存関係は個別のターゲットとしてビルドされ、Carthageは推移的依存関係のグラフを自動的に解決し、正しい順序でビルドします。コミュニティのベンチマークによると、Carthageは最新のMacで平均30〜60秒で15〜20の依存関係をビルドし、多くのライブラリを含むプロジェクトではCocoaPodsよりも高速です。CarthageはすべてのAppleプラットフォーム（iOS、macOS、watchOS、tvOS）をサポートし、バージョン0.38+以降はシミュレータとApple Siliconデバイスをサポートするユニバーサル.xcframeworkをビルドします。

Carthageの仕組み

Carthageは各依存関係のGitリポジトリをクローンし、指定されたバージョン（タグ、コミット、ブランチ）に切り替えて、フレームワークをビルドするためにxcodebuildを実行します。CarthageはビルドスキームによってXcodeプロジェクトのタイプ（フレームワーク、動的フレームワーク、静的ライブラリ）を自動的に判別します。プロジェクトに複数のスキームがある場合、Carthageはデフォルトスキーム（アルファベット順で最初）を使用します。ビルド後、Carthageは完成したフレームワークをCarthage/Build/にコピーし、正確なバージョンを固定したCartfile.resolvedファイルを作成します。Carthageはビルド済みフレームワークのキャッシュをサポートしており — 依存関係に変更がない場合は再ビルドをスキップします。

Carthageの推移的依存関係はCartfile.resolvedを介して処理されます：Carthageは必要なすべての依存関係のグラフを構築し、正しい順序でビルドします。2つのライブラリが同じサードパーティライブラリに依存している場合、Carthageはそれを1回ビルドして両方に使用します。Carthageは特定のターゲットと原因を示すビルドエラーを報告するため、問題の診断が容易になります。

Cartfile：構造、構文、例

Cartfileは、Carthageプロジェクトの依存関係を定義するRubyライクな構文（Cartfile形式）の設定ファイルです。Cartfileはプロジェクトルートの.xcodeprojの隣に配置されます。Cartfileの各行は1つの依存関係（ソース（Git URL、GitHubリポジトリ）とバージョン）を記述します。構文はタグ、コミット、ブランチによるバージョン固定をサポートしています。

# 基本依存関係 Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

github "Owner/Repo"ディレクティブはGitHubリポジトリの省略形です。Carthageは自動的にURL https://github.com/Owner/Repo.gitを構築します。GitLab、Bitbucket、その他のGitホストの場合は完全なURLを使用します：git "https://gitlab.com/owner/repo.git"。バージョン演算子：~> 5.9（5.9から6.0までの任意のバージョン、6.0を除く）、== 8.0.0（正確なバージョン）、>= 1.0（最小バージョン）。特定のコミットはgithub "owner/repo" "abc1234"で固定できます。

完全なCartfileの例

Carthageは異なる設定用に複数のディレクトリをサポートしています：Cartfile（メイン）、Cartfile.private（公開されない内部依存関係用）、Cartfile.resolved（自動生成）。プライベート依存関係は、テストフレームワークなど開発ビルドでのみ使用されるライブラリに役立ちます。

# Cartfile — 主要な依存関係
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# 完全な URL 用の GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# 開発ブランチ
github "marmelroy/PhoneNumberKit" "development"

githubとgitはCartfileの2種類のソースです。前者はGitHub専用で、自動的にURLを生成します。後者は完全なURLを持つ任意の公開またはプライベートGitリポジトリ用です。バージョンはタグ（== 2.1.1）、セマンティックレンジ（~> 5.9）、ブランチ名（"development"）、コミットハッシュ（"a1b2c3d"）で指定できます。セマンティックレンジ（~>）はSemVerに従う依存関係に推奨され、更新時の破壊的変更から保護します。

Cartfile.resolvedはcarthage update後に自動生成されます。推移的依存関係を含むすべてのインストール済み依存関係の正確なバージョンを固定します。このファイルはGitで管理する必要があります — これがないと、別のマシンでcarthage bootstrapコマンドを実行した場合、同じルールでライブラリをビルドしますが、バージョンが異なる可能性があります。carthage outdatedは新しいバージョンが利用可能な古い依存関係のリストを表示します。

Carthageのインストールと設定

CarthageはHomebrew（macOSの標準パッケージマネージャー）を介してインストールされます。代替方法：GitHubからビルド済みの.pkgインストーラからのインストール、またはソースからのビルド。CarthageにはXcode with Command Line Tools（xcodebuildを含む）が必要で、Apple Silicon Macでは一部のレガシー依存関係にRosetta 2が必要です。

# インストール Carthage 経由 Homebrew
brew install carthage

# バージョンの確認
carthage version

# .pkgからのインストール (Homebrew が利用できない場合)
# ダウンロード Carthage.pkg を GitHub Releases から手動でインストール

Carthageをインストールした後、プロジェクトの初期化はプロジェクトルートにCartfileを作成することから始まります。Carthageにはinitコマンドはありません — ファイルはテキストエディタで手動で作成します。Cartfileに依存関係を記入した後、開発者はcarthage bootstrap（Cartfile.resolvedが既に存在する場合）またはcarthage update（初回インストールまたは更新）を実行します。Carthageはリポジトリをクローンし、フレームワークをビルドしてCarthage/Build/に配置します。

Carthageの更新はbrew upgrade carthageで行います。バージョンはcarthage versionで確認します。2025年中期時点の最新安定版は0.40で、デフォルトの.xcframeworkサポート、改善された並列ビルド、完全なSwift 6サポートを備えています。バージョン0.39以降、Carthageは互換性シムなしのレガシー.frameworkのビルドを停止しました — --use-xcframeworksを明示的に指定することを推奨します。

# アップデート Carthage 経由 Homebrew
brew upgrade carthage

# 特定のバージョンのインストール
brew install carthage@0.39

# 完全な再インストール
brew uninstall carthage && brew install carthage

注意：Carthageは.xcworkspaceを作成せず、.xcodeprojを変更しません。CocoaPodsとは異なり、CarthageはXcode設定の完全な制御を開発者に委ねます。つまり、依存関係をインストールした後、手動でフレームワークをXcodeに追加する必要があります（「XcodeへのCarthageフレームワークの統合」セクションを参照）。Carthageはまた、各依存関係にフレームワークターゲットを含むXcodeプロジェクトまたはワークスペースが必要です — そうでないとビルドは失敗します。

フレームワークのビルド：bootstrapとupdate

Carthageは依存関係を操作するための3つの主要コマンドを提供します：bootstrap、update、build。carthage bootstrapは既存のCartfile.resolvedから依存関係をビルドします — CI環境やプロジェクトに参加する開発者に推奨されます。carthage updateはCartfile.resolvedを最新バージョン（Cartfileの制約を尊重）に更新し、ビルドを実行します。carthage buildはバージョンを保存せずに指定されたすべての依存関係をビルドします。

# 初期インストール（バージョンを更新）
carthage update --use-xcframeworks --platform iOS

# 固定バージョンでの再ビルド
carthage bootstrap --use-xcframeworks --platform iOS

# 1つの依存関係のみをビルド
carthage build Alamofire --platform iOS

--use-xcframeworksフラグは、Carthageにレガシー.frameworkの代わりにユニバーサル.xcframeworkをビルドするよう指示します。これにより、シミュレータと実デバイスの両方、および追加スクリプトなしのApple Silicon Macをサポートします。--platform iOSフラグはビルドを単一のiOSプラットフォームに制限し、特にプロジェクトにクロスプラットフォームライブラリが含まれている場合にプロセスを大幅に高速化します。

Carthageは--cache-buildsフラグによる並列ビルドをサポートし、既にビルドされたフレームワークをキャッシュします。再ビルド時、CarthageはGitコミットハッシュをチェックし、コードに変更がなければコンパイルをスキップします。CIサーバーでは、Carthage/Build/ディレクトリと~/Library/Caches/carthage/をキャッシュすることを推奨します。Carthageは詳細なログ出力のための--verboseと、ソースからの強制ビルド（開発者がプリビルドバイナリを信頼しない場合）のための--no-use-binariesもサポートしています。

XcodeへのCarthageフレームワークの統合

統合 CarthageフレームワークのXcodeへの統合は、4つのステップで手動で行います。carthage updateまたはbootstrapを実行した後、ビルドされたすべてのフレームワークはCarthage/Build/iOS/（または対応するプラットフォーム）に配置されます。開発者はXcodeプロジェクトを開き、アプリのターゲットを選択し、General → Frameworks, Libraries, and Embedded Contentにフレームワークを追加します。ランタイムフレームワーク（動的ライブラリ）の場合は、「Embed & Sign」を選択する必要があります — そうしないと、アプリは起動時に「dyld: Library not loaded」エラーでクラッシュします。

Carthage静的ライブラリの場合はより簡単で — アプリの実行可能ファイルに直接リンクされるため、埋め込みフェーズは必要ありません。ただし、Carthageはデフォルトで動的フレームワークをビルドします（明示的に設定された静的ライブラリを除く）。アプリのサイズを最小化することが重要なプロジェクトでは、Xcode設定による静的リンクを推奨します。

追加のステップとして、Build Phase → Run Scriptに入力ファイルを追加します。Carthageは、ビルドされたフレームワークからシミュレータアーティファクトを削除するスクリプト（strip simulator architectures）を必要とします。このスクリプトはApp Storeビルドに必要です：

# Run Script 用の App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthageは.xcworkspaceの使用を必要としません — すべての依存関係は既にバイナリフレームワークにビルドされています。Carthageは、ワークスペースを作成するCocoaPodsとは異なり、.xcodeprojと直接動作します。これにより、Carthageの依存関係はXcodeプロジェクトの設定を変更しないため、バージョン管理とCI設定が簡素化されます。唯一の変更はターゲットへのフレームワークの追加であり、これは.pbxprojに記録されます。

Carthage vs CocoaPods vs Swift Package Manager

Carthage、CocoaPods、Swift Package Manager（SPM）は、iOS開発における3つの主要な依存関係マネージャーです。Carthageは分散型アプローチで際立ち、CocoaPodsは集中型レジストリを提供し、SPMはAppleの組み込みソリューションです。これらの選択は、プロジェクトの要件、チームの規模、必要な自動化のレベルによって異なります。

Carthageは、Xcode設定への最小限の介入と統合プロセスの完全な制御が必要なプロジェクトに選ばれます。Carthageは、作者がユーザーに依存関係を独立してビルドする自由を提供したいオープンソースライブラリやフレームワークに理想的です。CarthageはUNIX哲学（各ツールは1つのことをうまくやる）を重視する開発者の間でも人気があります。CocoaPodsは、自動化が重要な数十の依存関係を持つエンタープライズプロジェクトの標準であり続けています。SPMはXcodeに組み込まれ、Appleによって積極的に開発されているため、新しいプロジェクトの選択肢です。

移行 マネージャー間の移行には異なるアプローチが必要です。Carthage → SPM：Xcodeからフレームワークを削除し、Cartfileを削除し、File → Add Package DependenciesからPackage Dependenciesを追加。Carthage → CocoaPods：Carthageフレームワークを削除し、Podfileを作成し、依存関係を追加してpod init && pod installを実行。CarthageからCocoaPodsやSPMに移行する場合、手動でフレームワークを更新する必要がなくなり — すべての依存関係が1つのコマンドで更新されます。Carthageは、ベンダーロックインを回避し、依存関係ビルドの透明性を維持することが重要なプロジェクトで引き続き関連性があります。

一般的な問題とその解決策

Carthageは安定したツールですが、開発者は特にCIサーバーでのビルド、Xcodeの更新、Swiftバージョンの変更時に定期的に一般的な問題に直面します。ほとんどの問題は、キャッシュのクリア、--use-xcframeworksの適切な設定、最小iOSバージョンの確認で解決します。

エラー「The file manager returned an error」 — Carthageキャッシュの破損またはファイル権限の競合時に発生します。解決策：rm -rf ~/Library/Caches/carthageでキャッシュを削除し、carthage bootstrapを再実行します。プロジェクトのCarthage/ディレクトリを削除して再ビルドすることも有効です。CIサーバーでは、Cartfile.resolvedが変更された場合のみCarthageキャッシュを更新する必要があります。

エラー「No such module」 — Carthageのビルドは成功したが、フレームワークがXcodeで見つかりません。解決策：General → Frameworks, Libraries, and Embedded Contentでフレームワークのパスを確認します。フレームワークはCarthage/Build/iOS/にある必要があります。.xcframeworkが正しく追加されていることを確認します（再度ドラッグ）。動的フレームワークの場合はEmbed & Signを確認します。エラーが続く場合は、Build SettingsにFRAMEWORK_SEARCH_PATHSを追加します。

Swiftの非互換性によるビルドエラー — ライブラリがプロジェクトとは異なるSwiftバージョン用にビルドされています。解決策：同じSwiftバージョンでソースからビルドするようcarthage update --no-use-binariesを使用します。ライブラリが現在のバージョンでコンパイルできない場合は、.xcconfigを使用してSwiftバージョンを指定するか、ライブラリをフォークします。Carthage 0.39以降、--use-xcframeworksはバイナリに正しいSwiftバージョンを自動的に含めます。

CIビルドの問題 — CI上のCarthageは適切なキャッシュ設定が必要です。解決策：Carthage/Build/と~/Library/Caches/carthage/をキャッシュします。CIではバージョン変更を避けるため、updateの代わりにcarthage bootstrap --use-xcframeworks --platform iOSを使用します。GitHub Actions用の公式Carthageアクションが利用可能です。Jenkins用 — CarthageBuildプラグイン。GUIなしのmacOSではCarthageがクラッシュする可能性があります — 解決策：brew install xcode-build-serverをインストールするか、-UseModernBuildSystem=NOフラグを追加します。