Сборка Android: библиотеки и шаблоны — документация

Точные зависимости, ABI, SCons, упаковка Gradle и проверка полученных файлов.

Когда нужна сборка

Этот маршрут создаёт нативные Android-библиотеки и шаблоны вашей сборки Reckfell. Он нужен при изменении модулей, C++ или параметров сборки. Для обычной упаковки игры используйте экспорт Android; APK шаблона ещё не содержит вашу игру.

Команды выполняются из каталога Source, где лежит SConstruct. Редактор, SDK и шаблоны должны соответствовать одному набору исходников/модулей; номера 1.0.0 недостаточно для проверки такого соответствия.

Зависимости текущих исходников

Компонент	Значение в build-файлах
Python / SCons	Не ниже 3.9 / 4.4
JDK	Минимум 17; согласуйте JDK терминала и Gradle JDK в IDE
Android SDK	compileSdk 36, targetSdk 36, minSdk 24
Build Tools	36.1.0
NDK	29.0.14206865
Gradle wrapper / Android Gradle Plugin	8.14.5 / 8.13.2
Kotlin	2.1.21

Это версии данной сборки, не рекомендация заменить их новейшими. Установите SDK-пакеты через Android Studio SDK Manager, включая NDK Side by side точной версии. Если версия недоступна в вашем наборе репозиториев, разберите это до сборки; не подменяйте NDK произвольным. Установка NDK.

ANDROID_HOME должен указывать на корень SDK с каталогами platforms, build-tools, ndk, cmdline-tools, а не на сам cmdline-tools/bin. Если ANDROID_HOME отсутствует, код использует ANDROID_SDK_ROOT; заданный, но пустой ANDROID_HOME подавляет этот fallback. Отдельно проверьте JAVA_HOME, java -version и доступность scons из того терминала/IDE, где запускаете сборку.

При отсутствующем NDK конфигурация может вызвать cmdline-tools/latest/bin/sdkmanager (sdkmanager.bat на Windows) и скачать нужную версию. Это требует установленного инструмента, сети и принятых лицензий. Не рассчитывайте, что любой пустой каталог SDK автоматически подготовится целиком. can_build проверяет лишь существование пути, а не полноту SDK.

Сначала нативные библиотеки

Минимальный пример для ARM64, без .NET-модуля:

scons platform=android target=template_debug arch=arm64
scons platform=android target=template_release arch=arm64

Ожидаемые нативные файлы: platform/android/java/lib/libs/debug/arm64-v8a/libreckfell_android.so и соответствующий путь release. Они ещё не являются APK. В SCons используются arm32, arm64, x86_32, x86_64; в Android-пакете им соответствуют armeabi-v7a, arm64-v8a, x86, x86_64.

Для дополнительных ABI повторите оба target с нужным arch до упаковки. Наличие одного ARM64-файла не означает поддержку всех устройств. ndk_platform по умолчанию android-24; значение ниже минимума конфигурация повышает до 24. Это нативный API level, отдельный от compileSdk/targetSdk Gradle.

Затем упаковка Gradle

Из Source/platform/android/java используйте wrapper репозитория:

./gradlew generateReckfellTemplates

На Windows тот же шаг из PowerShell:

.\gradlew.bat generateReckfellTemplates

В этом CLI-маршруте task обычно использует ранее собранные .so, а не пересобирает C++ автоматически. Он обрабатывает доступные debug/release-каталоги; отсутствующий target может быть пропущен. Проверьте наличие обоих свежих bin/android_debug.apk, bin/android_release.apk и bin/android_source.zip. ZIP — Gradle-шаблон, не архив всей игры или исходников движка.

Альтернатива: generate_android_binaries=yes у последнего SCons-вызова запускает Gradle после нативной стадии. Не ставьте его на каждый ABI без необходимости. Текущий Python-обёртчик вызывает Gradle без check=True; успешный код SCons не заменяет проверку Gradle-журнала и выходных файлов. При сомнении выполните упаковку wrapper-ом отдельно и проверьте его код возврата.

C#, редактор и символы

module_mono_enabled=yes — отдельный вариант нативной сборки, для него упаковщик выбирает generateReckfellMonoTemplates. Он не превращает стандартный APK в .NET-шаблон. Нужны также согласованные managed assemblies/SDK и успешная публикация C#-проекта; приведённые выше две команды этого не проверяют.

target=editor собирает Android-редактор, а не игровой шаблон. Его библиотеки идут в lib/libs/tools/<debug-or-release>/<ABI>, пакетные результаты — в bin/android_editor_builds. Не подменяйте ими android_debug.apk/android_release.apk. Автоупаковщик editor-ветки вызывает также задачи редакторов для XR-дистрибутивов; это не доказательство их установки или запуска.

Для нативной отладки используйте debug_symbols=yes; separate_debug_symbols=yes отделяет символы от распространяемого бинарника. Debug-target, наличие символов и dev_build=yes — разные настройки. Сохраняйте символы вместе с идентичностью конкретной .so, иначе LLDB может показывать неверные строки. Работа в Android Studio.

Если результат не получен

Признак	Что проверить
Android не определяется	Непустой SDK root и существование пути; затем наличие конкретных пакетов.
NDK не найден	Версию 29.0.14206865, расположение `ndk/<version>` и доступность ожидаемого sdkmanager.
Gradle не запускается	Wrapper, Java 17+, сеть/репозитории и Gradle-журнал; не откатывайте jarsigner на JDK 8.
Получен только один APK	Наличие native debug/release для нужных ABI; task может пропускать отсутствующие библиотеки.
Библиотека не загружается	ABI устройства/пакета, JNI-путь `.so`, зависимости и журнал запуска. Установка APK не доказывает запуск.

Не начинайте диагностику с gradlew clean: task удаляет в том числе сгенерированные native libraries и пакеты. Сначала сохраните нужные результаты и найдите ошибочную стадию.

Граница проверки: версии, выбор ABI, SDK-пути, диспетчер упаковки и Gradle tasks сверены по исходникам. Функции выбора SDK/NDK и команды упаковщика проверены изолированно с подставными путями и процессами, без загрузок. Настоящие SCons/Gradle, сборка APK, .NET-публикация, установка и рендер Android здесь не выполнялись; движок не менялся.