From abd37b7b83dc0ae1c955f0b1dd8dcd44617a9edd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Wed, 3 Aug 2016 08:21:13 +0200 Subject: [PATCH] Improve docs on compiling for Android for 2.1 Based on @KelinciFX's work in #214. --- reference/compiling_for_android.rst | 211 ++++++++++++---------------- 1 file changed, 93 insertions(+), 118 deletions(-) diff --git a/reference/compiling_for_android.rst b/reference/compiling_for_android.rst index 3b8197870..47d166b7e 100644 --- a/reference/compiling_for_android.rst +++ b/reference/compiling_for_android.rst @@ -21,16 +21,17 @@ Requirements For compiling under Windows, Linux or OSX, the following is required: -- Python 2.7+ (3.0 is untested as of now). -- SCons build system. +- Python 2.7+ (3.0 is untested as of now) +- SCons build system +- [Windows only] PyWin32 (optional, for parallel compilation) - Android SDK version 19 [Note: Please install all Tools and Extras of sdk manager] - Android build tools version 19.1 -- Android NDK -- Gradle -- OpenJDK 6 or later (or Oracle JDK 6 or later) +- Android NDK r10e 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 -Setting up SCons ----------------- +Setting up the buildsystem +-------------------------- Set the environment variable ANDROID_HOME to point to the Android SDK. @@ -43,66 +44,12 @@ To set those environment variables on Windows, press Windows+R, type pane, then click on **Environment variables** on the window that appears. -To set those environment variables on Linux, use +To set those environment variables on Unix (e.g. Linux, Mac OSX), use ``export ANDROID_HOME=/path/to/android-sdk`` and ``export ANDROID_NDK_ROOT=/path/to/android-ndk``. -Compiling ---------- - -Go to the root dir of the engine source code and type: - -:: - - C:\godot> scons platform=android - -This should result in a regular .so in ``\bin`` folder as if it was -compiled with flags: ``tools=no target=debug``. The resulting file will -be huge because it will contain all debug symbols, so for next builds, -using ``target=release_debug`` or ``target=release`` is recommended. - -Copy the .so to the ``libs/armeabi`` Android folder (or symlink if you are -in Linux or OSX). Note: Git does not support empty directories so you -will have to create it if it does not exist: - -:: - - C:\godot> mkdir platform/android/java/libs - C:\godot> mkdir platform/android/java/libs/armeabi - -Then copy: - -:: - - C:\godot> copy bin/libgodot.android..so platform/android/java/libs/armeabi/libgodot_android.so - -Or alternatively, if you are under a Unix system you can symlink: - -:: - - user@host:~/godot$ ln -s bin/libgodot.android..so platform/android/java/libs/armeabi/libgodot_android.so - -Remember that only *one* of libgodot_android.so must exist for each -platform, for each build type (release, debug, etc), it must be -replaced. - -**Note**: The file inside ``libs/armeabi`` must be renamed to -**"libgodot_android.so"**, or else unsatisfied link error will happen -at runtime. - -If you also want to include support for x86 Android, add the following -compile flag: ``android_arch=x86``, then copy/symlink the resulting binary to -the ``x86`` folder: - -:: - - C:\godot> copy bin/libgodot.android..x86.so platform/android/java/libs/x86/libgodot_android.so - -This will create a fat binary that works in both platforms, but will add -about 6 megabytes to the APK. - Toolchain ---------- +~~~~~~~~~ We usually try to keep the Godot Android build code up to date, but Google changes their toolchain versions very often, so if compilation @@ -113,74 +60,99 @@ the current number, then set the following environment variable: NDK_TARGET (by default set to "arm-linux-androideabi-4.9") -Building the APK ----------------- - -To compile the APK, go to the Java folder and run ``gradlew.bat build`` -(or ``./gradlew build`` on Unix): - -:: - - C:\godot\platform\android\java> gradlew.bat build - - -In the ``java/bin`` subfolder, the resulting apk can be used as export -template. - -**Note:** If you reaaaally feel oldschool, you can copy your entire game -(or symlink) to the assets/ folder of the Java project (make sure -engine.cfg is in assets/) and it will work, but you lose all the -benefits of the export system (scripts are not byte-compiled, textures -not converted to Android compression, etc. so it's not a good idea). - -Compiling export templates --------------------------- - -Godot needs the freshly compiled APK as export templates. It opens the -APK, changes a few things inside, adds your file and spits it back. It's -really handy! (and required some reverse engineering of the format). +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 the following arguments: -- (debug) - -:: - - C:\godot> scons platform=android target=release_debug - C:\godot> cp bin/libgodot_android.opt.debug.so platform/android/java/libs/armeabi/libgodot_android.so - C:\godot> cd platform/android/java - C:\godot\platform\android\java> gradlew.bat build - -Resulting APK is in: - -:: - - platform/android/java/build/outputs/apk/java-release-unsigned.apk - -- (release) +- Release template (used when exporting with "Debugging Enabled" OFF) :: C:\godot> scons platform=android target=release - C:\godot> cp bin/libgodot_android.opt.so platform/android/java/libs/armeabi/libgodot_android.so C:\godot> cd platform/android/java - C:\godot\platform\android\java> gradlew.bat build + C:\godot\platform\android\java> gradlew build -Resulting APK is in: +The resulting APK is in: :: - platform/android/java/build/outputs/apk/java-release-unsigned.apk + bin\android_release.apk -(same as before) - -They must be copied to your templates folder with the following names: +- Debug template (used when exporting with "Debugging Enabled" ON) :: - android_debug.apk - android_release.apk + 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``. + + +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: + +:: + + 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 + +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. + +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. + +When exporting your game, Godot opens the APK, changes a few things inside, +adds your file and spits it back. It's really handy! (and required some +reverse engineering of the format). + +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: + +- Windows: ``C:\Users\[username]\AppData\Roaming\Godot\templates`` +- Linux: ``/home/[username]/.godot/templates`` +- Mac OSX: ``/users/[username]/.godot/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 @@ -189,8 +161,9 @@ here: .. image:: /img/andtemplates.png You don't even need to copy them, you can just reference the resulting -file in the ``bin\`` directory of your Godot source folder, so the next -time you build you automatically have the custom templates referenced. +file in the ``bin\`` directory of your Godot source folder, so that the +next time you build you will automatically have the custom templates +referenced. Troubleshooting --------------- @@ -202,7 +175,7 @@ Android might complain the application is not correctly installed. If so, check the following: - Check that the debug keystore is properly generated. -- Check that jarsigner is from JDK6. +- Check that jarsigner is from JDK 6, 7 or 8. If it still fails, open a command line and run logcat: @@ -221,7 +194,9 @@ Application exits immediately If the application runs but exits immediately, there might be one of the following reasons: -- libgodot_android.so is not in ``libs/armeabi`` +- 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.