diff --git a/development/compiling/compiling_for_android.rst b/development/compiling/compiling_for_android.rst index ba41da370..83597de07 100644 --- a/development/compiling/compiling_for_android.rst +++ b/development/compiling/compiling_for_android.rst @@ -8,47 +8,65 @@ Compiling for Android Note ---- -For most cases, using the built-in deployer and export templates is good +In most cases, using the built-in deployer and export templates is good enough. Compiling the Android APK manually is mostly useful for custom builds or custom packages for the deployer. -Also, you still need to do all the steps mentioned in the -:ref:`doc_exporting_for_android` tutorial before attempting your custom -export template. +Also, you still need to follow the steps mentioned in the +:ref:`doc_exporting_for_android` tutorial before attempting to build +a custom export template. Requirements ------------ For compiling under Windows, Linux or macOS, the following is required: -- Python 2.7+ or Python 3.5+ -- SCons build system -- [Windows only] PyWin32 (optional, for parallel compilation) -- Android SDK version 23.0.3 [Note: Please install all tools and extras of the SDK Manager] -- Android build tools version 19.1 -- Android NDK r13 or later +- `Python 2.7+ or Python 3.5+ `_ +- `SCons `_ build system +- `Android SDK `_ (command-line tools are sufficient) + + - Required SDK components will be automatically installed by Gradle (except the NDK) + +- `Android NDK `_ r17 or later - Gradle (will be downloaded and installed automatically if missing) -- JDK 6 or later (either OpenJDK or Oracle JDK) - JDK 9 is untested as of now +- JDK 8 (either OpenJDK or Oracle JDK) + + - JDK 9 or later are not currently supported + - You can download a build from `ojdkbuild `_ + +.. seealso:: For a general overview of SCons usage for Godot, see + :ref:`doc_introduction_to_the_buildsystem`. Setting up the buildsystem -------------------------- -Set the environment variable ANDROID_HOME to point to the Android -SDK. +Set the environment variable ``ANDROID_HOME`` to point to the Android +SDK. If you downloaded the Android command-line tools, this would be +the folder where you extracted the contents of the ZIP archive. +Later on, ``gradlew`` will install necessary SDK components in this folder. +However, you need to accept the SDK component licenses before they can be +downloaded by Gradle. This can be done by running the following command +from the root of the SDK directory, then answering all the prompts +with ``y``: -Set the environment variable ANDROID_NDK_ROOT to point to the +:: + + tools/bin/sdkmanager --licenses + + +Set the environment variable ``ANDROID_NDK_ROOT`` to point to the Android NDK. -To set those environment variables on Windows, press Windows+R, type +To set those environment variables on Windows, press **Windows + R**, type "control system", then click on **Advanced system settings** in the left pane, then click on **Environment variables** on the window that appears. -To set those environment variables on Unix (e.g. Linux, macOS), use +To set those environment variables on Linux or macOS, use ``export ANDROID_HOME=/path/to/android-sdk`` and -``export ANDROID_NDK_ROOT=/path/to/android-ndk``. -Where /path/to/android-sdk and /path/to/android-ndk is the path where Android SDK -and Android NDK are placed on your PC. +``export ANDROID_NDK_ROOT=/path/to/android-ndk`` +where ``/path/to/android-sdk`` and ``/path/to/android-ndk`` point to +the root of the SDK and NDK directories. Toolchain ~~~~~~~~~ @@ -66,81 +84,75 @@ Building the export templates ----------------------------- Godot needs two export templates for Android: the optimized "release" -template (`android_release.apk`) and the debug version (`android_debug.apk`). -Compiling the standard export templates is done by calling scons with +template (``android_release.apk``) and the debug template (``android_debug.apk``). +As Google will require all APKs to include ARMv8 (64-bit) libraries starting +from August 2019, the commands below will build an APK containing both +ARMv7 and ARMv8 libraries. + +Compiling the standard export templates is done by calling SCons with the following arguments: -- Release template (used when exporting with "Debugging Enabled" OFF) +- Release template (used when exporting with **Debugging Enabled** unchecked) :: - C:\godot> scons platform=android target=release - C:\godot> cd platform/android/java - C:\godot\platform\android\java> gradlew build + scons platform=android target=release android_arch=armv7 + scons platform=android target=release android_arch=arm64v8 + cd platform/android/java + # On Windows + .\gradlew build + # On Linux and macOS + ./gradlew build -(on Linux or macOS, execute the `gradlew` script with `./gradlew build`) -The resulting APK is in: +The resulting APK will be located at ``bin/android_release.apk``. + +- Debug template (used when exporting with **Debugging Enabled** checked) :: - bin\android_release.apk + scons platform=android target=release_debug android_arch=armv7 + scons platform=android target=release_debug android_arch=arm64v8 + cd platform/android/java + # On Windows + .\gradlew build + # On Linux and macOS + ./gradlew build -- Debug template (used when exporting with "Debugging Enabled" ON) - -:: - - C:\godot> scons platform=android target=release_debug - C:\godot> cd platform/android/java - C:\godot\platform\android\java> gradlew build - -The resulting APK is in: - -:: - - bin\android_debug.apk - -Faster compilation -~~~~~~~~~~~~~~~~~~ - -If you are on Unix or installed PyWin32 on Windows and have multiple CPU -cores available, you can speed up the compilation by adding the ``-jX`` -argument to the SCons command, where ``X`` is the number of cores that you -want to allocate to the compilation, e.g. ``scons -j4``. +The resulting APK will be located at ``bin/android_debug.apk``. Adding support for x86 devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you also want to include support for x86 devices, run the scons command -a second time with the ``android_arch=x86`` argument before building the APK -with Gradle. For example for the release template: +If you also want to include support for x86 devices, run the SCons command +a third time with the ``android_arch=x86`` argument before building the APK +with Gradle. For example, for the release template: :: - C:\godot> scons platform=android target=release - C:\godot> scons platform=android target=release android_arch=x86 - C:\godot> cd platform/android/java - C:\godot\platform\android\java> gradlew build + scons platform=android target=release android_arch=armv7 + scons platform=android target=release android_arch=arm64v8 + scons platform=android target=release android_arch=x86 + cd platform/android/java + # On Windows + .\gradlew build + # On Linux and macOS + ./gradlew build -This will create a fat binary that works in both platforms, but will add -about 6 megabytes to the APK. - -Troubleshooting -~~~~~~~~~~~~~~~ - -It might be necessary to clean the build cache between two APK compilations, -as some users have reported issues when building the two export templates -one after the other. +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 +to support when exporting; in other words, unused platforms will be removed from +the APK. Using the export templates -------------------------- -As export templates for Android, Godot needs release and debug APKs 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 to build your own from the same version. +Godot needs release and debug APKs 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. @@ -148,13 +160,18 @@ adds your files. Installing the templates ~~~~~~~~~~~~~~~~~~~~~~~~ -The newly-compiled templates (android_debug.apk and android_release.apk) -must be copied to Godot's templates folder with their respective names. -The templates folder can be located in: +The newly-compiled templates (``android_debug.apk`` +and ``android_release.apk``) must be copied to Godot's templates folder +with their respective names. The templates folder can be located in: -- Windows: ``C:\Users\[username]\AppData\Roaming\Godot\templates`` -- Linux: ``/home/[username]/.local/share/godot/templates/[gd-version]/`` -- macOS: ``/users/[username]/.godot/templates`` +- Windows: ``%APPDATA%\Godot\templates\\`` +- Linux: ``$HOME/.local/share/godot/templates//`` +- macOS: ``$HOME/Library/Application Support/Godot/templates//`` + +```` is of the form ``major.minor[.patch].status`` using values from +``version.py`` in your Godot source repository (e.g. ``3.0.5.stable`` or ``3.1.dev``). +You also need to write this same version string to a ``version.txt`` file located +next to your export templates. .. TODO: Move these paths to a common reference page @@ -175,80 +192,34 @@ Troubleshooting Application not installed ~~~~~~~~~~~~~~~~~~~~~~~~~ -Android might complain the application is not correctly installed. If -so, check the following: +Android might complain the application is not correctly installed. +If so: - Check that the debug keystore is properly generated. -- Check that jarsigner is from JDK 6, 7 or 8. +- Check that the jarsigner executable is from JDK 8. -If it still fails, open a command line and run logcat: +If it still fails, open a command line and run `logcat `_: :: - C:\android-sdk\platform-tools> adb logcat - -And check the output while the application is installed. Reason for -failure should be presented there. + adb logcat +Then check the output while the application is installed; +the error message should be presented there. Seek assistance if you can't figure it out. Application exits immediately ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If the application runs but exits immediately, there might be one of the -following reasons: +If the application runs but exits immediately, this might be due to +one of the following reasons: - Make sure to use export templates that match your editor version; if you use a new Godot version, you *have* to update the templates too. -- libgodot_android.so is not in ``lib/armeabi-v7a`` or ``lib/armeabi`` -- Device does not support armv7 (try compiling yourself for armv6) -- Device is Intel, and apk is compiled for ARM. +- ``libgodot_android.so`` is not in ``libs//`` + where ```` is the device's architecture. +- The device's architecture does not match the exported one(s). + Make sure your templates were built for that device's architecture, + and that the export settings included support for that architecture. In any case, ``adb logcat`` should also show the cause of the error. - -Compilation fails -~~~~~~~~~~~~~~~~~ - -On Linux systems with Kernel version 4.3 or newer, compilation may fail -with the error "pthread_create failed: Resource temporarily unavailable." - -This is because of a change in the way Linux limits thread creation. But -you can change those limits through the command line. Please read this -section thoroughly before beginning. - -First open a terminal, then begin compilation as usual (it may be a good -idea to run a --clean first). While compiling enter the following in -your terminal: - -:: - - user@host:~/$ top -b -n 1 | grep scons - -The output should list a scons process, with its PID as the first number -in the output. For example the PID 1077 in the output shown below: - -:: - - user@host:~/$ top -b -n 1 | grep scons - 1077 user 20 0 10544 1628 1508 S 0.000 0.027 0:00.00 grep - -Now you can use another command to increase the number of processes that -scons is allowed to spawn. You can check its current limits with: - -:: - - user@host:~/$ prlimit --pid=1077 --nproc - -You can increase those limits with the command: - -:: - - user@host:~/$ prlimit --pid=1077 --nproc=60000:60500 - -Obviously you should substitute the scons PID output by top and a limits -that you think suitable. These are in the form --nproc=soft:hard where -soft must be lesser than or equal to hard. See the man page for more -information. - -If all went well, and you entered the prlimit command while scons was -running, then your compilation should continue without the error.