Carthage
0.40.0
Carthage は、Cocoa アプリケーションにフレームワークを追加する最も簡単な方法であることを目的としています。
Carthage は依存関係を構築し、バイナリ フレームワークを提供しますが、プロジェクトの構造とセットアップは完全に制御できます。 Carthage は、プロジェクト ファイルやビルド設定を自動的に変更しません。
brew install carthage実行して Carthage を入手するか、別のインストール方法を選択してください
.xcodeprojまたは.xcworkspaceと同じディレクトリに Cartfile を作成します。
Cartfile に必要な依存関係をリストします。次に例を示します。
github "Alamofire/Alamofire" ~> 5.5
carthage update --use-xcframeworksを実行します
Cartfile.resolvedファイルとCarthageディレクトリは、 .xcodeprojまたは.xcworkspaceと同じディレクトリに表示されます。
ビルドされた.xcframeworkバンドルをCarthage/Buildからアプリケーションの Xcode プロジェクトの「フレームワークとライブラリ」セクションにドラッグします。
アプリケーションに Carthage を使用している場合は、「埋め込みと署名」を選択し、それ以外の場合は「埋め込みしない」を選択します。
詳細なガイドについては、「アプリケーションへのフレームワークの追加」から読み続けてください。
Carthage をインストールするには複数のオプションがあります。
インストーラー:最新リリースのCarthage.pkgファイルをダウンロードして実行し、画面上の指示に従います。 CLI 経由で pkg をインストールする場合は、最初にsudo chown -R $(whoami) /usr/local実行する必要がある場合があります。
Homebrew: Homebrew を使用すると、 brew updateとbrew install carthage実行するだけでcarthageツールをシステムにインストールできます。 (注: 以前に Carthage のバイナリ バージョンをインストールした場合は、 /Library/Frameworks/CarthageKit.frameworkを削除する必要があります)。
MacPorts: MacPorts を使用すると、 sudo port selfupdateおよびsudo port install carthage実行するだけで、システムにcarthageツールをインストールできます。 (注: 以前に Carthage のバイナリ バージョンをインストールした場合は、 /Library/Frameworks/CarthageKit.frameworkを削除する必要があります)。
ソースから:最新の開発バージョン (非常に不安定または互換性がない可能性があります) を実行したい場合は、リポジトリのmasterブランチをクローンしてから、 make install実行します。 Xcode 10.0 (Swift 4.2) が必要です。
Carthage をインストールしたら、プロジェクトへのフレームワークの追加を開始できます。 Carthage は動的フレームワークのみをサポートしており、 iOS 8 以降 (または OS X の任意のバージョン) でのみ利用できることに注意してください。
carthage update --use-xcframeworksを実行します。これにより、依存関係が Carthage/Checkouts フォルダーにフェッチされ、それぞれがビルドされるか、コンパイル済みの XCFramework がダウンロードされます。バージョン 0.37.0 (2021 年 1 月) 以降では XCFrameworks を使用することをお勧めします。Apple Silicon Mac 上でビルドする場合は XCFrameworks が必要です。個別のフレームワーク バンドルから XCFrameworks に切り替えるには、プロジェクトにいくつかの変更を加える必要があります。
Carthage/Buildフォルダーを削除して、既存のフレームワーク バンドルをすべて削除します。carthage build --use-xcframeworksを実行して、新しい XCFrameworks をビルドします。構築に使用する他の引数は、通常どおりに指定できます。carthage copy-frameworksビルド フェーズが存在する場合は、削除します。Xcode 12 以降の非互換性: Xcode 12 以降でフレームワーク バンドルを構築する場合、マルチ アーキテクチャ プラットフォームはサポートされません。 XCFrameworks を使用して構築することをお勧めします。個別のフレームワーク バンドルを構築する必要がある場合は、回避策の xcconfig ファイルを使用してください。
carthage update --platform macOSを実行します。これにより、依存関係が Carthage/Checkouts フォルダーにフェッチされ、それぞれがビルドされるか、事前にコンパイルされたフレームワークがダウンロードされます。さらに、OS X でのデバッグとクラッシュ レポートのためにデバッグ シンボルをコピーする必要があります。
プロジェクトで使用するフレームワークをリストしたカートファイルを作成します。
carthage updateを実行します。これにより、依存関係が Carthage/Checkouts フォルダーにフェッチされ、それぞれがビルドされるか、事前にコンパイルされたフレームワークがダウンロードされます。
アプリケーションターゲットの「一般設定」タブを開きます。 Xcode 11.0 以降の場合、「フレームワーク、ライブラリ、埋め込みコンテンツ」セクションで、使用する各フレームワークをディスク上の Carthage/Build フォルダーからドラッグ アンド ドロップします。次に、「埋め込み」セクションで、追加した各項目のプルダウン メニューから「埋め込まない」を選択します。 Xcode 10.x 以前の場合、「リンクされたフレームワークとライブラリ」セクションで、使用する各フレームワークをディスク上の Carthage/Build フォルダーからドラッグ アンド ドロップします。
アプリケーション ターゲットの[ビルド フェーズ]設定タブで、 +アイコンをクリックし、 [新しい実行スクリプト フェーズ]を選択します。シェル (例: /bin/sh ) を指定する実行スクリプトを作成し、シェルの下のスクリプト領域に次の内容を追加します。
/usr/local/bin/carthage copy-frameworks input.xcfilelistという名前のファイルとoutput.xcfilelistという名前のファイルを作成します。
使用するフレームワークへのパスをinput.xcfilelistに追加します。例えば：
$(SRCROOT)/Carthage/Build/iOS/Result.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework
コピーしたフレームワークへのパスをoutput.xcfilelistに追加します。例えば：
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework
入力ファイルと一緒に出力ファイルを指定すると、Xcode は入力ファイルが変更された場合、または出力ファイルが見つからない場合にのみスクリプトを実行する必要があります。これは、Carthage でフレームワークを再構築していない場合、ダーティ ビルドが高速になることを意味します。
input.xcfilelist Carthage 実行スクリプトフェーズの「入力ファイルリスト」セクションに追加します。
output.xcfilelist Carthage 実行スクリプトフェーズの「出力ファイルリスト」セクションに追加します。
このスクリプトは、ユニバーサル バイナリによって引き起こされる App Store 送信のバグを回避し、アーカイブ時に必要なビットコード関連のファイルと dSYM が確実にコピーされるようにします。
ビルドされた製品ディレクトリにコピーされたデバッグ情報を使用すると、Xcode はブレークポイントで停止するたびにスタック トレースをシンボライズできるようになります。これにより、デバッガーでサードパーティのコードをステップ実行することもできます。
App Store または TestFlight に提出するためにアプリケーションをアーカイブするとき、Xcode はこれらのファイルをアプリケーションの.xcarchiveバンドルの dSYMs サブディレクトリにもコピーします。
その過程で、カルタゴはいくつかのビルド アーティファクトを作成することになります。これらの中で最も重要なのは Cartfile.resolved ファイルです。このファイルには、各フレームワーク用に実際にビルドされたバージョンがリストされています。プロジェクトを使用する他のユーザーが同じフレームワーク バージョンをビルドするためにそのファイルが必要になるため、必ず Cartfile.resolved をコミットしてください。
スクリプトの実行フェーズを追加して、依存関係の 1 つが古くなったときに自動的に警告することができます。
Build Phases設定タブで、 +アイコンをクリックし、 New Run Script Phaseを選択します。シェル (例: /bin/sh ) を指定する実行スクリプトを作成し、シェルの下のスクリプト領域に次の内容を追加します。 /usr/local/bin/carthage outdated --xcode-warnings 2> /dev/nullCarthage は、ダウンロードされた Swift (および Objective-C/Swift 混合) フレームワークが、ローカルで使用されているのと同じバージョンの Swift で構築されたことを確認します。バージョンの不一致がある場合、Carthage はソースからフレームワークの構築を続行します。フレームワークをソースから構築できない場合、カルタゴは失敗します。
Carthage はxcrun swift --versionの出力を使用してローカルの Swift バージョンを決定するため、使用する予定の Swift ツールチェーンで Carthage コマンドを実行するようにしてください。多くのユースケースでは、追加の必要はありません。ただし、たとえば、Xcode 8.x を使用して Swift 2.3 プロジェクトを構築している場合、 carthage bootstrapにデフォルトのswiftを指定する 1 つの方法は、次のコマンドを使用することです。
TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap
上記の手順を完了して変更をプッシュした後、プロジェクトの他のユーザーはリポジトリをフェッチしてcarthage bootstrap実行するだけで、追加したフレームワークの使用を開始できます。
任意のターゲットの依存関係に Carthage を使用することは、アプリケーションに Carthage を使用することと非常に似ています。主な違いは、Xcode でフレームワークが実際にどのように設定され、リンクされるかにあります。
単体テスト ターゲットには[全般設定] タブに[リンクされたフレームワークとライブラリ]セクションがないため、代わりに、ビルドされたフレームワークを[ライブラリとバイナリをリンク]ビルド フェーズにドラッグする必要があります。
[ビルド設定]タブのテスト ターゲットで、 @loader_path/Frameworks実行パスの検索パスに追加します (まだ存在しない場合)。
まれに、各依存関係をビルド製品にコピーすることも必要な場合があります (たとえば、外部フレームワーク内に依存関係を埋め込むため、または依存関係がテスト バンドルに存在することを確認するため)。これを行うには、フレームワークの宛先を使用して新しいファイルのコピービルド フェーズを作成し、そこにフレームワーク参照も追加します。テスト バンドルではフレームワークを削除する必要がなく、 copy-frameworksの同時インスタンスの実行 (並列ビルドをオンにした状態) はサポートされていないため、 carthage copy-frameworksコマンドは使用しないでください。
Cartfile を変更した場合、または (指定した要件に従って) 各フレームワークの最新バージョンに更新する場合は、 carthage updateコマンドを再度実行するだけです。
1 つまたは特定の依存関係のみを更新する場合は、依存関係をスペース区切りのリストとしてupdateコマンドに渡します。例えば
carthage update Box
または
carthage update Box Result
速度の向上とメモリ使用量の削減を目的として、フレームワークをアップグレードするためのロジックが書き直されました。現在はオプトイン機能です。 --new-resolver更新コマンドに渡すことで使用できます。たとえば、
carthage update --new-resolver Box
アップデート中にパフォーマンスの問題が発生した場合は、新しいリゾルバーを試してください。
プロジェクトに追加したいフレームワークの依存関係がカートファイルに明示的にリストされている場合、Carthage はそれらを自動的に取得します。その後、それらを Carthage/Build フォルダーから自分でプロジェクトにドラッグする必要があります。
プロジェクトに埋め込まれたフレームワークに他のフレームワークへの依存関係がある場合は、それらをアプリケーション ターゲットにリンクする必要があります (アプリケーション ターゲットがそのフレームワークへの依存関係がなく、それらを使用しない場合でも)。
デフォルトでは、Carthage は依存関係のソース ファイルをプロジェクト フォルダーに直接チェックアウトし、依存関係をコミットするか無視するかを選択できます。代わりに Git サブモジュールとして依存関係を利用できるようにしたい場合 (おそらく、サブモジュール内で変更をコミットしてプッシュできるようにするため)、 --use-submodulesフラグを指定してcarthage updateまたはcarthage checkout実行できます。
この方法で実行すると、Carthage はリポジトリの.gitmodulesおよび.git/configファイルに書き込み、依存関係のバージョンが変更されるとサブモジュールを自動的に更新します。
開発中に依存関係に取り組み、親プロジェクトをビルドするときに依存関係を自動的に再ビルドしたい場合は、次のように Carthage を呼び出すスクリプト実行ビルド フェーズを追加できます。
/usr/local/bin/carthage build --platform " $PLATFORM_NAME " --project-directory " $SRCROOT "プレーンチェックアウトは直接変更すべきではないため、これを行う前にサブモジュールを使用する必要があることに注意してください。
デフォルトでは、Carthage は、以前と同じ解決されたバージョンであるかどうかに関係なく、依存関係を再構築します。 --cache-builds渡すと、carthage は依存関係の再構築を可能であれば回避します。 Carthage がこのキャッシュを実行する方法の詳細については、バージョン ファイルに関する情報を参照してください。
注: 現時点では、 --cache-builds --use-submodulesと互換性がありません。両方を使用すると、作業コピーとサブモジュールの依存関係に対するコミットされた変更が正しく再構築されなくなります。詳細については #1785 を参照してください。
Bash/Zsh/Fish Completion に記載されているように、Carthage コマンドとオプションの自動補完が利用可能です。
Carthage は動的フレームワークのみを公式にサポートしています。動的フレームワークは、OS X のどのバージョンでも使用できますが、 iOS 8 以降でのみ使用できます。さらに、バージョン 0.30.0 以降、Carthage は静的フレームワークをサポートしています。
Carthage には集中化されたパッケージ リストやプロジェクト仕様フォーマットがないため、ほとんどのフレームワークは自動的に構築されます。
フレームワーク プロジェクトの具体的な要件を以下に示します。
Carthage は、 .xcodeprojから共有される Xcode スキームのみを構築します。 carthage build --no-skip-currentを実行し、Carthage/Build フォルダーをチェックすることで、意図したスキームがすべて正常にビルドされたかどうかを確認できます。
コマンドの実行時に重要なスキームが構築されていない場合は、Xcode を開いてスキームがSharedとしてマークされていることを確認し、Carthage がスキームを検出できるようにします。
carthage build --no-skip-currentでビルド障害が発生した場合は、 xcodebuild -scheme SCHEME -workspace WORKSPACE buildまたはxcodebuild -scheme SCHEME -project PROJECT build (実際の値を使用) を実行して、同じ障害が発生するかどうかを確認してください。これにより、問題を解決するのに十分な情報が得られるはずです。
Apple 開発者ツールの複数のバージョンがインストールされている場合 (Xcode ベータ版など)、 xcode-select使用して Carthage が使用するバージョンを変更します。
それでも Carthage でフレームワークを構築できない場合は、問題を開いてください。喜んでお手伝いします。
Carthage は、リポジトリ上で公開されているタグを検索し、各タグ名をセマンティック バージョンとして解釈することによって、フレームワークのどのバージョンが利用可能であるかを判断します。たとえば、タグv1.2では、セマンティック バージョンは 1.2.0 です。
バージョン番号のないタグ、またはバージョン番号の後に文字が続くタグ ( 1.2-alpha-1など) は現在サポートされておらず、無視されます。
Carthage は、プロジェクトのリポジトリ上の GitHub リリースにアタッチされている場合、またはバイナリ プロジェクト定義ファイルを介して、事前に構築されたフレームワークを最初から構築するのではなく、自動的に使用できます。
特定のタグに事前構築されたフレームワークを提供するには、サポートされているすべてのプラットフォームのバイナリを1 つのアーカイブにまとめて圧縮し、そのアーカイブをそのタグに対応する公開リリースに添付する必要があります。添付ファイルにはバイナリが含まれていることを Carthage に示すために、その名前に.frameworkを含める必要があります (例: ReactiveCocoa.framework.zip )。アーカイブのディレクトリ構造は自由形式ですが、フレームワークはその名前 (例: ReactiveCocoa.framework ) に基づいてCarthage/Build/<platform>にコピーされるため、アーカイブ内に 1 回だけ出現する必要があります。
事前にビルドされた XCFrameworks を提供するには、 --use-xcframeworksを使用してビルドし、同じプロセスに従ってすべての XCFrameworks を 1 つのアーカイブに圧縮します。添付ファイル名に.xcframeworkを含めます。バージョン 0.38.0 以降、Carthage は--use-xcframeworksが渡された場合に.xcframework添付ファイルのダウンロードを優先します。
以下を使用して、carthage 自体でアーカイブ操作を実行できます。
-carthage build --no-skip-current
-carthage archive YourFrameworkNameまたはその代わりに
carthage build --archiveドラフト リリースは、目的のタグに対応している場合でも、自動的に無視されます。
travis-ci を使用して、タグ付きリリースをビルドしてアップロードすることができます。
gem install travisで travis CLI をインストールする
リポジトリ用に travis-ci をセットアップします (ステップ 1 および 2)
そのテンプレートに基づいて、リポジトリのルートに.travis.ymlファイルを作成します。 FRAMEWORK_NAME正しい値に設定します。
PROJECT_PLACEHOLDER と SCHEME_PLACEHOLDER を置き換えます
プロジェクトの代わりにワークスペースを使用している場合は、xcode_project 行を削除し、xcode_workspace 行のコメントを解除します。
プロジェクトの形式は MyProject.xcodeproj である必要があります。
ワークスペースの形式は MyWorkspace.xcworkspace である必要があります。
xcode_sdk値を別の SDK に自由に更新できます。iphoneos SDK でテストするには、コード署名 ID をアップロードする必要があることに注意してください。
詳細については、objective-c プロジェクトの travis ドキュメントにアクセスしてください。
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 travis setup releasesを実行し、ここのドキュメントに従ってください
このコマンドは、travis がリリースを GitHub.com にアップロードできるようにするために、GitHub 認証情報を.travis.ymlファイルにエンコードします。アップロードするファイルを要求されたら、 $FRAMEWORK_NAME.framework.zipと入力します。
タグ上で実行するようにデプロイ セクションを更新します。
.travis.ymlで次の場所を見つけます。
on :
repo : repo/repoそして、 tags: trueとskip_cleanup: trueを追加します。
skip_cleanup : true
on :
repo : repo/repo
tags : trueこれにより、新しいタグがプッシュされたときにデプロイメントを作成することが travis に通知され、生成された zip ファイルを travis がクリーンアップするのを防ぐことができます。
多くの動的フレームワークをアプリに埋め込む場合、メイン前の起動時間が非常に遅くなる可能性があります。 Carthage は、代わりに動的フレームワークを静的フレームワークとして構築することで、これを軽減できます。静的フレームワークは、アプリケーションに直接リンクしたり、ワークフローにいくつかの簡単な変更を加えてより大きな動的フレームワークに統合したりすることができ、その結果、メイン前の起動時間を大幅に短縮することができます。
バージョン 0.30.0 以降、Carthage プロジェクトは、Swift または Objective-C で記述された静的にリンクされたフレームワークのサポートを展開します。このフレームワークのサポートは Xcode 9.4 で導入されました。ただし、特にFrameworkと書かれているため、Darwin は.framework拡張子と静的にリンクされたオブジェクト アーカイブを内部にバンドルしていることに注意してください。 Carthage は現在静的ライブラリスキームをサポートしておらず、将来的に静的ライブラリ スキームのサポートを導入する予定もありません。
ワークフローはほとんど変わりません。
しかし：
詳細については、StaticFrameworks のドキュメントを参照してください。
このアプローチにはいくつかの注意事項が適用されることに注意してください。
あなたのプロジェクトが Carthage で使用できることを宣伝したいですか?互換性バッジを追加できます。
…次のマークダウンを挿入するだけでREADMEに追加できます。
[ ![ Carthage compatible ] ( https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat )] ( https://github.com/Carthage/Carthage ) 事前構築されたフレームワークは、フレームワークが構築されたマシン以外のマシンでステップ実行を使用してデバッグすることはできません。 carthage bootstrap/build/update --no-use-binariesだけでこの問題は修正されるはずですが、より自動化された回避策については #924 を参照してください。 Apple にこの問題の根本原因を修正してもらいたい場合は、rdar://23551273 を複製してください。
carthageコマンド ライン ツールの機能のほとんどは、実際には CarthageKit という名前のフレームワークにカプセル化されています。
Carthage を別のツールの一部として使用することに興味がある場合、または Carthage の機能を拡張することに興味がある場合は、CarthageKit のソース コードを見て、API がニーズに合うかどうかを確認してください。
CocoaPods は、Cocoa の長年にわたる依存関係マネージャーです。では、なぜカルタゴが作られたのでしょうか？
まず、CocoaPods (デフォルト) は、アプリケーションとすべての依存関係用の Xcode ワークスペースを自動的に作成および更新します。 Carthage はxcodebuild使用してフレームワーク バイナリを構築しますが、それらを統合する責任はユーザーにあります。 CocoaPods のアプローチは使いやすいのに対し、Carthage のアプローチは柔軟で邪魔になりません。
CocoaPods の目標は、README に次のように記載されています。
…より一元化されたエコシステムを作成することで、サードパーティのオープンソース ライブラリの発見しやすさと、そのライブラリへの関与を向上させる。
対照的に、Carthage は分散型依存関係マネージャーとして作成されました。プロジェクトの集中リストがないため、メンテナンス作業が軽減され、中心的な障害点が回避されます。ただし、プロジェクトの発見はさらに難しく、ユーザーは GitHub のトレンド ページなどを利用する必要があります。
CocoaPods プロジェクトには、プロジェクトに関するメタデータが含まれ、プロジェクトの構築方法を指定する podspec ファイルと呼ばれるものも必要です。 Carthage は依存関係を単一のワークスペースに統合するのではなく、 xcodebuild使用して依存関係を構築します。同様の仕様ファイルはありませんが、依存関係には製品のビルド方法を記述した独自の Xcode プロジェクトを含める必要があります。
最終的に、私たちが Carthage を作成したのは、可能な限りシンプルなツール、つまり Xcode の責任を引き継ぐことなく、フレームワーク作成者に余分な作業を発生させずに仕事を完了させる依存関係マネージャーを求めたからです。 CocoaPods は、さらなる複雑さを犠牲にして、Carthage には決して搭載できない多くの驚くべき機能を提供します。
Carthage は MIT ライセンスに基づいてリリースされています。
ヘッダーの背景写真は CC BY-NC-SA 2.0 ライセンスに基づいて公開されています。リチャード・モーテルによるオリジナル写真。
