Android NDK How-To:
===================

A collection of tips and tricks for NDK users


How to force the display of build commands:
-------------------------------------------

Do "make APP=<yourapp> V=1" and actual build commands will be
displayed. This can be used to verify that things are compiled
as you expect them to, and check for bugs in the NDK build system.

(The V=1 trick comes from the Linux kernel build system)



How to force a rebuild of all your sources:
-------------------------------------------

Use GNU Make's "-B" option, as in:

   make APP=<yourapp> -B


How to store your native sources in under your project's path:
--------------------------------------------------------------

It is often more convenient to store your native sources at a
different location than $NDK_ROOT/sources. For example, you would
typically place them under the same directory than your other project
files, to keep everything under source control, etc...

The NDK build system needs to access the sources from $NDK_ROOT/sources
and your Application.mk from $NDK_ROOT/apps/<name>. This is essentially
to keep its implementation sane and simple, and to ensure that certain
features, like automatic dependency management, work reliably.

You can however use simple symlinks to redirect paths to your project's
storage location. For example:

   $NDK_ROOT/sources/<foo>  ---->  $PROJECT_PATH/jni/<foo>
   $NDK_ROOT/apps/<foo>     ---->  $PROJECT_PATH/jni/<foo>

Where $PROJECT_PATH/jni/<foo> contains both an Android.mk and an
Application.mk. Note that things like $(call my-dir) will always evaluate
to the NDK paths (i.e. $NDK_ROOT/sources/<foo>) at build time.

Windows users: The NDK is only supported on Cygwin, which implements
symbolic links through the "ln -s" command, as in:

    ln -s  <target>  <link>


How to properly add include directories to your module declaration:
-------------------------------------------------------------------

If you define several modules, it is common to need to include one
module's header while compiling another one. For example, consider
the following example:

  $NDK_ROOT/sources/foo/
    Android.mk
    foo.h
    foo.c

  $NDK_ROOT/sources/bar/
    Android.mk
    bar.c

Where the 'bar.c' uses '#include <foo.h>'. You will need to add the
path to the 'foo' module in bar/Android.mk to build it properly.

One is tempted to use the following:

  LOCAL_C_INCLUDES := ../foo

However this will not work because all compilation happens from the
root NDK directory (i.e. $NDK_ROOT), and include files must be relative
to it. The above line really translates to:

  LOCAL_C_INCLUDES := $(NDK_ROOT)/../foo

Which adds a non-existing directory to the C include path. The correct
line is instead:

  LOCAL_C_INCLUDES := sources/foo

Or even better:

  LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo

Which uses a path relative to $(LOCAL_PATH), in the case where you would
need to move 'foo' and 'bar' to a deeper level in the 'sources' hierarchy.