Merge pull request #12046 from Calinou/android-gabe

Document GABE in Exporting for Android and Gradle builds for Android

tutorials/export/android_gradle_build.rst

@@ -3,22 +3,27 @@
 Gradle builds for Android
 =========================
 
-Godot provides the option to build using the gradle buildsystem. Instead of
-using the already pre-built template that ships with Godot, an Android
+Godot provides the option to build using the `Gradle <https://gradle.org/>`__ build system.
+Instead of using the already pre-built template that ships with Godot, an Android
 Java project gets installed into your project folder. Godot will then build it
 and use it as an export template every time you export the project.
 
 There are some reasons why you may want to do this:
 
-* Export an AAB file for Google Play.
-* Modify the project before it's built.
-* Add external SDKs that build with your project.
+- Export an AAB file for Google Play.
+- Modify the project before it's built.
+- Add external SDKs that build with your project.
 
-Configuring the gradle build is a fairly straightforward process. But first
-you need to follow the steps in :ref:`exporting for android<doc_exporting_for_android>`
+The native portion of the template (the ``.so`` library included in the APK)
+remains precompiled. This means that unlike
+:ref:`compiling a custom Android export template <doc_compiling_for_android>`,
+you don't need to install a C++ toolchain or clone the Godot source code.
+
+Configuring the Gradle build is a fairly straightforward process. But first,
+you need to follow the steps in :ref:`exporting for android <doc_exporting_for_android>`
 up to **Setting it up in Godot**. After doing that, follow the steps below.
 
-Set up the gradle build environment
+Set up the Gradle build environment
 -----------------------------------
 
 Go to the Project menu, and install the *Gradle Build* template:
@@ -31,8 +36,32 @@ download them.
 A Gradle-based Android project will be created under ``res://android/build``.
 Editing these files is not needed unless you really need to modify the project.
 
+Performing Gradle builds from the Android editor
+------------------------------------------------
 
-Enabling the gradle build and exporting
+Since Godot 4.6, it is possible to perform Gradle builds from the Android editor.
+This requires installing the
+`Godot Android Build Environment (GABE) <https://godotengine.org/download/android/#gabe>`__
+application on the same device the editor is running on.
+
+.. note::
+
+    This application is *not* required when exporting from the Android editor with
+    pre-built APK templates, or when exporting to other platforms.
+
+This application lets you install everything required to build Android projects with Gradle.
+It is called by the editor to perform Gradle builds when exporting to Android.
+
+To set up the build environment, open the app and follow these instructions:
+
+- Ensure you have an active Internet connection.
+- Open the :menu:`Rootfs` tab from the bottom navigation bar.
+- Click :button:`Install Rootfs`.
+
+After the installation completes, you can export projects using Gradle builds
+from the Godot editor.
+
+Enabling the Gradle build and exporting
 ---------------------------------------
 
 When setting up the Android project in the **Project > Export** dialog,
@@ -41,13 +70,12 @@ When setting up the Android project in the **Project > Export** dialog,
 .. image:: img/gradle_build_enable.webp
 
 From now on, attempting to export the project or one-click deploy will call the
-`Gradle <https://gradle.org/>`__ build system to generate fresh templates. The
-templates built will be used automatically afterwards, so no further configuration
-is needed.
+Gradle build system to generate fresh templates. The templates built will be
+used automatically afterwards, so no further configuration is needed.
 
 .. note::
 
-    When using the gradle Android build system, assets that are placed within a
+    When using the Gradle Android build system, assets that are placed within a
     folder whose name begins with an underscore will not be included in the
     generated APK. This does not apply to assets whose *file* name begins with
     an underscore.

tutorials/export/exporting_for_android.rst

@@ -18,8 +18,23 @@ The following steps detail what is needed to set up the Android SDK and the engi
     Projects written in C# can be exported to Android as of Godot 4.2, but support
     is experimental and :ref:`some limitations apply <doc_c_sharp_platforms>`.
 
+Setup on Android
+----------------
+
+When exporting to Android from the Android editor, you do **not** need to
+install OpenJDK or the Android SDK when exporting to Android, regardless of the
+export method used (pre-built APK or Gradle build).
+
+However, if you are performing a Gradle build, you will need to follow some
+steps described in :ref:`doc_android_gradle_build`.
+
+You can then skip to :ref:`doc_exporting_for_android_providing_launcher_icons`.
+
+Setup on Windows, macOS, and Linux
+----------------------------------
+
 Install OpenJDK 17
-------------------
+^^^^^^^^^^^^^^^^^^
 
 Download and install `OpenJDK 17 <https://adoptium.net/temurin/releases/?variant=openjdk17&version=17&os=any&arch=any>`__.
 
@@ -28,7 +43,7 @@ Download and install `OpenJDK 17 <https://adoptium.net/temurin/releases/?variant
     Higher versions of the JDK are also supported, but we recommend using JDK 17 for optimal compatibility and stability.
 
 Download the Android SDK
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Download and install the Android SDK.
 
@@ -61,9 +76,8 @@ Download and install the Android SDK.
     If you are using Linux,
     **do not use an Android SDK provided by your distribution's repositories as it will often be outdated**.
 
-
 Setting it up in Godot
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Enter the Editor Settings screen (under the Godot tab for macOS, or the Editor tab
 for other platforms). This screen contains the editor settings for the user
@@ -95,6 +109,8 @@ Once that is configured, everything is ready to export to Android!
     the application in question from the Android device before exporting to
     Android again.
 
+.. _doc_exporting_for_android_providing_launcher_icons:
+
 Providing launcher icons
 ------------------------
 
@@ -155,6 +171,17 @@ You can optimize the size of your application by compiling an Android export
 template with only the features you need. See :ref:`doc_optimizing_for_size` for
 more information.
 
+Performing a custom Gradle build
+--------------------------------
+
+If you need to modify the template's Java code or integrate with third-party
+Android SDKs, you may want to use a custom Gradle build instead of the default
+pre-built APK template. This allows you to have more control over the build
+process and the generated project, and you can use it as a base for further
+customization.
+
+See :ref:`doc_android_gradle_build` for guidance on setting up a custom Gradle build.
+
 Environment variables
 ---------------------