Improve docs on compiling for Android for 2.1

Based on @KelinciFX's work in #214.

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.<version>.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.<version>.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.<version>.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):
-
-::
+Building the export templates
+-----------------------------
 
-    C:\godot\platform\android\java> gradlew.bat build
+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:
 
+-  Release template (used when exporting with "Debugging Enabled" OFF)
 
-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).
+    C:\godot> scons platform=android target=release
+    C:\godot> cd platform/android/java
+    C:\godot\platform\android\java> gradlew build
 
-Compiling export templates
---------------------------
+The resulting APK is in:
 
-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).
+::
 
-Compiling the standard export templates is done by calling scons with
-the following arguments:
+    bin\android_release.apk
 
--  (debug)
+-  Debug template (used when exporting with "Debugging Enabled" ON)
 
 ::
 
     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
+    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_debug.apk
 
--  (release)
+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> cp bin/libgodot_android.opt.so platform/android/java/libs/armeabi/libgodot_android.so
+    C:\godot> scons platform=android target=release android_arch=x86
     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:
+This will create a fat binary that works in both platforms, but will add
+about 6 megabytes to the APK.
 
-::
+Troubleshooting
+~~~~~~~~~~~~~~~
 
-    platform/android/java/build/outputs/apk/java-release-unsigned.apk
+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.
 
-(same as before)
+Using the export templates
+--------------------------
 
-They must be copied to your templates folder with the following names:
+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``
 
-    android_debug.apk
-    android_release.apk
+.. 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.