Компиляция для Android

См. также

Эта страница описывает, как скомпилировать "шаблон экспорта" Android из исходных файлов. Если вы хотите экспортировать свой проект в Android, читайте Экспортирование для ОС Android.

Примечание

В большинстве случаев достаточно использовать встроенный шаблоны экспорта. Компиляция Android APK вручную полезна в основном для пользовательских сборок.

Кроме того, перед тем как приступить к созданию шаблона экспорта, необходимо выполнить шаги, описанные в руководстве Экспортирование для ОС Android.

Требования

Для компиляции на системах Windows, Linux или macOS необходимо следующее:

  • Python 3.8+.

  • SCons 4.0+ система сборки.

  • Android SDK

    • To install the Android SDK, follow the steps here <https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_android.html>_.

    • В Linux не используйте Android SDK, предоставленный в репозиториях вашего дистрибутива, так как он часто устаревает.

    • На macOS не используйте Android SDK, предоставленный Homebrew, так как он не будет установлен в едином месте.

  • Gradle (будет загружен и установлен автоматически, если отсутствует).

  • JDK 17 (либо OpenJDK, либо Oracle JDK).

    • You can download a build from Adoptium.

См. также

Чтобы получить исходный код Godot для компиляции, см. Получение исходного кода.

Для общего обзора использования SCons в Godot, смотрите Введение в систему сборки.

Настройка билда

  • Установите переменную окружения ANDROID_HOME так, чтобы она указывала на Android SDK. Если вы скачали инструменты командной строки Android, это будет папка, в которую вы извлекли содержимое ZIP-архива.

    • Windows: Нажмите Windows + R, введите "control system", затем нажмите Advanced system settings (Дополнительные параметры системы) на левой панели, затем нажмите Environment variables (Переменные среды) в появившемся окне.

    • Linux или macOS: Добавьте текст export ANDROID_HOME="/path/to/android-sdk" в файл .bashrc или .zshrc, где /path/to/android-sdk указывает на корень каталогов SDK.

  • После настройки SDK и переменных окружения обязательно перезапустите терминал, чтобы изменения вступили в силу. Если вы используете IDE со встроенным терминалом, перезапустите IDE.

  • Выполните команду scons platform=android. Если это не поможет, вернитесь назад и проверьте шаги. Если настройка выполнена правильно, начнётся загрузка NDK. Если вы пытаетесь скомпилировать GDExtension, сначала необходимо скомпилировать движок для загрузки NDK, а затем можно скомпилировать GDExtension.

Создание шаблонов экспорта

Godot требуются три шаблона экспорта для Android: оптимизированный шаблон "релиза" (android_release.apk), шаблон отладки (android_debug.apk) и шаблон сборки Gradle (android_source.zip). Поскольку с августа 2019 года Google требует, чтобы все APK-файлы включали библиотеки ARMv8 (64-разрядные), команды ниже собирают шаблоны, содержащие библиотеки как ARMv7, так и ARMv8.

Компиляция стандартных шаблонов экспорта выполняется путем вызова SCons из корневого каталога Godot со следующими аргументами:

  • Release template (используется при экспорте с отключенным параметром Debugging Enabled (Отладка включена))

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes

  • Debug template (используется при экспорте с установленным флажком Debugging Enabled (Отладка включена))

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes

  • (Необязательно) Dev template (используется при устранении неполадок)

scons platform=android target=template_debug arch=arm32 dev_build=yes
scons platform=android target=template_debug arch=arm64 dev_build=yes generate_android_binaries=yes

Полученные шаблоны будут расположены в каталоге bin:

  • bin/android_release.apk для шаблона релиза

  • bin/android_debug.apk для шаблона отладки

  • bin/android_dev.apk для шаблона dev

  • bin/android_source.zip для шаблона сборки Gradle

Примечание

  • Если вы изменяете список собираемых архитектур, не забудьте добавить generate_android_binaries=yes к последней собираемой архитектуре, чтобы файлы шаблонов были сгенерированы после сборки.

  • Чтобы включить отладочные символы в сгенерированные шаблоны, добавьте параметры debug_symbols=yes к команде SCons.

    • Обратите внимание, что вы можете включить separate_debug_symbols=yes для генерации отладочных символов в отдельном файле *-native-debug-symbols.zip.

См. также

Если вам нужно включить слои валидации (validation layers) Vulkan, см Vulkan validation layers on Android.

Добавление поддержки систем x86

Если вы также хотите включить поддержку устройств x86 и x86_64, выполните команду SCons третий и четвёртый раз с аргументами arch=x86_32 и arch=x86_64 перед сборкой APK с помощью Gradle. Например, для шаблона релиза:

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_android_binaries=yes

Это создаст шаблоны исполняемых файлов, работающие на всех платформах. Окончательный размер исполняемого файла экспортируемых проектов будет зависеть от выбранных вами платформ; другими словами, неиспользуемые платформы будут удалены из исполняемого файла.

Очистка созданных шаблонов экспорта

Для удаления созданных шаблонов экспорта можно использовать следующие команды:

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Использование шаблонов экспорта

Godot требует релизных и отладочных исполняемых файлов, скомпилированных с той же версией/коммитом, что и редактор. Если вы используете официальные исполняемые файлы для редактора, убедитесь, что установлены соответствующие шаблоны экспорта или собраны собственные на основе той же версии.

При экспорте игры Godot использует шаблоны в качестве основы и обновляет их содержимое по мере необходимости.

Установка шаблонов

Скомпилированные шаблоны (android_debug.apk, android_release.apk и android_source.zip) необходимо скопировать в папку шаблонов Godot, указав их соответствующие имена. Папка шаблонов может находиться по адресу:

  • Windows: %APPDATA%\Godot\export_templates\<version>\

  • Linux: $HOME/.local/share/godot/export_templates/<version>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<version>/

<version> имеет вид major.minor[.patch].status, используя значения из version.py в вашем исходном репозитории Godot (например, 4.1.3.stable или 4.2.dev). Вам также необходимо записать эту же строку версии в файл version.txt, расположенный рядом с шаблонами экспорта.

Однако, если вы пишете собственные модули или код на C++, вам может потребоваться настроить исполняемые файлы шаблонов как пользовательские шаблоны экспорта в меню экспорта проекта. Для этого необходимо включить Advanced Options (Дополнительные параметры).

../../../_images/andtemplates.webp

Вам даже не нужно их копировать, вы можете просто сослаться на полученный файл в каталоге bin\ исходной папки Godot, чтобы при следующей сборке вы автоматически ссылались на пользовательские шаблоны.

Создание редактора Godot

Компиляция редактора выполняется путем вызова SCons из корневого каталога Godot со следующими аргументами:

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes

  • Вы можете добавить параметр dev_build=yes для создания dev-сборки редактора Godot.

  • Вы можете добавить параметры debug_symbols=yes, чтобы включить отладочные символы в сгенерированную сборку.

    • Note that you can include separate_debug_symbols=yes to the last architecture you're building, to generate the debug symbols in a separate *-native-debug-symbols.zip file.

  • Вы можете пропустить определенные архитектуры в зависимости от целевого устройства, чтобы ускорить компиляцию.

Не забудьте добавить generate_android_binaries=yes к последней архитектуре, которую вы собираете, чтобы двоичные файлы генерировались после сборки.

Полученные двоичные файлы будут расположены в папке bin/android_editor_builds/.

Удаление двоичных файлов Редактора

Для удаления сгенерированных двоичных файлов редактора можно использовать следующие команды:

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Установка APK-файла редактора Godot

Если на устройстве Android включены параметры разработчика, подключите его к компьютеру через кабель для зарядки через порт USB/USB-C. Откройте Терминал/Командную строку и выполните следующие команды из корневого каталога со следующими аргументами:

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

Устранение неполадок

Платформа не отображается в SCons

Дважды проверьте, установлена ли переменная окружения ANDROID_HOME. Это необходимо для того, чтобы платформа появилась в списке обнаруженных платформ SCons. Подробнее см. в разделе Настройка системы сборки.

Приложение не установлено

Android может сообщать, что приложение установлено неправильно. В этом случае:

  • Проверьте правильность создания хранилища ключей отладки.

  • Проверьте, что исполняемый файл jarsigner принадлежит JDK 8.

Если проблема не устранена, откройте командную строку и запустите logcat:

adb logcat

Затем проверьте вывод при установке приложения; там должно быть сообщение об ошибке. Обратитесь за помощью, если не можете разобраться.

Приложение немедленно завершает работу

Если приложение запускается, но сразу же завершает работу, это может быть вызвано одной из следующих причин:

  • Обязательно используйте шаблоны экспорта, соответствующие версии вашего редактора. Если вы используете новую версию Godot, вам придется обновить и шаблоны.

  • libgodot_android.so отсутствует в libs/<arch>/, где <arch> — архитектура устройства.

  • Архитектура устройства не соответствует экспортированной. Убедитесь, что ваши шаблоны созданы для архитектуры этого устройства и что настройки экспорта включают её поддержку.

В любом случае adb logcat также должен показать причину ошибки.