HOW TO BUILD CSOUND 6 FOR ANDROID

=================================

Michael Gogins, Steven Yi

5 July 2013

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

SETTING UP THE TOOLCHAIN

========================

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

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 the Android SDK from http://developer.android.com/sdk/index.html.

Use the Eclipse version.

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
and LuaJIT.

In your MSys shell, you 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, armeabi-v7a (ARMv7 VFP), Android 2.3.3)..."

export SDK=/d/Android/adt-bundle-windows-x86-20130514/sdk
export NDK=/d/Android/android-ndk-r8e
export ANDROID_NDK_ROOT=$NDK
export CSOUND_HOME=/c/Users/new/csound-csound6-git
export NDK_MODULE_PATH=${CSOUND_HOME}/android/pluginlibs
export PATH=${PATH}:$NDK_MODULE_PATH
export NDKABI=9
export NDKVER=$NDK/toolchains/arm-linux-androideabi-4.7
export NDKP=$NDKVER/prebuilt/windows/bin/arm-linux-androideabi-
export NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
export NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8"

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 (LuaJIT, Fluidsynth, and
libsndfile). It will also patch projects so that they can be used together
with the plugin libraries.

2. build-all.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
will be compiled.

MANUALLY BUILDING THE CSOUND PROJECTS

=====================================

To save build time, 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

BUILD THE LUAJIT MODULE (OPTIONAL, REQUIRED BY LUACSOUND OPCODES)

LuaJIT is a version of the excellent lightweight dynamic language Lua,

extended with a just-in-time (JIT) compiler that runs Lua code as fast as
compiled C code, and with a highly useful foreigh function interface (FFI).

Change to $(NDK_MODULE_PATH) and use Git to clone the LuaJIT head there.
Change to the LuaJIT directory and execute:

make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH"

TARGET_SYS=linux
BUILD AND INSTALL LUA OPCODES (OPTIONAL, USEFUL FOR ALGORITHMIC COMPOSITION IN
CSOUND)

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

$NDK/ndk-build

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

=============================

Configure Eclipse for the Android SDK and for the Android NDK.

Run Eclipse and load the $(CSOUND_SRC_ROOT)/android project directories:

CSDPlayer
CsoundAndroid
CsoundAndroidExamples

Make sure that the project.properties files are consistent with the
environment variables about the Android configuration, e.g. if $NDKABI is 9,
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-10.

Clean the projects (this should rebuild them).

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