ndk/docs/APPLICATION-MK.html

   1 <html><body><pre>Application.mk file syntax specification
   2
   3 Introduction:
   4 -------------
   5
   6 This document describes the syntax of Application.mk build files
   7 written to describe the native modules required by your Android
   8 application. To understand what follows, it is assumed that you have
   9 read the docs/OVERVIEW.html file that explains their role and
  10 usage.
  11
  12 Readers of this document should have read docs/OVERVIEW.html and
  13 docs/ANDROID-MK.html
  14
  15
  16 Overview:
  17 ---------
  18
  19 The purpose of Application.mk is to describe which native
  20 'modules' (i.e. static/shared libraries) are needed by your
  21 application.
  22
  23 An Application.mk file is usually placed under $PROJECT/jni/Application.mk,
  24 where $PROJECT points to your application's project directory.
  25
  26 Another alternative is to place it under a sub-directory of the top-level
  27 $NDK/apps directory, e.g.:
  28
  29    $NDK/apps/&lt;myapp&gt;/Application.mk
  30
  31 Where &lt;myapp&gt; is a short name used to describe your 'application'
  32 to the NDK build system (this name doesn't go into your generated
  33 shared libraries or your final packages).
  34
  35 The Application.mk is really a tiny GNU Makefile fragment that must
  36 define a few variables:
  37
  38 APP_PROJECT_PATH
  39     This variable should give the *absolute* path to your
  40     Application's project root directory. This is used to copy/install
  41     stripped versions of the generated JNI shared libraries to a
  42     specific location known to the APK-generating tools.
  43
  44     Note that it is optional for $PROJECT/jni/Application.mk, but
  45     *mandatory* for $NDK/apps/&lt;myapp&gt;/Application.mk
  46
  47 APP_MODULES
  48     This variable is optional. If not defined, the NDK will build by
  49     default _all_ the modules declared by your Android.mk, and any
  50     sub-makefile it may include.
  51
  52     If APP_MODULES is defined, it must be a space-separated list of module
  53     names as they appear in the LOCAL_MODULE definitions of Android.mk
  54     files. Note that the NDK will compute module dependencies automatically.
  55
  56     NOTE: This variable's behaviour changed in NDK r4. Before that:
  57
  58       - the variable was mandatory in your Application.mk
  59       - all required modules had to be listed explicitly.
  60
  61 APP_OPTIM
  62     This optional variable can be defined to either 'release' or
  63     'debug'. This is used to alter the optimization level when
  64     building your application's modules.
  65
  66     A 'release' mode is the default, and will generate highly
  67     optimized binaries. The 'debug' mode will generate un-optimized
  68     binaries which are much easier to debug.
  69
  70     Note that if your application is debuggable (i.e. if your manifest
  71     sets the android:debuggable attribute to "true" in its &lt;application&gt;
  72     tag), the default will be 'debug' instead of 'release'. This can
  73     be overridden by setting APP_OPTIM to 'release'.
  74
  75     Note that it is possible to debug both 'release' and 'debug'
  76     binaries, but the 'release' builds tend to provide less information
  77     during debugging sessions: some variables are optimized out and
  78     can't be inspected, code re-ordering can make stepping through
  79     the code difficult, stack traces may not be reliable, etc...
  80
  81 APP_CFLAGS
  82     A set of C compiler flags passed when compiling any C or C++ source code
  83     of any of the modules. This can be used to change the build of a given
  84     module depending on the application that needs it, instead of modifying
  85     the Android.mk file itself.
  86
  87     IMPORTANT WARNING: +++++++++++++++++++++++++++++++++++++++++++++++++++
  88     +
  89     + All paths in these flags should be relative to the top-level NDK
  90     + directory. For example, if you have the following setup:
  91     +
  92     +    sources/foo/Android.mk
  93     +    sources/bar/Android.mk
  94     +
  95     +  To specify in foo/Android.mk that you want to add the path to the
  96     + 'bar' sources during compilation, you should use:
  97     +
  98     +   APP_CFLAGS += -Isources/bar
  99     +
 100     + Or alternatively:
 101     +
 102     +   APP_CFLAGS += -I$(LOCAL_PATH)/../bar
 103     +
 104     + Using '-I../bar' will *NOT* work since it will be equivalent to
 105     + '-I$NDK_ROOT/../bar' instead.
 106     +
 107     +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 108
 109     NOTE: In android-ndk-1.5_r1, this only applied to C sources, not C++ ones.
 110           This has been corrected to match the full Android build system.
 111
 112 APP_CXXFLAGS
 113     An alias for APP_CPPFLAGS, to be considered obsolete as it may disappear
 114     in a future release of the NDK.
 115
 116 APP_CPPFLAGS
 117     A set of C++ compiler flags passed when building C++ sources *only*.
 118
 119     NOTE: In android-ndk-1.5_r1, this applied to both C and C++ sources.
 120           This has been corrected to match the full Android build system.
 121           You can now use APP_CFLAGS for flags that shall apply to C and
 122           C++ sources.
 123
 124 APP_BUILD_SCRIPT
 125     By default, the NDK build system will look for a file named Android.mk
 126     under $(APP_PROJECT_PATH)/jni, i.e. for the file:
 127
 128        $(APP_PROJECT_PATH)/jni/Android.mk
 129
 130     If you want to override this behaviour, you can define APP_BUILD_SCRIPT
 131     to point to an alternate build script. A non-absolute path will always
 132     be interpreted as relative to the NDK's top-level directory.
 133
 134 APP_ABI
 135     By default, the NDK build system will generate machine code for the
 136     'armeabi' ABI. This corresponds to an ARMv5TE based CPU with software
 137     floating point operations. You can use APP_ABI to select a different
 138     ABI.
 139
 140     For example, to support hardware FPU instructions on ARMv7 based devices,
 141     use:
 142
 143         APP_ABI := armeabi-v7a
 144
 145     Or to support both ARMv5TE and ARMv7 based devices, use:
 146
 147         APP_ABI := armeabi armeabi-v7a
 148
 149     For the list of all supported ABIs and details about their usage and
 150     limitations, please read docs/CPU-ARCH-ABIS.html
 151
 152 APP_STL
 153     By default, the NDK build system provides C++ headers for the minimal
 154     C++ runtime library (/system/lib/libstdc++.so) provided by the Android
 155     system.
 156
 157     However, the NDK comes with alternative C++ implementations that you can
 158     use or link to in your own applications. Define APP_STL to select one of
 159     them. Examples are:
 160
 161        APP_STL := stlport_static    --> static STLport library
 162        APP_STL := stlport_shared    --> shared STLport library
 163        APP_STL := system            --> default C++ runtime library
 164
 165     For more information on the subject, please read docs/CPLUSPLUS-SUPPORT.html
 166
 167 A trivial Application.mk file would be:
 168
 169 -------------- cut here -------------------------
 170 APP_PROJECT_PATH := &lt;path to project&gt;
 171 -------------- cut here -------------------------
 172 </pre></body></html>