Instructions for users of libraries

This document explains how to use Librairies that have been packages according to the Best Practices for authors of libraries.
Feedback is very welcome ! If something is not clear, please ask me !

Requirements

  • You must have installed the SDK and the NDK.
    On Unix-like systems it is as simple as downloading the corresponding archives and then running the "$SDK/tools/android" command to install the desired APIs. If many people ask for this, I'll try to provide more complete instructions.
  • You must know how to build a simple program with the NDK build system.
    Explaining how to build an Android program is outside the scope of this document, but if many people ask for it, I'll try to provide more complete instructions.

5 easy steps

So now you've got everything setup. Running "ndk-build" does its magic, except that it cannot find the libraries.
Here is how to help it finding them.
  1. Create a "libraries" directory. This directory will contain all the Android libraries you use.
    I suggest creating it outside of your project's directory so that you can share it among your projects and only have one copy of the libraries on your machine, but that is a matter of taste.
    Another nice option, if you are using Git, is to create it as a collection of Git submodules. Mercurial users would probably use subrepositories for a similar result.
  2. Add the "libraries" directory to the NDK_MODULE_PATH environment variable.
    On Unix, this can be done by adding
    export NDK_MODULE_PATH=INSERT_FULL_PATH_TO_THE_DIRECTORY
    to the .profile file in your home directory .
  3. Download and extract the library.
    Please extract it as a subdirectory of your "libraries" directory, and check that it contains a file named Android.mk .
    If this library use a custom build system, you may have to perform additional steps here. Please refer to the library's documentation. For most libraries, this should not be the case.
  4. Find the library module name.
    It should be mentioned in the library's documentation. If it is not, just open the Android.mk file and search for a line like:
    LOCAL_MODULE := MODULE_NAME
    MODULE_NAME is the name of this module.
    Rename the subdirectory of your "libraries" directories that contain the source code for the library so that it is named MODULE_NAME.
  5. Add those lines to your own Android.mk.
    LOCAL_SHARED_LIBRARIES := MODULE_NAME
    $(call import-module,MODULE_NAME)
    If you already use a library, add the new module name to the existing one, separating them with spaces:
    LOCAL_SHARED_LIBRARIES := EXISTING_MODULE_NAME MODULE_NAME
    $(call import-module,EXISTING_MODULE_NAME)
    $(call import-module,MODULE_NAME)

Enable support for exceptions or for the STL

The library author might ask in the documentation that you enable the support for exceptions, or for the STL, or for both.
In order to do so, create an Application.mk file in the jni directory and add the following lines :
  • STL and no Exceptions
    APP_STL := stlport_static
  • STL and/or Exceptions
    APP_STL := gnustl_static
    APP_CPPFLAGS += -fexceptions 
Alternatively, you can build the STL as a shared library and load it explicitely in your program. Please refer to CPLUSPLUS-SUPPORT.html in the NDK documentation for more information on this matter.
Comments