= Getting Started: Building for Android =
[[TracNav(Getting-Started/TOC)]]
[[PageOutline(2-3,,inline)]]


Android target is currently available in [https://svn.pjsip.org/repos/pjproject/branches/projects/android Android branch] and currently still experimental.

== Requirements ==

 * Besides the [http://developer.android.com/sdk/index.html Android SDK], you will also need the [http://developer.android.com/tools/sdk/ndk/index.html Android NDK].
 * Optional: [http://www.swig.org/download.html SWIG] if you want to build the sample application apjsua.

== Build Preparation ==

 1. [wiki:Getting-Started/Download-Source Get the source code], if you haven't already.
 2. Set your [wiki:Getting-Started/Build-Preparation config_site.h] to the following:
  {{{
#define PJ_CONFIG_ANDROID 1
#include <pj/config_site_sample.h>
  }}}
  This will activate Android specific settings in the {{{config_site_sample.h}}}.

== Building PJSIP ==

Just run:
 {{{
$ cd /path/to/your/pjsip/dir
$ export ANDROID_NDK_ROOT=/path_to_android_ndk_dir 
$ ./configure-android
$ make dep && make clean && make
 }}}

Notes:
 * the {{{./configure-android}}} is a wrapper that calls the standard {{{./configure}}} script with settings suitable for Android target.
 * you may pass standard {{{./configure}}} options to this script too.
 * for more info, run {{{./configure-android --help}}}
 * other customizations are similar to what is explained in [wiki:Getting-Started/Autoconf Building with GNU] page.

== Building and running apjsua sample application == #apjsua

We have apjsua sample application located under {{{pjsip-apps/src/apjsua}}}. It is not built by default, and you need [http://www.swig.org/download.html SWIG] to build it.

Follow these steps to build apjsua:
 1. Make sure SWIG is in the build environment PATH.
     - Alternatively, update SWIG path in {{{$PJDIR/pjsip-apps/src/apjsua/jni/Android.mk}}} file.
 1. Run {{{ndk-build}}} from directory {{{$PJDIR/pjsip-apps/src/apjsua}}}, note that the Android NDK root should be in the PATH, e.g:
     {{{
$ cd /path/to/your/pjsip/dir
$ cd pjsip-apps/src/apjsua
$ ndk-build
     }}}
 1. Create Android project from apjsua. In Eclipse:
    a. From menu: '''File''' --> '''New''' --> '''Project'''
    a. Select '''Android Project from Existing Code''', press '''Next'''
    a. In ''Root Directory'', put the location of '''apjsua''' source code (i.e. {{{$PJDIR/pjsip-apps/src/apjsua}}}) and press '''Finish'''
 1. You may need to select different Android SDK than what is configured in apjsua. You can do this from the project's '''Properties'''.
 1. You can modify {{{apjsua/res/raw/config.txt}}} for apjsua's config file.
 1. Run it.


== Debugging native code with Eclipse == #debug-native

Here are the steps for debugging PJSIP native code using Eclipse:
 1. Build PJSIP with debugging enabled, e.g: insert {{{CFLAGS += -g}}} into {{{user.mak}}} in PJSIP root directory.
 1. Make sure that the JNI part of the application is built using {{{ndk-build}}}. For reference, check apjsua's {{{Android.mk}}} build config in {{{pjsip-apps/src/apjsua/jni}}}, it contains sample of how to import PJSIP build settings (build search paths, build flags, etc) and SWIG invocation.
 1. Enable NDK plugin for Eclipse, check [http://tools.android.com/recent/usingthendkplugin this] and follow the instructions.
     - CDT can also be fetched from [http://www.eclipse.org/cdt/downloads.php CDT download page], normally Eclipse for C/C++ will have CDT installed, just make sure that the CDT version is 7.0.2 or newer.
 1. It is recommended to introduce delay (about 5 seconds) in the application code between loading the native code library and calling any native functions (to be debugged), e.g:
     {{{
try {
	System.loadLibrary("some_native_lib.so");
} catch (UnsatisfiedLinkError e) {
	return -1;
}

// Wait for GDB init
if ((getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
	try {
		Thread.sleep(5000);
        } catch (InterruptedException e) { }
}

// Start calling native functions here
// ...
     }}}
 1. Load the PJSIP project to Eclipse (if not yet), and try put breakpoint anywhere in the PJSIP code before launching the Android application debug configuration in Eclipse.



== Other Android projects ==

Also have a look at the following PJSIP Android project:
 * [http://code.google.com/p/csipsimple/ csipsimple] project, an Android port of pjsip.