build

Only running Gradle will not generate the missing jniLibs; please complete the native build first when building for the first time.

Environmental requirements

Tools	Version	Purpose
OpenJDK	24	Gradle and Android Compilation
Android SDK	API 37	Compilation and Target Platform
Android NDK	30.0.14904198	Go, Rust, C/C++ native builds
CMake	3.22.1	Building C/C++ components
Python	3.10 or higher	Execute build script
Go	1.26	Building mihomo core
Rust	nightly	Build configuration compiler
cargo-ndk	Latest version	Compiling Rust for Android
Git, patch	Available	Synchronize kernel and application Go patches

The current application only builds arm64-v8a, and the corresponding Rust target is aarch64-linux-android.

Prepare warehouse

Get source code

git clone https://github.com/YumeYucca/YumeBox.git
cd YumeBox

Configure Android SDK

Install API 37, NDK 30.0.14904198 and CMake 3.22.1, then create local.properties in the root directory of the repository:

sdk.dir=C:/Android/Sdk

NDK will automatically locate according to android.ndkVersion in gradle.properties.

Preparing for Go and Rust

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

Before building the Go core, you also need to apply the patches in .github/patch/ to go env GOROOT. CI automatically performs this step before building the native component.Execute in Git Bash or WSL:

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

Sync mihomo

Select a kernel channel. Alpha is used by default:

python scripts/sync_kernel.py alpha

You can also use Meta:

python scripts/sync_kernel.py meta

Build native components

Complete build

A full build will generate all native libraries and download Geo data:

python scripts/native-build.py --all

###Build by components

Parameters	Output or function
`--go`	mihomo shared core, preview library and PIE startup shell
`--rust`	Rust configuration compiler `liboverride.so`
`--compat`	Core process communication bridge `libcompat.so`
`--loader`	APK payload loader `libloader.so`
`--shell`	Only build mihomo PIE startup shell
`--geo`	Download and compress Geo data with BundleMRS
`--clean`	Clean native, Geo and version tags

Native debugging builds only the current ABI:

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

After a successful build, jniLibs/arm64-v8a/ should contain:

Documentation	Purpose
`libmihomo.so`	mihomo PIE startup shell
`libmihomocore.so`	mihomo Go shared core
`libpreview.so`	Configuration Preview
`liboverride.so`	Override compilation
`libcompat.so`	Core Communication Bridge
`libloader.so`	APK native payload loading
`core-version.properties`	Kernel branches, commits and build information

Geo data is located at build/generated/assets/geo/:

geoip.metadb.xz
geosite.dat.xz
ASN.mmdb.xz
BundleMRS.7z

Build APK

###Debug Debug is suitable for local installation and debugging:

./gradlew :app:assembleDebug
./gradlew -Pgeo.bundle=true :app:assembleDebug

.\gradlew.bat :app:assembleDebug
.\gradlew.bat -Pgeo.bundle=true :app:assembleDebug

Release

Release enables compression and resource shrinking:

./gradlew -Pgeo.bundle=false :app:assembleRelease
./gradlew -Pgeo.bundle=true :app:assembleRelease

.\gradlew.bat -Pgeo.bundle=false :app:assembleRelease
.\gradlew.bat -Pgeo.bundle=true :app:assembleRelease

Geo data variants

Variation	Content	Applicable scenarios
`external`	No built-in Geo data	Smaller size, need to download for first startup
`builtin`	Built-in Geo data	First time installation or offline use

Both variants use the same application code and kernel; the only difference is whether the Geo resources are packaged into the APK. APK outputs to:

app/build/outputs/apk/debug/
app/build/outputs/apk/release/

Local builds usually generate YumeBox-external.apk or YumeBox-builtin.apk. The actual file name is based on the output directory.

Release signature

Local verification does not need to be configured with a formal signature; publishing APK requires release.keystore and signing.properties in the warehouse root directory:

keystore.password=你的仓库密码
key.alias=yumebox
key.password=你的密钥密码

Field	Description
`keystore.password`	keystore password
`key.alias`	Signing key alias
`key.password`	Signing key password

Do not submit release.keystore or signing.properties.

CI build

Stage	Main work	Results
Native build	Sync kernel, build Go, Rust, C/C++ and loader	`native-*` build artifacts
APK build	Download the native product, packaged `builtin` and `external` respectively	Two Release APKs
Release preparation	Compute version, generate SHA-256 and metadata	Release directory and update information
Release	Upload APK and metadata	GitHub Release

CI uses arm64-v8a and writes build version information via build.number, build.hash, and build.branch.

Verify installation

adb install -r app/build/outputs/apk/debug/YumeBox-external.apk

If the file names are different, first look at the actual product in app/build/outputs/apk/.

FAQ

Phenomenon	Treatment
`jniLibs/arm64-v8a` is missing `.so`	Run `python scripts/native-build.py --all` first.
Android SDK not found	Check `local.properties` or `ANDROID_SDK_ROOT`.
NDK not found	Install `30.0.14904198`, do not use other versions instead.
`cargo-ndk` or Rust target is missing	Reinstall nightly, `rust-src`, and `aarch64-linux-android`.
Go patch cannot be applied	Check whether the patch has been applied, or use the dedicated Go SDK instead.
`builtin` Missing Geo file	Run `python scripts/native-build.py --geo` first.
ABI not supported	Current project only supports `arm64-v8a`.

For more build errors, please see FAQ.

Start here

Guides

Overrides

More

Environmental requirements

Prepare warehouse

Build native components

Complete build

Build APK

Release

Geo data variants

Release signature

CI build

Verify installation

FAQ

​Environmental requirements

​Prepare warehouse

​Build native components

​Complete build

​Build APK

​Release

​Geo data variants

​Release signature

​CI build

​Verify installation

​FAQ

Environmental requirements

Prepare warehouse

Build native components

Complete build

Build APK

Release

Geo data variants

Release signature

CI build

Verify installation

FAQ