はじめに (対象読者・この記事でわかること)

本記事は、iOSアプリ開発においてCarthageでAlamofireを導入したものの、ビルドエラーやリンクエラーで利用できないと悩んでいるSwiftエンジニア向けに書かれています。
Carthageの基本的な使い方は理解しているが、依存ライブラリのバージョン不整合や Xcode の設定で詰まっている方が対象です。この記事を読むと、エラーメッセージの読み取り方、原因となる設定項目、実際に動作するプロジェクトを作るまでのフローがすべて把握でき、すぐに開発を再開できるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。
- Swift と Xcode の基本的な操作
- Carthage のインストールと Cartfile の記述方法
- Alamofire の概要と利用イメージ

背景と問題の概要

Carthage は軽量な依存管理ツールとして iOS 開発者に人気がありますが、バイナリ配布方式のため、Xcode のビルド設定や Swift のバージョンと微妙にずれることがあります。特に Alamofire は頻繁にメジャーアップデートが行われ、Carthage のビルドスクリプトが対応しきれないケースが散見されます。
典型的な問題は次の通りです。

  1. リンクエラー：Undefined symbols for architecture x86_64: "_OBJC_CLASS_$_Alamofire" などが出る。
  2. ビルド失敗：[Carthage] Building Alamofire for iOS の途中で error: Unable to find a matching version for property 'swift-version' が表示される。
  3. ビルド設定の不整合：Framework Search Paths が正しく設定されていない、もしくは Enable Bitcode がオンのままビルドすることでエラーになる。

これらは「Alamofire がプロジェクトに組み込めていない」状態の根本原因です。本章では、まず問題の切り分け手順を示し、次に確実に動作させるための設定変更を解説します。

具体的な手順と実装方法

ステップ 1: Carthage と Alamofire のバージョン確認

まずは Cartfile と Carthage のバージョンを最新版に合わせます。

Bash

# Carthage のバージョン確認
carthage version
# 例: 0.38.0 以上が推奨

# Cartfile の記述例
github "Alamofire/Alamofire" ~> 5.7

~> 演算子はメジャーリリースを固定しつつ、マイナーバージョンは自動で取得できるため、Xcode の Swift バージョンと整合しやすくなります。記述後に以下を実行します。

Bash

carthage update --use-xcframeworks --platform iOS

--use-xcframeworks オプションは、Apple が推奨する XCFramework 形式でビルドさせ、Bitcode の有無に関係なく利用できるようにします。

ステップ 2: Xcode プロジェクトへのフレームワーク追加

  1. 「Frameworks, Libraries, and Embedded Content」 に Alamofire.framework をドラッグ＆ドロップします。
  2. 「Embed」 の項目は “Embed & Sign” を選択。これにより、実機・シミュレータ両方で正しくリンクされます。
  3. 「Build Settings」 の Framework Search Paths に $(PROJECT_DIR)/Carthage/Build/iOS が含まれているか確認し、無ければ手動で追加します。

ポイント：Carthage が生成したフレームワークは Carthage/Build/iOS 配下に置かれますが、XCFramework を使用した場合は Carthage/Build/Alamofire.xcframework が生成されます。Framework Search Paths にはそれぞれのパスを追加してください。

ステップ 3: Swift コンパイラ設定の統一

Alamofire のバイナリは Swift 5.5+ を前提にビルドされています。プロジェクト側が Swift 5.2 以前になっているとリンク時にシンボルが見つからないエラーが出ます。

  • 「Build Settings」 → 「Swift Compiler - Language」 → 「Swift Language Version」 を “Swift 5.5” 以上に統一します。
  • 同様に Build Active Architecture Only を YES（デバッグ時）にして、シミュレータと実機の両方でビルドできるようにします。

ステップ 4: Clean ビルドとキャッシュクリア

設定変更後、Xcode のビルドキャッシュが残っていると再度エラーになることがあります。

Bash

# DerivedData の削除
rm -rf ~/Library/Developer/Xcode/DerivedData/*
# Carthage のキャッシュクリア（必要に応じて）
carthage cache clean Alamofire

その後、Xcode で Product → Clean Build Folder を実行し、再ビルドします。

ハマった点やエラー解決

1. 「Undefined symbols for architecture arm64」になるケース

  • 原因：Embed & Sign が設定されていない、もしくは Framework Search Paths が間違っている。
  • 解決策：Embed & Sign に設定し直し、$(PROJECT_DIR)/Carthage/Build/iOS を追加。

2. 「Unable to find a matching version for property 'swift-version'」エラー

  • 原因：Carthage が利用している Swift のバージョンと、プロジェクトで指定しているバージョンが不一致。
  • 解決策：Carthage と Xcode の両方で同じ Swift バージョン（例：5.5）を使用するように Cartfile の記述を見直し、carthage update を再実行。

3. Bitcode 関連エラー

  • 原因：XCFramework でビルドされた Alamofire が Bitcode をサポートしていない（古いバイナリの場合）。
  • 解決策：Build Settings の Enable Bitcode を NO に変更。もしくは、--use-xcframeworks オプションで再ビルドし、Bitcode 対応バイナリを取得。

まとめ

本記事では、Carthage で導入した Alamofire が利用できない典型的な原因と、バージョン統一、XCFramework の活用、Xcode の設定見直し という３つの観点から具体的な解決手順を示しました。

  • 原因の切り分け：リンクエラー・ビルドエラーはバージョンと検索パスの不整合が多い
  • 解決策：--use-xcframeworks + 正しい Swift バージョン + Embed & Sign の設定が必須
  • 次のステップ：CocoaPods・Swift Package Manager への移行や、CI 環境での Carthage ビルド自動化

これらを実践すれば、Alamofire の導入障壁が大幅に下がり、開発のスピードが向上します。今後は、Carthage と他の依存管理ツールの比較や、マルチプラットフォーム（macOS、watchOS）での Alamofire 活用についても取り上げていく予定です。

参考資料