[[PageOutline]]
= How To Build BOINC Apps for Android =

This document describes how to build BOINC apps for Android.

We assume the app is written in C/C++.
It must be cross-compiled on a non-Android system
(Linux, Windows, or Mac; the instructions here are for Linux).
The BOINC API library (libboincapi) must also be cross-compiled and linked.
The  result of this is a "native mode" executable
for a particular architecture (ARM, MIPS, or Intel) on Android.

Various build systems can be used for this purpose:

 * The GNU tools (configure/make).
 * Eclipse
 * Android Studio

In this document we'll use the GNU tools.

== Cookbook ==

In the following, we'll assume that on your build system:

 * the BOINC source tree is at '''~/boinc'''.
 * the source code for your application is at '''~/my_app'''.

Download and install the latest Android Native Development Kit (NDK):
http://developer.android.com/tools/sdk/ndk/index.html

Set an environment variable NDKROOT to point to the NDK directory, e.g.
{{{
export NDKROOT="$HOME/android-ndk-r10d"
}}}

Prepare the Android toolchain by doing
{{{
cd ~/boinc/android
build_androidtc_arm.sh
}}}
This create a directory ~/androidarm-tc containing
compilers, linkers, and libraries for that CPU type.

Now build the BOINC libraries:
{{{
cd ~/boinc/android
build_libraries_arm.sh
}}}
This builds the libraries,
and stores them together with their .h files in ~/androidarm-tc.

Now build your app as follows:
{{{
cd ~/my_app
~/boinc/android/boinc_build_app_arm.sh
}}}

Note: this assumes we're building an ARM executable.
If you want to build MIPS or Intel, substitute "mips" or "intel" in the above commands.

== Building FPU versions ==

To build a version for VFP:
{{{
-O3 -mhard-float -mfpu=vfp -mfloat-abi=softfp -fomit-frame-pointer
}}}
To build a version for neon:
{{{
-O3 -mhard-float -mfpu=neon -mfloat-abi=softfp -fomit-frame-pointer
}}}

It's often useful to build a single executable that can support the vfp or neon libraries & instructions,
and then use the BOINC APP_INIT_DATA and HOST_INFO structures
to find the capabilities of the host and call the appropriate optimized routines
(member variable 'p_features' e.g. strstr(aid.host_info.p_features, " neon ").  

You can do this by selectively compiling using the above options,
into separate small libraries that you link into the single executable,
and use C++ namespaces to separate similar function calls.
Refer to the boinc/client/Makefile.am and client/whetstone.cpp, and client/cs_benchmark.cpp files
for an example of how to do this.

== Deploying Android app versions ==

BOINC on Android uses the following BOINC platform identifier:
"arm-android-linux-gnu"
"x86-android-linux-gnu"
"mipsel-android-linux-gnu"

(how to use plan classes if you have separate FPU versions)
The client reports CPU architecture and capabilities, i.e. VFP and NEON support, to the project server.

== Position-independent executables (PIE) ==
Starting with version 4.1, Android supports '''position-independent executables''' (PIE).
Starting with version 5.0, PIE is mandatory - Android refuses to run native executables
that are not PIE.

You can build PIE apps by including in your Makefile:
{{{
LOCAL_CFLAGS += -fPIE
LOCAL_LDFLAGS += -fPIE -pie
}}}

You should use plan classes so that
 * PIE versions are sent only to Android 4.1 or later devices.
 * non-PIE versions are sent only to pre-5.0 devices.

For example (using [AppPlanSpec XML plan class specification]):
{{{
<plan_class>
  <name>android_arm_pie</name>
  <min_android_version>40100</min_android_version>
</plan_class>

<plan_class>
  <name>android_arm_non_pie</name>
  <max_android_version>49999</max_android_version>
</plan_class>
}}}

If you have both PIE and non-PIE, change the 49999 to 40099.

== FORTRAN on Android NDK (optional build) ==

The Android NDK currently does not have a FORTRAN compiler distributed with it.
But it is possible to build GNU Fortran (gfortran) libraries for ARM/Android using the information at
[http://danilogiulianelli.blogspot.co.uk/2013/02/how-to-build-gcc-fortran-cross-compiler.html]

== Example ==
Setup the environment:
[http://boinc.berkeley.edu/trac/browser/boinc-v2/samples/example_app/build_android.sh]

Android Makefile: [http://boinc.berkeley.edu/trac/browser/boinc-v2/samples/example_app/Makefile_android]

An example of how to adapt a BOINC app's Makefile to compile it for Android
can be found in the BOINC sources at:
[https://github.com/novarow/AndroidBOINC/blob/master/native/diffs_android/uppercase/Makefile_android]

Note that the AndroidBOINC build script sets up the required environment
variables for the standard C++ library as well as the Android SYSROOT.

-llog refers to the library required to use Logcat from native code.
Logcat is used for debugging purposes and is not required for the app's functionality.