Сборка

Итоговый 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	последняя	Кросс-компиляция Rust для Android

Точка входа в сборку — скрипт kotlin в корне репозитория (kotlin.bat в Windows). При первом запуске он сам скачивает нужный Kotlin Toolchain, поэтому Kotlin и Gradle устанавливать вручную не требуется. Минимальная поддерживаемая версия Android — 13 (API 33), поддерживается только 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

Установите Go 1.27 от MetaCubeX (эта версия используется в CI) и инструментарий Rust nightly. Рекомендуется отдельный Go SDK, так как следующий шаг изменяет его GOROOT:

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`	Загрузчик payload APK `libloader.so`
`--shell`	Только PIE-ланчеры mihomo и предпросмотра
`--geo`	Скачивает и сжимает Geo-данные
`--clean`	Удаляет артефакты сборки

ABI по умолчанию берётся из abi.app.list в kernel.properties; его можно задать и явно через переменную окружения:

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`	PIE-ланчер mihomo
`libmihomocore.so`	Общее ядро mihomo на Go
`libpreview.so`	Предпросмотр конфигурации
`liboverride.so`	Компиляция переопределений
`libcompat.so`	Мост обмена с ядром
`libloader.so`	Загрузчик нативного payload 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 и упаковывает payload; сначала выполните настройку подписи ниже:

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 вместе с одноимённым .apk.json, где хранятся версия, SHA-256 и прочие данные сборки.

Вариант	Флаг	Описание
`external`	`-Pgeo.bundle=false`	Без встроенного Geo, меньше размер; 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
Подготовка релиза	Вычисление версии, 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 отсутствует или версия не совпадает	Установите 30.0.16248370, как указано в `kernel.properties`.
Нет 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` и проверьте наличие всех трёх XZ-файлов.
Сбой подписи Release или APK не устанавливается	Проверьте четыре ключа в `signing.properties` и keystore; переустановка требует того же сертификата.
Компиляция прошла, но итогового APK нет	Уберите `--compile-only`, используйте точку входа `packaging` и проверьте ошибки валидации.
ABI не поддерживается	Поддерживается только `arm64-v8a`.

Другие ошибки сборки описаны в FAQ.

Начало

Руководства

Переопределения

Другое

Требования

Подготовка репозитория

Сборка нативных компонентов

Полная сборка

Сборка по компонентам

Артефакты сборки

Сборка APK

Debug

Release

Подпись

Сборка в CI

Проверка установки

Частые проблемы

​Требования

​Подготовка репозитория

​Сборка нативных компонентов

​Полная сборка

​Сборка по компонентам

​Артефакты сборки

​Сборка APK

​Debug

​Release

​Подпись

​Сборка в CI

​Проверка установки

​Частые проблемы

Требования

Подготовка репозитория

Сборка нативных компонентов

Полная сборка

Сборка по компонентам

Артефакты сборки

Сборка APK

Debug

Release

Подпись

Сборка в CI

Проверка установки

Частые проблемы