Improve the Compiling for Android page

This mentions that Gradle will automatically download SDK components
(except the NDK, as it is used before Gradle is called).

(cherry picked from commits 012491d8b1c25430159682df146017dbaf7db498
and 2514d3415c1492988421eff14d6f3c099d213a57, with some more changes
from merge conflict resolution)

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 OSX, the following is required:
 
--  Python 2.7+ (3.0 is untested as of now)
--  SCons build system
--  [Windows only] PyWin32 (optional, for parallel compilation)
--  Android SDK version 23.0.3 [Note: Please install all Tools and Extras of sdk manager]
--  Android build tools version 19.1
--  Android NDK r13 or later
+-  `Python 2.7+ or Python 3.5+ <https://www.python.org/downloads/>`_
+-  `SCons <https://scons.org/pages/download.html>`_ build system
+-  `Android SDK <https://developer.android.com/studio/#command-tools>`_ (command-line tools are sufficient)
+
+   -  Required SDK components will be automatically installed by Gradle (except the NDK)
+
+-  `Android NDK <https://developer.android.com/ndk/downloads/>`_ 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 <https://github.com/ojdkbuild/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, Mac OSX), 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 you 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,73 @@ 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:
+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.
 
--  Release template (used when exporting with "Debugging Enabled" OFF)
-
-::
-
-    C:\godot> scons platform=android target=release
-    C:\godot> cd platform/android/java
-    C:\godot\platform\android\java> gradlew build
-    
-(on Linux/OSX, execute the `gradlew` script with `./gradlew build`)
+Compiling the standard export templates is done by calling SCons with
+the following arguments:
 
-The resulting APK is in:
+-  Release template (used when exporting with **Debugging Enabled** unchecked)
 
 ::
 
-    bin\android_release.apk
+    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
 
--  Debug template (used when exporting with "Debugging Enabled" ON)
+The resulting APK will be located at ``bin/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:
+-  Debug template (used when exporting with **Debugging Enabled** checked)
 
 ::
 
-    bin\android_debug.apk
-
-Faster compilation
-~~~~~~~~~~~~~~~~~~
+    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
 
-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,
 adds your file and spits it back. It's really handy! (and required some
@@ -149,13 +159,18 @@ 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:
+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``
+-  Windows: ``%APPDATA%\Godot\templates\<version>\``
+-  Linux: ``$HOME/.local/share/godot/templates/<version>/``
+-  macOS: ``$HOME/Library/Application Support/Godot/templates/<version>/``
+
+``<version>`` 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
 
@@ -176,81 +191,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 <https://developer.android.com/studio/command-line/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/<android_arch>/``
+   where ``<android_arch>`` 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.
-