Table of Contents

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 Android SDK and the 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):

android update project -p .

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:

$> android list targets
Available Android targets:
----------
id: 1 or "android-3"
     Name: Android 1.5
[--- more targets ---]
$> android update project -p . -t android-3

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

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 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

The update_media.sh script uses the 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.