Getting Started: Building for Android

1. Requirements
2. Build Preparation
3. Building PJSIP
4. Setting up the target device
5. Building and running pjsua sample application
6. Building and running pjsua2 sample application
   1. Log output
7. Debugging native code with Eclipse
8. Important Issue(s) when Developing Apps with Pjsua2 API
   1. Garbage Collector May Crash Your App
9. Other Android projects

Android target is currently only available in latest source code from repository. Follow the instructions for the trunk, the development branch has been merged and is not maintained.

Requirements

• Besides the ​Android SDK, you will also need the ​Android NDK (minimum version r8b).
• Optional if you want to build and and run the sample application PJSUA:
  • ​SWIG (minimum version 2.0.5)
  • Eclipse with ​ADT Plugin.
  • Telnet application to interact with PJSUA command line. If you are not familiar with telnet, please find a tutorial suitable for your development platform.

Build Preparation

1. Get the source code from repository, if you haven't already. This tutorial applies to PJSIP version 2.2 and above (or the 2.1 from SVN trunk dated 2013/04/24 or later).
2. Set your 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:

• to build for other targets, e.g: x86 or armv7, instead of just './configure-android', run

  TARGET_ABI=armeabi-v7a ./configure-android --use-ndk-cflags
  

• for some targets, there may be error like

  error: undefined reference to '__stack_chk_fail_local'
  

  this can be fixed by adding -fno-stack-protector into CFLAGS, e.g: via user.mak file.
• 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 Building with GNU page.

Setting up the target device

To run or debug application (such as the sample applications below), first we need to setup the target device:

• using virtual device: ​http://developer.android.com/tools/devices/index.html
• using real device: ​http://developer.android.com/tools/device.html

Building and running pjsua sample application

We have pjsua sample application located under pjsip-apps/src/pjsua/android. It is not built by default, and you need ​SWIG to build it.

Follow these steps to build pjsua:

1. Make sure SWIG is in the build environment PATH.
   • Alternatively, update SWIG path in $PJDIR/pjsip-apps/src/pjsua/android/jni/Android.mk file.
2. Run ndk-build from directory $PJDIR/pjsip-apps/src/pjsua/android (note that the Android NDK root should be in the PATH), e.g:

   $ cd /path/to/your/pjsip/dir
   $ cd pjsip-apps/src/pjsua/android
   $ ndk-build
   

3. Create Android project from pjsua. In Eclipse:
   1. From menu: File --> New --> Project
   2. Select Android Project from Existing Code, press Next
   3. In Root Directory, put the location of pjsua source code (i.e. $PJDIR/pjsip-apps/src/pjsua/android) and press Finish
4. You may need to select different Android SDK than what is configured in pjsua. You can do this from the project's Properties.
5. Run it.
6. You will see telnet instructions on the device's screen. Telnet to this address to operate the application. See PJSUA CLI Manual for command reference.

Building and running pjsua2 sample application

Another sample application, which is based on pjsua2 high-level API with SWIG binding, is located under pjsip-apps/src/swig/java/android. It is not built by default, and you need ​SWIG to build it.

Follow these steps to build pjsua2 sample application:

1. Make sure SWIG is in the build environment PATH.
2. Run make from directory $PJDIR/pjsip-apps/src/swig (note that the Android NDK root should be in the PATH), e.g:

   $ cd /path/to/your/pjsip/dir
   $ cd pjsip-apps/src/swig
   $ make
   

3. Create Android project from pjsua. In Eclipse:
   1. From menu: File --> New --> Project
   2. Select Android Project from Existing Code, press Next
   3. In Root Directory, put the location of pjsua2 source code (i.e. $PJDIR/pjsip-apps/src/swig/java/android) and press Finish
4. You may need to select different Android SDK than what is configured in pjsua2. You can do this from the project's Properties.
5. Run it.

Log output

The pjsua2 sample application will write log messages to LogCat window (to show LogCat window, from Eclipse menu: Window --> Show View --> Other --> type LogCat)

Debugging native code with Eclipse

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.
2. Make sure that the JNI part of the application is built using ndk-build. For reference, check pjsua's Android.mk build config in pjsip-apps/src/pjsua/android/jni, it contains sample of how to import PJSIP build settings (build search paths, build flags, etc) and SWIG invocation.
3. Enable NDK plugin for Eclipse, check ​this and follow the instructions.
   • CDT can also be fetched from ​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.
4. 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
   // ...
   

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

Important Issue(s) when Developing Apps with Pjsua2 API

Garbage Collector May Crash Your App

There are two problems with Java garbage collector (gc):

• it delays the destruction of Java objects (including pjsua2 objects), causing the code in object's destructor to be executed out of order
• the gc operation may be run on different thread, not previously registered to PJLIB

Due to problems above, application MUST immediately destroy pjsua2 objects using object's delete() method, instead of relying on the gc to clean up the object.

For example, to delete an Account:

acc.delete();

Other Android projects

Also have a look at the following PJSIP Android project:

• ​csipsimple project, an Android port of pjsip.