==== Installing tools ====

There is nothing magical in the process of getting the Android projects building on Linux. But it does require some work since a bunch of tools are needed.

The two most important and fundamental packages are the [[http://developer.android.com/sdk/index.html|Android SDK]] and the [[http://developer.android.com/tools/sdk/ndk/index.html|Android NDK]]. Since the installation processes of those is thoroughly explained in the Android developer documentation that won't be repeated here. Follow the Android documentation at least as much that you get the ''hello-jni'' application built, installed (on a device or an emulator) and running. Only after that continue here.

==== Building Proton examples ====

Some Proton examples are in a good shape regarding how up-to-date their Android projects are to be built in Linux. Some examples alas are not in so good shape. Apologies for that. Currently, if you can find a ''build.sh'' script in an example's ''android'' directory then that example is in a good shape. Continue with such an example.

The first thing you need to do is to update the project settings so that it's known where your Android SDK is located. Issue this command within the project's ''android'' directory (note the dot at the end):
<code>android update project -p .</code>

You may have to also give the ''-t'' argument to specify the target. You get a list of your installed targets with the ''android list targets'' command. So perhaps something like this:
<code>$> android list targets
Available Android targets:
----------
id: 1 or "android-3"
     Name: Android 1.5
[--- more targets ---]
$> android update project -p . -t android-3
</code>

Unless you change the installation location of your Android SDK or want to change the target you don't have to execute these commands after this.

Basically it should be possible to build the complete Android application by just executing the ''build.sh'' script. The result of the successful completion of that script should produce a ''<ProjectName>-debug.apk'' package under the ''android/bin'' directory which can be installed on a device or emulator.

If however something goes wrong with the script (or you want to experiment with an example without a ''build.sh'' script) here is some explanation about the steps that the script takes. You can off course execute these commands by hand too, more or less in this order.

=== <PROTON>/tools/linux/prepareAndroid.sh ===

**Note on 7/28/2018:**  The tools directory is gone, but I kept this script in <PROTON>RTPack/linux I think.  Aki wrote this part, I've never actually made Android stuff in linux, so sorry if this is broken now! -Seth

This is a script that prepares a Proton style project for compilation. It copies, moves and modifies various source files. It also performs the preprocessing step explained in [[proton:android_projects#v2_styles|the general explanation about Android projects]] page. Whenever a source file that needs preprocessing is changed this file can be run in order to get that file updated for compilation.

The script accepts some command line parameters which control its behaviour. Use the -h argument to get a list of those.

This script must be executed within the ''android'' directory of the project.

=== ndk-build ===

This is the normal ''ndk-build'' script of the Android NDK. Nothing special here.

=== <PROTON>/tools/linux/update_media.sh and <PROTON>/tools/linux/androidSyncAssets.sh ===

**Note on 7/28/2018:** Scripts moved to <PROTON>/RTPack/linux.  -Seth

The ''update_media.sh'' script uses the [[proton:rtpack|RTPack]] tool to create font files and convert the various image files. It is not specific to Android projects but applies to all the platforms. It should be executed in the project's ''media'' directory. The resulting files end up to the project's ''bin'' directory.

The ''androidSyncAssets.sh'' script simply makes sure that the contents of the project's ''android/assets'' directory is the same as the project's ''bin'' directory's contents.

Together these two scripts make sure that the graphical assets and sounds and such media is in the correct format in the correct location for the Android project.

You only need to execute these scripts when modifications to the project's media files are made.

=== ant debug ===

This again is the usual Android SDK's build command. It produces the debug version of the application package to the ''android/bin'' directory. You can install it to a device with an ''ant installd'' command or using the ''adb'' command as usual. Since this is basic Android development stuff refer to the Android developer documentation for more details.

=== More... ===

These scripts only get you a debug build of the project. When you need a release build or something that these scripts don't produce you need to execute various commands yourself. The tools provided with Proton only get you so far (for now at least - they are off course constantly improving).

==== Building your own Android projects ====

Basically you just need to construct a similar project that the Proton examples are. Replace the project name (alas in many places) with your own project name and write your own ''AndroidManifest.xml''. The scripts in ''<PROTON>/tools/linux/'' are meant to be such that they can be used with any project following the Proton structure. If something in a script doesn't quite work, it's possibly not your fault but the tool's. Please report any errors you encounter with the tools on the forum for example - or even better, supply patches.