ビルド

リリース APK は必ず packaging エントリーポイントでビルドしてください。初回ビルドの前に、ネイティブコンポーネントの準備を完了してください。

必要環境

ツール	バージョン	用途
OpenJDK	25	ビルドツールチェーンの実行
Android SDK	API 37、build-tools 37.0.0	コンパイル、パッケージング、署名
Android NDK	30.0.16248370	ネイティブコンポーネントのビルド
CMake、Ninja	SDK の CMake 3.22.1 または PATH 上のもの	C/C++ のビルド
Python	3.10 以上	ビルドスクリプトの実行
Go	1.27（MetaCubeX/go）	mihomo コアのビルド
Rust	nightly、rust-src	設定コンパイラのビルド
cargo-ndk	最新	Android 向け Rust のクロスコンパイル

ビルドの入り口はリポジトリルートの kotlin スクリプト（Windows は kotlin.bat）です。初回実行時に必要な Kotlin Toolchain を自動的にダウンロードするため、Kotlin や Gradle を手動でインストールする必要はありません。サポートする最低 Android バージョンは 13（API 33）、対応 ABI は arm64-v8a のみです。NDK バージョン、最小 SDK、ABI は kernel.properties から読み込まれます。

リポジトリの準備

ソースの取得

git clone --recurse-submodules https://github.com/YumeYucca/YumeBox.git
cd YumeBox

Android SDK の設定

API 37、build-tools 37.0.0、NDK 30.0.16248370、CMake 3.22.1、Ninja をインストールし、SDK ライセンスに同意してください。ANDROID_HOME を SDK に向けるか、リポジトリルートに local.properties を作成します：

sdk.dir=C:/Android/Sdk

ANDROID_HOME、ANDROID_SDK_ROOT、sdk.dir はすべて同じ SDK を指す必要があります。

Go と Rust の準備

MetaCubeX が管理する Go 1.27（CI と同じバージョン）と Rust nightly ツールチェーンをインストールします。次のステップで GOROOT を変更するため、専用の Go SDK を推奨します：

rustup toolchain install nightly --component rust-src
rustup target add --toolchain nightly aarch64-linux-android
cargo install cargo-ndk

Go コアをビルドする前に、.github/patch/ のパッチを go env GOROOT の示すディレクトリへ適用します。CI はネイティブビルドの前に自動で実行します。以下のコマンドは Linux、macOS、Git Bash で利用できます：

project_root="$PWD"
go_root="$(go env GOROOT)"
for patch_file in "$project_root"/.github/patch/*.patch; do
  if (cd "$go_root" && patch --forward --dry-run -p 1 < "$patch_file") >/dev/null 2>&1; then
    (cd "$go_root" && patch --forward -p 1 < "$patch_file")
  elif (cd "$go_root" && patch --reverse --dry-run -p 1 < "$patch_file") >/dev/null 2>&1; then
    echo "適用済み: $patch_file"
  else
    echo "適用できません: $patch_file" >&2
    exit 1
  fi
done

mihomo カーネルの同期

既定では Alpha ブランチを同期します。Meta も利用できます：

python scripts/sync_kernel.py alpha
python scripts/sync_kernel.py meta

ネイティブコンポーネントのビルド

完全ビルド

python scripts/native-build.py --all

すべてのネイティブライブラリを生成し、Geo データをダウンロードします。

コンポーネント単位のビルド

引数	効果
`--go`	mihomo 共有コア、プレビューライブラリ、PIE ランチャー
`--rust`	設定コンパイラ `liboverride.so`
`--compat`	コア間通信ブリッジ `libcompat.so`
`--loader`	APK ペイロードローダー `libloader.so`
`--shell`	mihomo とプレビューの PIE ランチャーのみ
`--geo`	Geo データのダウンロードと圧縮
`--clean`	ビルド成果物の削除

既定の ABI は kernel.properties の abi.app.list から取得されます。環境変数で明示的に指定することもできます：

ABI_APP_LIST=arm64-v8a python scripts/native-build.py --go --rust --compat --loader

$env:ABI_APP_LIST = "arm64-v8a"
python scripts/native-build.py --go --rust --compat --loader

ビルド成果物

jniLibs/arm64-v8a/ のネイティブライブラリ：

ファイル	用途
`libmihomo.so`	mihomo PIE ランチャー
`libmihomocore.so`	mihomo Go 共有コア
`libpreview.so`	設定プレビュー
`liboverride.so`	オーバーライドコンパイル
`libcompat.so`	コア間通信ブリッジ
`libloader.so`	APK ネイティブペイロードローダー
`core-version.properties`	カーネルのブランチ、コミット、ビルド情報

Geo データは build/generated/assets/geo/ に配置されます：

geoip.metadb.xz
geosite.dat.xz
ASN.mmdb.xz

APK のビルド

ビルドコマンドは kotlin run -m packaging です。すべての -Pkey=value 引数は -- の後に置き、packaging エントリへ渡します。PowerShell ではドットを含む引数を単一引用符で囲みます。

Debug

Debug はローカルでのインストールと検証向けで、既定では Geo を同梱しません：

sh kotlin run -m packaging -- --build-type=debug
sh kotlin run -m packaging -- --build-type=debug -Pgeo.bundle=true

.\kotlin.bat run -m packaging -- --build-type=debug
.\kotlin.bat run -m packaging -- --build-type=debug '-Pgeo.bundle=true'

Release

Release は loader DEX をビルドしてペイロードを梱包します。先に後述の署名設定を済ませてください：

sh kotlin run -m packaging -- --build-type=release -Pgeo.bundle=false
sh kotlin run -m packaging -- --build-type=release -Pgeo.bundle=true

.\kotlin.bat run -m packaging -- --build-type=release '-Pgeo.bundle=false'
.\kotlin.bat run -m packaging -- --build-type=release '-Pgeo.bundle=true'

検証に合格した APK は output_apk/debug/ と output_apk/release/ に YumeBox-external.apk または YumeBox-builtin.apk として出力され、バージョンや SHA-256 などのビルド情報を記録した同名の .apk.json が生成されます。

バリアント	引数	説明
`external`	`-Pgeo.bundle=false`	Geo を同梱しないため小型。初回起動時にダウンロード
`builtin`	`-Pgeo.bundle=true`	Geo を同梱しオフライン向け。ビルド前に `python scripts/native-build.py --geo` を実行

署名

署名を設定しない場合、Debug は標準の debug keystore を自動生成して使用します。リポジトリルートに signing.properties が存在する場合は、Debug と Release の両方でそれが優先されます。Release は署名が必須です。リポジトリルートに release.keystore を置き、signing.properties を作成してください：

keystore.path=release.keystore
keystore.password=<keystore-password>
key.alias=yumebox
key.password=<key-password>

キー	説明
`keystore.path`	keystore のパス。リポジトリルート相対または絶対パス
`keystore.password`	keystore のパスワード
`key.alias`	署名鍵のエイリアス
`key.password`	鍵のパスワード

release.keystore と signing.properties はコミットしないでください。

未署名 APK は --allow-unsigned を明示的に指定し、かつ signing.properties がない場合にのみ生成されます。未署名 APK は adb install でインストールできず、CI もこのオプションを使用しません。

CI ビルド

すべての CI ジョブは macos-26 で実行され、arm64-v8a のみをビルドします：

段階	作業	結果
並列準備	Toolchain の事前コンパイル、ネイティブビルド、Geo ダウンロードを並列実行	コンパイルキャッシュとネイティブ成果物
並列 APK パッケージング	`builtin` / `external` のパッケージング、署名、検証	検証済み Release APK 2 本
リリース準備	バージョン計算、SHA-256 と更新メタデータの生成	リリースディレクトリと更新情報
Release 公開	APK とメタデータのアップロード	GitHub Release

CI はコミット数をビルドバージョン番号として使用し、コミットハッシュとブランチ情報を埋め込みます。

インストールの確認

adb install -r output_apk/debug/YumeBox-external.apk

ファイル名が異なる場合は、先に output_apk/debug/ の実際の成果物を確認してください。

よくある問題

症状	対処
`jniLibs/arm64-v8a` に `.so` がない	先に `python scripts/native-build.py --all` を実行する。
SDK が見つからない、または SDK の不一致	`ANDROID_HOME`、`ANDROID_SDK_ROOT`、`local.properties` を確認し、API 37 / build-tools 37.0.0 をインストールしてライセンスに同意する。
NDK がない、またはバージョン不一致	`kernel.properties` が指定する 30.0.16248370 をインストールする。
CMake または Ninja がない	SDK の CMake 3.22.1 をインストールするか、PATH に用意する。
`cargo-ndk` や Rust target がない	nightly、`rust-src`、`aarch64-linux-android`、`cargo-ndk` をインストールする。
Go パッチを適用できない	MetaCubeX/go 1.27 を確認し、パッチ適用済みかどうか確認する。必要なら専用 Go SDK を使う。
`builtin` に Geo ファイルがない	先に `python scripts/native-build.py --geo` を実行し、3 つの XZ ファイルが揃っているか確認する。
Release の署名失敗、インストール不可	`signing.properties` の 4 キーと keystore を確認する。上書きインストールは同じ証明書を使う。
コンパイル成功なのに APK が出力されない	`--compile-only` を外し、`packaging` エントリで検証エラーを確認する。
ABI が非対応	現在は `arm64-v8a` のみ対応。

その他のビルドエラーは FAQ を参照してください。

はじめに

ガイド

オーバーライド

その他

必要環境

リポジトリの準備

ネイティブコンポーネントのビルド

完全ビルド

コンポーネント単位のビルド

ビルド成果物

APK のビルド

Debug

Release

署名

CI ビルド

インストールの確認

よくある問題

​必要環境

​リポジトリの準備

​ネイティブ コンポーネントのビルド

​完全ビルド

​コンポーネント単位のビルド

​ビルド成果物

​APK のビルド

​Debug

​Release

​署名

​CI ビルド

​インストールの確認

​よくある問題

必要環境

リポジトリの準備

ネイティブコンポーネントのビルド

完全ビルド

コンポーネント単位のビルド

ビルド成果物

APK のビルド

Debug

Release

署名

CI ビルド

インストールの確認

よくある問題