資料一覧へ
xtool

Linux・Windows・macOS で iOS アプリをビルドして実機に入れる

Cross-platform Xcode replacement / xtool-org/xtool

1 — 概要

SwiftPM / Cross-platform

xtool は、Xcode のビルド・署名・実機インストールを置き換える CLI です。SwiftPM パッケージを iOS アプリ（.app / .ipa）に組み立て、Apple Developer Services で証明書とプロビジョニングプロファイルを用意し、USB で接続した iPhone へインストールします。

CLI は Linux、WSL、macOS で動きます。Linux と WSL では、Apple が配布する Xcode.xip から iOS 用の Swift SDK を生成して使います。macOS ではインストール済みの Xcode の SDK を使いますが、Xcode のビルドシステムは使いません。

Package.swift + xtool.ymlswift build（Darwin SDK）.app に梱包プロビジョニング + 署名USB で実機へ
3
対応 OS（Linux / WSL / macOS）
6.4
Linux で使う Swift
2
ログイン方式
MIT
ライセンス

言語: Swift 6（strict concurrency）· 配布: Linux は AppImage、macOS は Homebrew または xtool.app · 作者: Kabir Oberai

2 — モジュール構成

リポジトリは 1 つの Swift Package です。CLI 本体とは別に、署名や実機操作を担う XKit をライブラリとして公開しています。

ターゲット役割
xtool / XToolSupportCLI の入口とサブコマンド（setup、dev、sdk、auth など）
PackLibxtool.yml の読み込み、SwiftPM の依存グラフからの梱包計画（Planner）、.app の組み立て（Packer）、Xcode プロジェクト生成
XKitApple Developer Services への認証（GrandSlam / API キー）、証明書・App ID・プロファイルの発行、署名、実機へのインストール。iOS でも動く
DeveloperAPIApp Store Connect API の OpenAPI 定義から生成したクライアント
XcodeProjectsxtool dev generate-xcode-project 用の .xcodeproj 書き出し

自作アプリから XKit を使う場合は、SwiftPM の依存に追加します。

// package dependency:
.package(url: "https://github.com/xtool-org/xtool", .upToNextMinor(from: "1.2.0"))
// target dependency:
.product(name: "XKit", package: "xtool")

3 — xtool dev の流れ

xtool dev は xtool dev run の省略形です。パッケージのルートで実行すると、ビルドから起動可能な状態までを 1 回で進めます。

01 / Plan

梱包計画を作る

Package.swift と xtool.yml を読み、アプリ本体と App Extension に対応するライブラリ製品、リソース、Info.plist、entitlements を決めます。xtool.yml がなければ com.example を組織 ID として続行します。

02 / Build

SwiftPM でビルド

ターゲット arm64-apple-ios で SwiftPM がビルドし、Packer が xtool/<App>.app を組み立てます。初回は iOS SDK のモジュールをビルドするため数分かかります。

03 / Install

署名して実機へ

デバイスを Apple ID に登録し、証明書・App ID・プロファイルを用意して署名し、インストールします。進捗は Provisioning、Signing、Installing などの段階で表示されます。

Hello$ xtool dev
Planning...
Building for debugging...
Build of product 'Hello-App' complete! (4.94s)
Waiting for device to be connected...
Installing to device: Kabir's iPhone (udid: *****)

[Unpacking app] 100%
[Logging in] 100%
[Preparing device] 100%
[Provisioning] 100%
[Signing] 100%
[Packaging] 100%
[Connecting] 100%
[Installing] 100%
[Verifying] 100%
macOS ではシミュレーターも使えます。 xtool dev run --simulator で arm64-apple-ios-simulator 向けにビルドし、iOS Simulator へインストールします。この場合はログインもデバイス接続も不要です。

4 — インストール

項目Linux / WSLmacOS
SwiftSwift 6.4 ツールチェーン（swift.org から）Xcode 同梱の Swift
iOS SDKXcode.xip（Xcode 27）から xtool setup が生成インストール済み Xcode の SDK
デバイス接続usbmuxd。WSL は USBIPD で USB をパススルーOS 標準
xtool 本体GitHub Release の xtool-<arch>.AppImagebrew install xtool-org/tap/xtool または xtool.app

Linux の手順

# 前提: Swift 6.4 と usbmuxd を入れ、Xcode.xip をブラウザーでダウンロードしておく
swift --version
sudo apt-get install usbmuxd

# xtool を PATH に置く
curl -fL \
  "https://github.com/xtool-org/xtool/releases/latest/download/xtool-$(uname -m).AppImage" \
  -o xtool
chmod +x xtool
sudo mv xtool /usr/local/bin/

# ログインと SDK の生成
xtool setup
swift sdk list   # darwin が表示されれば完了

xtool setup のログイン方式

方式条件仕組み
API Key（推奨）有料の Apple Developer Program公開 API の App Store Connect API。App Manager ロールの Team Key を発行して入力する
Password任意の Apple ID（無料アカウント可）メールアドレス・パスワード・2FA で Apple の非公開 API に認証する
Xcode.xip は手動でダウンロードします。 ダウンロードページは Apple ID でのログインとライセンス同意が必要なため、curl では取得できません。xtool setup でファイルのパスを入力すると、展開して Darwin 用の Swift SDK をインストールします。SDK は後から xtool sdk で更新・削除できます。

5 — 最初のアプリ

  1. xtool new Hello でテンプレートを作ります。Package.swift、xtool.yml、.bsp/xtool.json、SwiftUI の HelloApp.swift と ContentView.swift が生成されます。
  2. iPhone を USB で接続し、Hello ディレクトリで xtool dev を実行します。
  3. iPhone に「このコンピュータを信頼しますか」が出たら 信頼 を選びます。直後にエラーで止まった場合は xtool dev を再実行します。
  4. デベロッパモードを求められたら、iPhone の設定で有効にして再実行します。
  5. 初回起動で「信頼されていないデベロッパ」と出たら、設定 > 一般 > VPN とデバイス管理 で自分の Apple ID を信頼します。
Developer$ xtool new Hello
Creating package: Hello
Creating Package.swift
Creating xtool.yml
Creating .gitignore
Creating .bsp/xtool.json
Creating Sources/Hello/HelloApp.swift
Creating Sources/Hello/ContentView.swift
エディターの補完は SourceKit-LSP で動きます。 .bsp/xtool.json は Build Server Protocol 経由で xtool にビルド情報を問い合わせる設定です。VS Code なら Swift 拡張を入れれば、iOS SDK の型にもホバーで説明が出ます。コードを直したら xtool dev を再実行します。2 回目以降はキャッシュが効きます。

6 — xtool.yml の設定

SwiftPM のライブラリをどう iOS アプリに梱包するかを書くファイルです。version: 1 と、bundleID または orgID のどちらかが必須です。

キー内容
bundleID / orgIDバンドル ID。orgID の場合は <orgID>.<製品名> になる
productアプリ本体にするライブラリ製品。製品が複数あるときに指定する
infoPath追加・上書きしたいキーだけを書いた Info.plist。自動生成の内容にマージされる
entitlementsPathentitlements の plist
iconPathアプリアイコン。PNG のみ
resourcesアプリバンドル直下に置くファイル。通常のリソースは SwiftPM の resources: で足りる
extensionsApp Extension の一覧。各項目に product と infoPath が必須
skipLSP.bsp/xtool.json の自動作成を止める

ウィジェットを足す例

Package.swift に HelloWidget ライブラリを追加したうえで、アプリ本体と拡張を区別します。

version: 1
bundleID: com.example.Hello
product: Hello
extensions:
  - product: HelloWidget
    infoPath: HelloWidget-Info.plist

7 — コマンド一覧

区分コマンド内容
設定setupログインと SDK の準備をまとめて行う
設定auth login / logout / statusApple Developer Services の認証
設定sdk build / install / update / remove / statusDarwin Swift SDK の管理
開発newテンプレートからプロジェクトを作る
開発dev（= dev run）ビルドして実機またはシミュレーターで実行
開発dev build [--sign] [--ipa]ビルドのみ。--sign で署名、--ipa で .ipa を出力
開発dev generate-xcode-projectmacOS で Xcode を使いたいときの .xcodeproj を生成
開発ds teams / devices / identifiers / certificates / profilesDeveloper Services 上の資源を一覧する
デバイスdevices / install / uninstall / launch接続中デバイスの一覧、.ipa のインストール、削除、起動

8 — 制約と注意

  • Password 方式は Apple の非公開 API を使います。 公式ドキュメントは、慎重を期すなら使い捨ての Apple ID を作ることを勧めています。認証情報の送信先は Apple だけです。
  • 実機に入れるとバンドル ID に接頭辞が付きます。 例: XTL-1234.com.example.Hello。無料アカウント同士で同じバンドル ID を使えないため、共有時の衝突を避ける措置です。
  • Linux でも Xcode.xip が必要です。 iOS SDK は Apple の Xcode から生成するため、Apple ID でのダウンロードとライセンス同意は避けられません。
  • WSL では USB 接続の設定が要ります。 USBIPD でデバイスを WSL にバインドします。AFCClient.Error.muxError が出る場合は、Windows 側の iTunes 経由で接続を中継する方法が issue #19 で案内されています。
  • macOS で手動インストールした場合は自動更新されません。 新しいリリースは自分で確認して入れ替えます。Homebrew なら brew upgrade で更新できます。