From 73091bea0a6d41e4a8b2524456b61017360ea87b Mon Sep 17 00:00:00 2001 From: Fredia Huya-Kouadio Date: Mon, 29 Jul 2024 23:39:57 -0700 Subject: [PATCH] Update the Android build documentation (#9669) Co-authored-by: Hugo Locurcio --- .../compiling/compiling_for_android.rst | 72 +++++++++++-------- tutorials/editor/using_the_android_editor.rst | 3 +- tutorials/export/exporting_for_android.rst | 5 +- 3 files changed, 48 insertions(+), 32 deletions(-) diff --git a/contributing/development/compiling/compiling_for_android.rst b/contributing/development/compiling/compiling_for_android.rst index 49cbacf69..c7f50ade7 100644 --- a/contributing/development/compiling/compiling_for_android.rst +++ b/contributing/development/compiling/compiling_for_android.rst @@ -90,10 +90,11 @@ Setting up the buildsystem Building the export templates ----------------------------- -Godot needs two export templates for Android: the optimized "release" -template (``android_release.apk``) and the debug template (``android_debug.apk``). +Godot needs three export templates for Android: the optimized "release" +template (``android_release.apk``), the debug template (``android_debug.apk``), +and the Gradle build template (``android_source.zip``). As Google requires all APKs to include ARMv8 (64-bit) libraries since August 2019, -the commands below build an APK containing both ARMv7 and ARMv8 libraries. +the commands below build templates containing both ARMv7 and ARMv8 libraries. Compiling the standard export templates is done by calling SCons from the Godot root directory with the following arguments: @@ -105,14 +106,6 @@ root directory with the following arguments: scons platform=android target=template_release arch=arm32 scons platform=android target=template_release arch=arm64 generate_apk=yes -.. note:: - - If you are changing the list of architectures you're building, remember to add - ``generate_apk=yes`` to the *last* architecture you're building, so that an APK - file is generated after the build. - -The resulting APK will be located at ``bin/android_release.apk``. - - Debug template (used when exporting with **Debugging Enabled** checked) :: @@ -120,7 +113,25 @@ The resulting APK will be located at ``bin/android_release.apk``. scons platform=android target=template_debug arch=arm32 scons platform=android target=template_debug arch=arm64 generate_apk=yes -The resulting APK will be located at ``bin/android_debug.apk``. +- (**Optional**) Dev template (used when troubleshooting) + +:: + + scons platform=android target=template_debug arch=arm32 dev_build=yes + scons platform=android target=template_debug arch=arm64 dev_build=yes generate_apk=yes + +The resulting templates will be located under the ``bin`` directory: + +- ``bin/android_release.apk`` for the release template +- ``bin/android_debug.apk`` for the debug template +- ``bin/android_dev.apk`` for the dev template +- ``bin/android_source.zip`` for the Gradle build template + +.. note:: + + - If you are changing the list of architectures you're building, remember to add ``generate_apk=yes`` to the *last* architecture you're building, so that the template files are generated after the build. + + - To include debug symbols in the generated templates, add the ``debug_symbols=yes`` parameter to the SCons command. .. seealso:: @@ -142,10 +153,10 @@ example, for the release template: scons platform=android target=template_release arch=x86_32 scons platform=android target=template_release arch=x86_64 generate_apk=yes -This will create a fat binary that works on all platforms. -The final APK size of exported projects will depend on the platforms you choose +This will create template binaries that works on all platforms. +The final binary size of exported projects will depend on the platforms you choose to support when exporting; in other words, unused platforms will be removed from -the APK. +the binary. Cleaning the generated export templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -164,19 +175,18 @@ You can use the following commands to remove the generated export templates: Using the export templates -------------------------- -Godot needs release and debug APKs that were compiled against the same +Godot needs release and debug binaries that were compiled against the same version/commit as the editor. If you are using official binaries for the editor, make sure to install the matching export templates, or build your own from the same version. -When exporting your game, Godot opens the APK, changes a few things inside and -adds your files. +When exporting your game, Godot uses the templates as a base, and updates their content as needed. Installing the templates ~~~~~~~~~~~~~~~~~~~~~~~~ The newly-compiled templates (``android_debug.apk`` -and ``android_release.apk``) must be copied to Godot's templates folder +, ``android_release.apk``, and ``android_source.zip``) must be copied to Godot's templates folder with their respective names. The templates folder can be located in: - Windows: ``%APPDATA%\Godot\export_templates\\`` @@ -191,7 +201,7 @@ next to your export templates. .. TODO: Move these paths to a common reference page However, if you are writing your custom modules or custom C++ code, you -might instead want to configure your APKs as custom export templates +might instead want to configure your template binaries as custom export templates here: .. image:: img/andtemplates.png @@ -214,16 +224,20 @@ root directory with the following arguments: scons platform=android arch=x86_32 production=yes target=editor scons platform=android arch=x86_64 production=yes target=editor generate_apk=yes -You can skip certain architectures depending on your target device to speed up -compilation. Remember to add ``generate_apk=yes`` to the *last* architecture -you're building, so that an APK file is generated after the build. +- You can add the ``dev_build=yes`` parameter to generate a dev build of the Godot editor. -The resulting APK will be located at ``bin/android_editor_builds/android_editor-release.apk``. +- You can add the ``debug_symbols=yes`` parameter to include the debug symbols in the generated build. -Removing the Editor templates ------------------------------ +- You can skip certain architectures depending on your target device to speed up compilation. -You can use the following commands to remove the generated editor templates: +Remember to add ``generate_apk=yes`` to the *last* architecture you're building, so that binaries are generated after the build. + +The resulting binaries will be located under ``bin/android_editor_builds/``. + +Removing the Editor binaries +---------------------------- + +You can use the following commands to remove the generated editor binaries: :: @@ -233,8 +247,8 @@ You can use the following commands to remove the generated editor templates: # On Linux and macOS ./gradlew clean -Installing the Godot editor ---------------------------- +Installing the Godot editor APK +------------------------------- With an Android device with Developer Options enabled, connect the Android device to your computer via its charging cable to a USB/USB-C port. Open up a Terminal/Command Prompt and run the following commands from the root directory with the following arguments: diff --git a/tutorials/editor/using_the_android_editor.rst b/tutorials/editor/using_the_android_editor.rst index 04b8804ff..a8848f37d 100644 --- a/tutorials/editor/using_the_android_editor.rst +++ b/tutorials/editor/using_the_android_editor.rst @@ -9,7 +9,7 @@ that can be used to work on new or existing projects on Android devices. .. note:: - The Android editor is in beta testing stage, while we continue to refine the experience, + The Android editor is in early access, while we continue to refine the experience, and bring it up to parity with the Desktop version of the editor. See :ref:`doc_using_the_android_editor_limitations` below. Android devices support @@ -41,7 +41,6 @@ Here are the known limitations and issues of the Android editor: - No support for building and exporting an Android APK binary. As a workaround, you can generate and export a `Godot PCK or ZIP file `__ - No support for building and exporting binaries for other platforms -- Performance and stability issues when using the *Vulkan Mobile* renderer for a project - UX not optimized for Android phones form-factor - `Android Go devices `__ lacks the *All files access* permission required for device read/write access. diff --git a/tutorials/export/exporting_for_android.rst b/tutorials/export/exporting_for_android.rst index 30d7f6464..2ba960764 100644 --- a/tutorials/export/exporting_for_android.rst +++ b/tutorials/export/exporting_for_android.rst @@ -28,7 +28,7 @@ Download the Android SDK Download and install the Android SDK. -- You can install the Android SDK using `Android Studio Hedgehog (version 2023.1.1) or later `__. +- You can install the Android SDK using `Android Studio Iguana (version 2023.2.1) or later `__. - Run it once to complete the SDK setup using these `instructions `__. - Ensure that the `required packages `__ are installed as well. @@ -37,6 +37,9 @@ Download and install the Android SDK. - Android SDK Build-Tools version 34.0.0 - Android SDK Platform 34 - Android SDK Command-line Tools (latest) + + - Ensure that the `NDK and CMake are installed and configured `__. + - CMake version 3.10.2.4988404 - NDK version r23c (23.2.8568313)