Contents
前提条件と推奨環境
この章では、Swift 6 系列(6.2〜6.4) をローカルで快適に扱うために最低限必要なハードウェア・ソフトウェア構成を整理します。
対象読者は macOS/Windows 環境で SPM を使い始めたばかりの初心者から、複数パッケージを日常的に管理する中級者までです。
推奨環境
| 項目 | 推奨バージョン・条件 | 補足 |
|---|---|---|
| OS | macOS Ventura (12.7) 以上、もしくは macOS Sonoma (13.x) Windows 11 ビルド 22631 以降 |
両 OS の最新パッチ適用が前提です。 |
| Xcode | Xcode 15 系列(現在は 15.3 が最新版) | Swift コンパイラと SPM の統合が最も安定しています。 |
| Swift Toolchain | Swift 6.2〜6.4(公式バイナリまたは Homebrew) | CLI 環境でのビルド・テストに必須です。 |
| IDE / エディタ | macOS: Xcode Windows: VS Code + Apple 提供 Swift Extension |
Visual Studio 2022 には公式な Swift コンパイラ連携はありません(※)。 |
| ストレージ | 空き容量 50 GB 以上(Xcode 本体約45 GB、ツールチェーン+依存ライブラリ分) | 大規模プロジェクトや CI ランナーを想定した余裕です。 |
| 権限 | 管理者権限(Homebrew インストール時/PATH 変更時) | 標準的なセットアップで必要になります。 |
※ Visual Studio 2022 と Swift の公式統合は、執筆時点では Microsoft が提供する「Swift for Windows」バイナリと VS Code 拡張機能が主流です。公式ドキュメントに記載のない情報は未確認として扱います。
補足:CocoaPods の現状
- CocoaPods は 2026 年に「読み取り専用モード」へ移行 するという情報は現在(2024 年)公表されていません。
- 現時点では SPM が Apple 推奨の依存管理手段 として位置付けられていますが、CocoaPods は引き続き保守されています[^1]。
Xcode と Swift Toolchain のインストール手順
本章では macOS と Windows それぞれで Xcode 15.x および Swift 6 系列ツールチェーン を取得し、パス設定やバージョン確認までを具体的に示します。公式サイトと Homebrew の二通りの方法を提示することで、環境に合わせた選択が可能です。
2‑1. Xcode 15.x の取得とバージョン確認
概要:Apple Developer のダウンロードページから Xcode の .xip アーカイブを取得し、/Applications に配置します。インストール後は xcode-select と xcodebuild で正しく認識されているか確認します。
手順
- Apple Developer(https://developer.apple.com/download/all/)にサインイン
- 「Xcode 15.3」→「Download」ボタンをクリックし
.xipを取得 - ダウンロード完了後、ダブルクリックで解凍 →
Xcode.appを/Applicationsにドラッグ - ターミナルで以下を実行
bash
xcode-select --version # 例: Xcode Select version: 2379
xcodebuild -version # 例: Xcode 15.3\nBuild version 15D100
- 必要に応じて
sudo xcode-select -s /Applications/Xcode.app/Contents/Developerでデフォルトツールチェーンを設定
ポイント:Xcode のインストールは数 GB のディスク容量と時間がかかります。ネットワークが不安定な場合は Apple の公式ミラーからのダウンロードを検討してください。
2‑2. macOS 用公式 Swift ツールチェーンの入手方法
概要:Xcode に同梱されたコンパイラだけでなく、CLI 専用の Swift Toolchain を別途インストールするとビルド時間が短縮されます。Homebrew と公式 .pkg の二通りを比較します。
2‑2‑1. Homebrew 経由(推奨)
|
1 2 3 4 5 |
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" brew update brew install swift # 現行は Swift 6.4 がインストールされます swift --version # 確認例: Swift version 6.4 (swift-6.4-RELEASE) |
2‑2‑2. 公式サイトから直接ダウンロード
- https://swift.org/download/#releases にアクセス
- 「Swift 6.2 (macOS)」または「Swift 6.4 (macOS)」の
.pkgを取得 - ダブルクリックでインストーラ実行 → 指示に従い完了
比較表
| 方法 | メリット | デメリット |
|---|---|---|
| Homebrew | 依存関係自動解決、アップデートが簡単 | Homebrew が未インストールの場合は先行作業が必要 |
公式 .pkg |
Apple の署名済みパッケージで安全 | バージョン切替が手動になる |
2‑3. Windows 用 Swift バイナリの取得と PATH 設定
概要:Windows では swift.org が提供する ZIP 配布版を解凍し、システム環境変数 PATH に usr\bin を追加すれば CLI が利用可能です。Visual Studio との統合は公式には存在せず、VS Code + Swift Extension が主流です。
手順
- https://swift.org/download/#releases → 「Swift 6.4 (Windows)」ZIP(約 200 MB)をダウンロード
- 任意のディレクトリに解凍(例:
C:\Swift\swift-6.4) - システム環境変数 →
PathにC:\Swift\swift-6.4\usr\binを追記 - Windows 10/11 の場合は「設定」→「システム」→「バージョン情報」→「詳細設定」からアクセス
- 新しいコマンドプロンプト/PowerShell を開き確認
powershell
swift --version
# 出力例: Swift version 6.4 (swift-6.4-RELEASE)
注意:PATH の変更は管理者権限が必要です。環境変数を誤って削除すると他のツールに影響するため、バックアップを取ってから作業してください。
Swift Package Manager (SPM) による新規パッケージ作成
この章では コマンドライン だけで完結する SPM パッケージの雛形生成手順と、Package.swift の主要構文を解説します。実務で即座に利用できるテンプレートを把握しておくことが目的です。
3‑1. swift package init の基本オプション
概要:swift package init コマンドは、プロジェクトタイプに応じたディレクトリ構造とサンプルコードを自動生成します。主なオプションは --type library(ライブラリ) と --type executable(コマンドラインツール)の二つです。
実行例
|
1 2 3 |
mkdir MyLibrary && cd MyLibrary swift package init --type library # ライブラリテンプレート生成 |
| 生成物 | 内容 |
|---|---|
Package.swift |
パッケージメタ情報と依存関係の定義 |
Sources/ |
実装コード(モジュールごとにサブフォルダ) |
Tests/ |
XCTest ベースのテストケース |
ポイント:Swift 6 では
binaryTarget,plugin,unsafeFlagsが新たに利用可能です。後述のPackage.swift解説で併せて確認してください。
3‑2. Package.swift の主要セクション解説
概要:Package.swift は Swift Tools Version を先頭に記述し、以下のブロックで構成されます。各項目は macOS・iOS・Windows など複数プラットフォームへの対応を一元管理できます。
サンプル(Swift 6.4 対応)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
// swift-tools-version: 6.4 import PackageDescription let package = Package( name: "MyLibrary", platforms: [ .iOS(.v15), .macOS(.v13), // Ventura/Sonoma が対象 .windows(.v10) ], products: [ .library(name: "MyLibrary", targets: ["MyLibrary"]) ], dependencies: [ // 例: Apple の Collections ライブラリ .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.0") ], targets: [ .target( name: "MyLibrary", dependencies: [.product(name: "Collections", package: "swift-collections")], swiftSettings: [ // 実験的機能を有効化(CI では除外可) .unsafeFlags(["-enable-experimental-feature", "VariadicGenerics"]) ] ), .testTarget( name: "MyLibraryTests", dependencies: ["MyLibrary"] ), // 外部バイナリ配布例 .binaryTarget( name: "FastMath", url: "https://example.com/FastMath.xcframework.zip", checksum: "3a5e2f9d4b..." ) ] ) |
| セクション | 目的 |
|---|---|
platforms |
対応 OS と最低バージョンを宣言。未指定の場合は全プラットフォーム対象 |
products |
他パッケージが利用できる成果物(ライブラリ・実行ファイル)を定義 |
dependencies |
外部パッケージへの参照 URL とバージョン範囲 |
targets |
ソースコードとテストコードのビルド単位。binaryTarget, plugin, unsafeFlags が新要素 |
注:
unsafeFlagsは実験的機能や外部ツールチェーンに依存する場合のみ使用し、リリースビルドでは除外する設定 (.when(configuration: .release)) を推奨します。
3‑3. Sources/ と Tests/ ディレクトリの役割
概要:SPM は 慣習的なフォルダ構造 を自動的に認識します。Sources/ に置いたコードはパッケージ本体、Tests/ には XCTest テストが格納されます。
実装例
Sources/MyLibrary/Hello.swift
|
1 2 3 4 5 6 7 |
public struct Hello { public init() {} public func greet(name: String) -> String { "Hello, \\(name)!" } } |
Tests/MyLibraryTests/HelloTests.swift
|
1 2 3 4 5 6 7 8 9 10 |
import XCTest @testable import MyLibrary final class HelloTests: XCTestCase { func testGreet() { let h = Hello() XCTAssertEqual(h.greet(name: "Swift"), "Hello, Swift!") } } |
| ディレクトリ | 主なファイル例 | ビルド・テストへの影響 |
|---|---|---|
Sources/ |
MyLibrary/*.swift |
swift build 時に自動的にモジュール化 |
Tests/ |
MyLibraryTests/*.swift |
swift test が検出し実行 |
ベストプラクティス:テストコードは必ず
@testable importで本体を参照し、ビジネスロジックの単体テストを網羅的に書くことが CI の信頼性向上につながります。
macOS / Windows でのビルド・テスト手順
ここでは Xcode と VS Code を利用した、ローカルパッケージの組み込みから実行までのフローを具体的に示します。プラットフォームごとの UI 操作と CLI コマンドを併記し、どちらでも同様の結果が得られることを確認できます。
4‑1. Xcode からローカル SPM パッケージを組み込む方法
概要:Xcode の UI で File → Swift Packages → Add Package Dependency… を選択すると、ローカルフォルダでもリモート URL でも依存関係が自動的に解決されます。手作業で Package.resolved を編集する必要はありません。
手順
- Xcode で対象アプリ(iOS / macOS)プロジェクトを開く
- メニューバー → File → Swift Packages → Add Package Dependency…
- 「Enter package repository URL」欄にローカルパスを入力(例:
file:///Users/you/MyLibrary)または Git のリモート URL を貼り付け - バージョン指定画面で「Branch」「Exact version」等を選択し Next → Finish
追加後、プロジェクトの Package Dependencies に表示され、対象ターゲットの Frameworks, Libraries, and Embedded Content に自動的にリンクされます。
ポイント:ローカルパッケージは Git 管理が必須です。未コミット状態だと Xcode が正しく認識しない場合がありますので、
git add . && git commit -m "Initial"を事前に実行してください。
4‑2. VS Code + Swift Extension による Windows 開発フロー
概要:Windows 環境では VS Code と Apple が提供する Swift Language Extension を組み合わせて、コード補完・シンタックスハイライト・ビルドタスクを実現します。CLI (swift build / swift test) での動作確認も同時に行えます。
セットアップ手順
- VS Code を公式サイトからインストール
- 拡張機能マーケットプレイスで「Swift」 → Apple Swift Language Extension を検索しインストール
settings.jsonに実行ファイルパスと LSP パスを追記
json
{
"swift.path": "C:/Swift/swift-6.4/usr/bin/swift.exe",
"swift.languageServerPath": "C:/Swift/swift-6.4/usr/bin/sourcekit-lsp.exe"
}
- プロジェクトルートで VS Code のターミナルを開き、以下コマンドでビルド・テスト
powershell
swift build # コンパイル
swift test # XCTest 実行
- ビルド結果は Problems パネルにエラーが表示され、テストはターミナル上の出力と Test Explorer(拡張機能)で確認可能
注意:VS Code の拡張機能はまだ開発途上です。IDE 内の自動補完が不完全な場合は CLI を直接利用してください。
4‑3. Swift 6 で追加された binaryTarget・plugin・unsafeFlags の実装例
概要:Swift 6 では 外部バイナリ配布、ビルド時プラグイン、未公開フラグ が公式にサポートされました。以下はそれぞれの最小構成例です。
binaryTarget の使用例
|
1 2 3 4 5 6 |
.binaryTarget( name: "FastMath", url: "https://example.com/FastMath.xcframework.zip", checksum: "a1b2c3d4e5f6..." ) |
- 用途:大容量の C/C++ ライブラリやサードパーティ製 XCFramework を直接 SPM で取り込む
- 注意点:
checksumはswift package compute-checksum <file>コマンドで生成し、改ざん防止に利用
plugin の使用例(ビルドツールプラグイン)
|
1 2 3 4 5 6 |
.plugin( name: "CodeGenPlugin", capability: .buildTool(), path: "./Plugins/CodeGen" ) |
- 用途:コード生成やリント、カスタムスクリプトをビルドフェーズに組み込む
- 実装:
Package.swiftと同じレポジトリ内に Swift パッケージとしてプラグイン本体を書く
unsafeFlags の使用例(実験的機能)
|
1 2 3 4 5 6 7 |
.target( name: "MyLibrary", swiftSettings: [ .unsafeFlags(["-enable-experimental-feature", "VariadicGenerics"]) ] ) |
- 用途:コンパイラがまだ正式に提供していないオプションを一時的に有効化
- ベストプラクティス:リリースビルドでは除外し、
.when(configuration: .debug)のように条件付ける
実務で活用する Git 管理と CI/CD 設定
本章は GitHub へのパッケージ公開、GitHub Actions による macOS/Windows クロスプラットフォーム CI の構築、そして開発中に頻出するエラーの対処法をまとめます。実務での運用を意識したチェックリスト形式にしています。
5‑1. ローカルリポジトリ作成から GitHub へのプッシュまで
概要:SPM パッケージはシンプルなディレクトリ構造のため、.gitignore にビルド成果物を除外すれば軽量リポジトリが完成します。
手順
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
cd MyLibrary # 既に SPM パッケージがある前提 git init cat <<EOS > .gitignore .build/ Packages/ *.xcworkspace DerivedData/ EOS git add . git commit -m "Initial Swift Package" # GitHub 上で新規リポジトリ作成(例: https://github.com/you/MyLibrary) git remote add origin git@github.com:you/MyLibrary.git git branch -M main git push -u origin main |
- ポイント:
mainブランチをデフォルトに設定し、GitHub の「Protected Branch」機能で CI が成功するまでマージできないよう制御すると安全です。
5‑2. GitHub Actions を使った macOS / Windows クロスプラットフォーム CI
概要:以下の YAML は push と pull request のたびに macOS(Apple Silicon)と Windows ランナーで swift build・swift test を実行します。macOS では Homebrew 経由、Windows では swift-actions/setup-swift アクションを利用しています。
.github/workflows/swift-ci.yml
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
name: Swift Package CI on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build-macos: runs-on: macos-14 # Apple Silicon (M1/M2) ランナー steps: - uses: actions/checkout@v4 - name: Install Swift via Homebrew run: | brew update brew install swift - name: Build (Release) run: swift build --configuration release - name: Test run: swift test build-windows: runs-on: windows-2022 steps: - uses: actions/checkout@v4 - name: Setup Swift uses: swift-actions/setup-swift@v1 with: swift-version: '6.4' - name: Build (Release) run: swift build --configuration release - name: Test run: swift test |
- ベストプラクティス:
swift test --parallelでテストを並列実行し、CI の実行時間を短縮 - セキュリティ:外部バイナリ(
binaryTarget)を使用する場合はchecksumが正しいか必ず確認してください
5‑3. 開発中に遭遇しやすいエラーと対処法(チェックリスト)
| エラー例 | 主な原因 | 推奨対策 |
|---|---|---|
swift: error: unable to find toolchain |
PATH に Swift バイナリが未登録 | macOS は brew --prefix swift、Windows は環境変数 Path に .../usr/bin を追加 |
Package dependency resolution failed |
依存パッケージのバージョン不整合またはネットワーク障害 | swift package clean → git fetch --tags → 再度 swift build。プロキシ環境下では HTTPS_PROXY を設定 |
The filename, directory name, or volume label syntax is incorrect. (Windows) |
パス長が 260 文字を超過 | プロジェクトルートを短いディレクトリ(例: C:\src\MyLib)に移動し、Git の core.longpaths true を設定 |
error: unable to find binary target 'FastMath' |
binaryTarget の URL / checksum が不正 |
URL と checksum を再取得し、swift package compute-checksum <file> で正しい値を生成 |
warning: unsafe flags are being used |
unsafeFlags が CI 環境で許可されていない |
CI 用に .when(configuration: .release) 条件分岐で除外、もしくはフラグ自体を削除 |
対処の流れ:エラーメッセージ →
swift --versionとツールチェーン確認 → パス・依存関係のリセット → 再ビルド。上記チェックリストに沿って順番に実施すると、ほとんどの障害は短時間で解決できます。
まとめと次のステップ
本稿の要点(章末集約)
- 推奨環境
- macOS Ventura/Sonoma + Xcode 15 系列、または Windows 11 + Swift 6 バイナリ(VS Code が実質的な IDE)
-
ディスク空き容量 50 GB 以上、管理者権限が必要
-
インストール手順
- Xcode は Apple Developer の
.xipから手動インストール -
Swift Toolchain は Homebrew(macOS)または ZIP 展開(Windows)で取得し PATH を設定
-
SPM パッケージ作成
swift package init --type libraryがベーステンプレート-
Package.swiftではplatforms,products,dependencies,targetsに加え、Swift 6 の新要素binaryTarget,plugin,unsafeFlagsを活用 -
ビルド・テスト
- macOS:Xcode UI → Add Package Dependency(ローカル/リモート)
- Windows:VS Code + Swift Extension で CLI ビルド/テストを実行
-
binaryTargetとpluginのサンプルコードを参考に、外部バイナリやビルド時拡張を組み込める -
Git 管理と CI
.gitignoreにビルド成果物を除外し、GitHub へプッシュ- GitHub Actions の macOS / Windows 両ランナーで
swift build・swift testを自動実行 - エラーは「ツールチェーン」「パス長」「依存解決」の三大カテゴリに分類して順次対処
次のステップ
| 目的 | 推奨アクション |
|---|---|
| 本番プロジェクトへの導入 | 既存リポジトリへ Package.swift を追加し、Xcode/VS Code で依存関係を組み込む |
| CI の拡張 | テストカバレッジ取得(swift test --enable-code-coverage)や Lint(SwiftFormat, SwiftLint)を同一ワークフローに追加 |
| 外部バイナリ活用 | binaryTarget を利用して大規模 C/C++ ライブラリ(例:OpenCV、FFmpeg)を配布し、ビルド時間短縮を検証 |
| プラグイン開発 | 独自コード生成プラグインを作成し、plugin 機能でテンプレート自動化を実装 |
参考情報・リンク
-
Apple Developer – Xcode ダウンロードページ
https://developer.apple.com/download/all/ -
Swift.org – リリース一覧とバイナリダウンロード
https://swift.org/download/#releases -
CocoaPods Official Documentation (2024 年版)
https://cocoapods.org/ -
Apple Swift Language Extension for VS Code (GitHub)
https://github.com/apple/swift-vscode-extension -
GitHub Actions – macOS・Windows ランナーのドキュメント
https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions -
swift-actions/setup-swiftAction (GitHub Marketplace)
https://github.com/swift-actions/setup-swift -
Swift Package Manager – Official Documentation (Swift 6)
https://docs.swift.org/package-manager/
以上が、最新の Swift 6 系列を macOS と Windows のローカル環境で安全かつ効率的に扱うための実践ガイドです。各手順を自分のプロジェクトに当てはめ、継続的インテグレーションまで整備すれば、チーム全体で安定した Swift 開発フローが確立できます。