> ## Documentation Index
> Fetch the complete documentation index at: https://yumebox.yumeyuka.moe/llms.txt
> Use this file to discover all available pages before exploring further.

# build

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

<Frame>
  <img src="https://mintcdn.com/yumebox/37Z_Xsb-cHWca0U0/images/diagrams/yumebox-build-pipeline.svg?fit=max&auto=format&n=37Z_Xsb-cHWca0U0&q=85&s=8a2f6f0bc23529600e99481d11c36880" alt="YumeBox local and CI build link" noZoom={true} width="937" height="895" data-path="images/diagrams/yumebox-build-pipeline.svg" />
</Frame>

## 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

<Steps>
  <Step title="Get source code">
    ```bash theme={null}
    git clone https://github.com/YumeYucca/YumeBox.git
    cd YumeBox
    ```
  </Step>

  <Step title="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:

    ```properties theme={null}
    sdk.dir=C:/Android/Sdk
    ```

    NDK will automatically locate according to `android.ndkVersion` in `gradle.properties`.
  </Step>

  <Step title="Preparing for Go and Rust">
    ```bash theme={null}
    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:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Sync mihomo">
    Select a kernel channel. Alpha is used by default:

    ```bash theme={null}
    python scripts/sync_kernel.py alpha
    ```

    You can also use Meta:

    ```bash theme={null}
    python scripts/sync_kernel.py meta
    ```
  </Step>
</Steps>

## Build native components

### Complete build

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

```bash theme={null}
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:

<CodeGroup>
  ```bash Linux / macOS / Git Bash theme={null}
  ABI_APP_LIST=arm64-v8a python scripts/native-build.py --go --rust --compat --loader
  ```

  ```powershell Windows PowerShell theme={null}
  $env:ABI_APP_LIST = "arm64-v8a"
  python scripts/native-build.py --go --rust --compat --loader
  ```
</CodeGroup>

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/`:

```text theme={null}
geoip.metadb.xz
geosite.dat.xz
ASN.mmdb.xz
BundleMRS.7z
```

## Build APK

\###Debug

Debug is suitable for local installation and debugging:

<CodeGroup>
  ```bash Linux / macOS theme={null}
  ./gradlew :app:assembleDebug
  ./gradlew -Pgeo.bundle=true :app:assembleDebug
  ```

  ```powershell Windows theme={null}
  .\gradlew.bat :app:assembleDebug
  .\gradlew.bat -Pgeo.bundle=true :app:assembleDebug
  ```
</CodeGroup>

### Release

Release enables compression and resource shrinking:

<CodeGroup>
  ```bash Linux / macOS theme={null}
  ./gradlew -Pgeo.bundle=false :app:assembleRelease
  ./gradlew -Pgeo.bundle=true :app:assembleRelease
  ```

  ```powershell Windows theme={null}
  .\gradlew.bat -Pgeo.bundle=false :app:assembleRelease
  .\gradlew.bat -Pgeo.bundle=true :app:assembleRelease
  ```
</CodeGroup>

### 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:

```text theme={null}
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:

```properties theme={null}
keystore.password=你的仓库密码
key.alias=yumebox
key.password=你的密钥密码
```

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

<Info> Do not submit `release.keystore` or `signing.properties`. </Info>

## 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

```bash theme={null}
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](./faq).