docs/HOWTO.TXT

   1 Android NDK How-To:
   2 ===================
   3
   4 A collection of tips and tricks for NDK users
   5
   6
   7 How to force the display of build commands:
   8 -------------------------------------------
   9
  10 Do "ndk-build V=1" and actual build commands will be
  11 displayed. This can be used to verify that things are compiled
  12 as you expect them to, and check for bugs in the NDK build system.
  13
  14 (The V=1 trick comes from the Linux kernel build system)
  15
  16
  17
  18 How to force a rebuild of all your sources:
  19 -------------------------------------------
  20
  21 Use GNU Make's "-B" option, as in:
  22
  23    ndk-build -B
  24
  25
  26 How to store your native sources in a location other than $PROJECT/jni:
  27 -----------------------------------------------------------------------
  28
  29 First, you can simply tell your $PROJECT/jni/Android.mk to include
  30 another Android.mk that are located in different places.
  31
  32 Alternatively, you can define APP_BUILD_SCRIPT in your Application.mk
  33 to point to an alternative Android.mk file.
  34
  35
  36 How to store your Application.mk in a location other than $NDK/app/<name>:
  37 --------------------------------------------------------------------------
  38
  39 Starting with NDK r4, you can simply place the file under $PROJECT/jni/
  40 and launch the 'ndk-build' script from your project tree.
  41
  42 If you want to use 'ndk-build' but place the file to a different location,
  43 use a GNU Make variable override as:
  44
  45     ndk-build NDK_APPLICATION_MK=/path/to/your/Application.mk
  46
  47 If you're using the legacy $NDK/apps/<name> build nethod, you can create
  48 a symbolic link to your final Application.mk there. For example, imagine
  49 that you wrote:
  50
  51   $PROJECT/foo/Application.mk
  52
  53 You can create a symlink like with a command like:
  54
  55   ln -s $PROJECT/foo  $NDK/apps/<name>
  56
  57 This will make $NDK/apps/<name>/Application.mk point directly to
  58 $PROJECT/jni/Application.mk
  59
  60 Note that generated files will still go under $NDK/out/apps/<name> though.
  61
  62 Windows users: The NDK is only supported on Cygwin, which implements
  63 symbolic links through the "ln -s" command, as in:
  64
  65     ln -s  <target>  <link>
  66
  67
  68 How to properly add include directories to your module declaration:
  69 -------------------------------------------------------------------
  70
  71 If you define several modules, it is common to need to include one
  72 module's header while compiling another one. For example, consider
  73 the following example:
  74
  75   $PROJECT/jni/foo/
  76     Android.mk
  77     foo.h
  78     foo.c
  79
  80   $PROJECT/jni/bar/
  81     Android.mk
  82     bar.c
  83
  84 Where the 'bar.c' uses '#include <foo.h>'. You will need to add the
  85 path to the 'foo' module in jni/bar/Android.mk to build it properly.
  86
  87 One is tempted to use the following:
  88
  89   LOCAL_C_INCLUDES := ../foo
  90
  91 However this will not work because all compilation happens from the
  92 directory where 'ndk-build' is invoked, and include files must be
  93 relative to it.
  94
  95 The correct line is instead:
  96
  97   LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo
  98
  99 Which uses a path relative to $(LOCAL_PATH), in the case where you would
 100 need to move 'foo' and 'bar' to a deeper level in the 'sources' hierarchy.
 101
 102 In case you absolutely need it, you can also use NDK_APP_PROJECT_PATH to
 103 point to your project directory:
 104
 105   LOCAL_C_INCLUDES := $(NDK_APP_PROJECT_PATH)/jni/foo
 106
 107 However, we don't recommend using this, paths relative to $(LOCAL_PATH)
 108 being better.
 109