HOW TO BUILD CSOUND 6 FOR ANDROID
=================================

Michael Gogins, Steven Yi
5 September 2016

Csound 6 for Android includes the Csound library for Android, the Csound6
app front end ("Csound for Android") for the library, an app containing 
several demos of thelibrary, and some plugins for Csound.


SETTING UP THE TOOLCHAIN
========================

These instructions are for Linuxs, but should mostly apply on
other platforms as well. You need the following tools.

For Windows, install MinGW/MSys from mingw.org. See How_to_Build_Csound_on_Windows.doc in
the Csound 6 Git repository for how to set up the MinGW tools. On Linux, just
install recent gcc/g++ packages. For OS X, install Xcode.

Install Android Studio from https://developer.android.com/studio/index.html.

Install the Android Native Development Kit (NDK) from
http://developer.android.com/tools/sdk/ndk/index.html.


SETTING UP THE CSOUND PROJECTS
==============================

Clone the Csound 6 Git repository somewhere by executing:

git clone git://git.code.sf.net/p/csound/csound6-git csound-csound6-git

In the android directory, execute ./downloadDependencies.sh. This will
use git to clone or pull source code for libsndfile, which is required by
Csound, and for other optional third party libraries such as Fluidsynth.

In your operating system shell, you should use the following shell script or other
facility to set the environment variables that are used by the Android build:

echo "Configure for Android/ARM..."

export CSOUND_HOME=/c/Users/mike/csound-csound6-git
export SDK=/d/android/adt-bundle-windows-x86-20140702
export ANDROID_NDK_ROOT=$NDK
export NDK=/home/mkg/android-ndk-r12
export NDKP=/home/mkg/android-ndk-r12/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi-
export NDK_MODULE_PATH=/home/mkg/csound/csound/android/pluginlibs
export ANDROID_NDK_ROOT=/home/mkg/android-ndk-r12
export NDKF=--sysroot /home/mkg/android-ndk-r12/platforms/android-19/arch-arm
export NDKARCH=-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8
export NDKABI=19
export NDKVER=/home/mkg/android-ndk-r12/toolchains/arm-linux-androideabi-4.9


AUTOMATED BUILDING OF CSOUND LIBRARY AND PLUGINS
================================================

Once the above environment variables are set, you can use the following
scripts to build the Csound library as well as plugin libraries:

1. downloadDependencies.sh: Running this script will download the libraries
that libcsound and the plugin libs depend on (Fluidsynth and
libsndfile). It will also patch projects so that they can be used together
with the plugin libraries.

2. build-all-mkg.sh: This script will go through all of the plugin libraries
and call ndk-build to build them, as well as go into the CsoundAndroid folder
to build libcsound.  After running this script, all native parts of Csound
should be compiled, and the libraries will be copied to the appropriate target 
lib directories.

MANUALLY BUILDING THE CSOUND PROJECTS
=====================================

Most native libraries are built as NDK modules so as
to be available as pre-built shared libraries. The complete build
may be outlined as follows.

NOTE: It is convenient if all NDK modules built or used by this
project are located in the project's pluginlibs directory. Any new modules
placed here must of course have unique directories that do not conflict with
existing directories. The build environment must set the NDK_MODULE_PATH
environment variable to the complete pluginlibs path.

The plugin projects are built before Csound itself, because Csound
requires the libsndfile shared library, which is built by the libstdutil
module.

BUILD THE LIBSTDUTIL MODULE (REQUIRED BY CSOUND)

This will also build libsndfile for Android.

Change to $(CSOUND_SRC_ROOT)/android/pluginlibs/libstdutil/jni and execute:

    $NDK/ndk-build

BUILD THE FLUIDSYNTH MODULE (RECOMMENDED FOR CSOUND)

Change to $(CSOUND_SRC_ROOT)/android/pluginlibs/libfluidsynth/jni and execute:

    $NDK/ndk-build

You may need to touch config.h first.

BUILD THE CSOUND NATIVE LIBRARY FOR ANDROID

Change to $(CSOUND_SRC_ROOT)/android/CsoundAndroid and execute:

    ./build.sh

This will call SWIG to generate Java bindings to the NDK module for Csound 6,
then build and install the Csound 6 CsoundAndroid module.

This script will also call install_libs.sh (which can be run separately) to
install the above-mentioned local shared libraries in the CsoundAndroid
libs directory, so that they will be included in the .apk file.


BUILD THE CSOUND ANDROID APPS
=============================

Run Android Studio and open the CsoundForAndroid/build.gradle file.

Make sure that the project.properties files are consistent with the
environment variables about the Android configuration, e.g. if $NDKABI is 19,
then (a) the Android target version must be available when you inspect the
Android SDK Manager configuration tool, and (b) the properties files must
specify a target equal to or higher than the than $NDKABI, e.g. on my system
it is target=android-21.

Clean the projects (this should rebuild them).

Connect your ARMv7 Android 5.0 or higher device to Eclipse with a USB cable. Run
the Csound6 project. This wll create the .apk file as well.