mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 18:29:11 +00:00
Merge pull request #216 from godotengine/pr-compiling-android
Improve docs on compiling for Android for 2.1
This commit is contained in:
Rémi Verschelde
@@ -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):
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user