1`Application.mk` file syntax specification 2 3Introduction: 4------------- 5 6This document describes the syntax of `Application.mk` build files 7written to describe the native modules required by your Android 8application. To understand what follows, it is assumed that you have 9read the [OVERVIEW](OVERVIEW.html) file that explains their role and 10usage. 11 12Readers of this document should have read [OVERVIEW](OVERVIEW.html) and 13[ANDROID-MK](ANDROID-MK.html). 14 15 16Overview: 17--------- 18 19The purpose of `Application.mk` is to describe which native 20'modules' (i.e. static/shared libraries) are needed by your 21application. 22 23An `Application.mk` file is usually placed under `$PROJECT/jni/Application.mk`, 24where `$PROJECT` points to your application's project directory. 25 26Another alternative is to place it under a sub-directory of the top-level 27`$NDK/apps` directory, e.g.: 28 29 $NDK/apps/<myapp>/`Application.mk` 30 31Where <myapp> is a short name used to describe your 'application' 32to the NDK build system (this name doesn't go into your generated 33shared libraries or your final packages). 34 35The `Application.mk` is really a tiny GNU Makefile fragment that must 36define a few variables: 37 38- - - - 39APP_PROJECT_PATH 40> This variable should give the *absolute* path to your 41> Application's project root directory. This is used to copy/install 42> stripped versions of the generated JNI shared libraries to a 43> specific location known to the APK-generating tools. 44> 45> Note that it is optional for `$PROJECT/jni/Application.mk`, but 46> *mandatory* for `$NDK/apps/<myapp>/Application.mk` 47 48- - - - 49APP_MODULES 50> If this variable is defined, it tells `ndk-build` to only list the 51> corresponding modules and those that they depend on. It must be a 52> space-separated list of module names as they appear in the 53> LOCAL_MODULE definition of Android.mk files. 54> 55> It the variable is undefined, `ndk-build` looks for the list of all 56> _installable_ top-level modules, i.e. those listed by your Android.mk 57> and any file it includes directly. Imported modules are _not_ top-level 58> though. 59> 60> An installable module is either a shared library or executable, which 61> will generate a file in `libs/$ABI/`. 62> 63> If the variable is undefined, and there are no installable top-level 64> modules in your project, then `ndk-build` will build all top-level 65> static libraries and their dependencies instead. However, these 66> libraries will be placed at the usual location under `obj/` or 67> `obj-debug/`. 68> 69> NOTE: This variable's behaviour changed in NDK r4. Before that: 70> 71> - the variable was mandatory in your `Application.mk` 72> - all required modules had to be listed explicitly. 73 74- - - - 75APP_OPTIM 76> This optional variable can be defined to either '`release`' or 77> '`debug`'. This is used to alter the optimization level when 78> building your application's modules. 79> 80> A 'release' mode is the default, and will generate highly 81> optimized binaries. The 'debug' mode will generate un-optimized 82> binaries which are much easier to debug. 83> 84> Note that if your application is debuggable (i.e. if your manifest 85> sets the `android:debuggable` attribute to "`true`" in its `<application>` 86> tag), the default will be 'debug' instead of 'release'. This can 87> be overridden by setting APP_OPTIM to '`release`'. 88> 89> Note that it is possible to debug both 'release' and 'debug' 90> binaries, but the 'release' builds tend to provide less information 91> during debugging sessions: some variables are optimized out and 92> can't be inspected, code re-ordering can make stepping through 93> the code difficult, stack traces may not be reliable, etc... 94 95- - - - 96APP_CFLAGS 97> A set of C compiler flags passed when compiling any C or C++ source code 98> of any of the modules. This can be used to change the build of a given 99> module depending on the application that needs it, instead of modifying 100> the Android.mk file itself. 101> 102 IMPORTANT WARNING: +++++++++++++++++++++++++++++++++++++++++++++++++++ 103 + 104 + All paths in these flags should be relative to the top-level NDK 105 + directory. For example, if you have the following setup: 106 + 107 + sources/foo/Android.mk 108 + sources/bar/Android.mk 109 + 110 + To specify in foo/Android.mk that you want to add the path to the 111 + 'bar' sources during compilation, you should use: 112 + 113 + APP_CFLAGS += -Isources/bar 114 + 115 + Or alternatively: 116 + 117 + APP_CFLAGS += -I$(LOCAL_PATH)/../bar 118 + 119 + Using '-I../bar' will *NOT* work since it will be equivalent to 120 + '-I$NDK_ROOT/../bar' instead. 121 + 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 123 124> NOTE: In android-ndk-1.5_r1, this only applied to C sources, not C++ ones. 125> This has been corrected to match the full Android build system. 126 127- - - - 128APP_CXXFLAGS 129> An alias for APP_CPPFLAGS, to be considered obsolete as it may disappear 130> in a future release of the NDK. 131 132- - - - 133APP_CPPFLAGS 134> A set of C++ compiler flags passed when building C++ sources *only*. 135> 136> NOTE: In android-ndk-1.5_r1, this applied to both C and C++ sources. 137> This has been corrected to match the full Android build system. 138> You can now use APP_CFLAGS for flags that shall apply to C and 139> C++ sources. 140 141- - - - 142APP_LDFLAGS 143> A set of linker flags passed when linking application. This only 144> applies when building shared libraries and executables, these 145> flags are ignored when building static libraries. 146 147- - - - 148APP_BUILD_SCRIPT 149> By default, the NDK build system will look for a file named Android.mk 150> under `$(APP_PROJECT_PATH)/jni`, i.e. for the file: 151 152 $(APP_PROJECT_PATH)/jni/Android.mk 153 154> If you want to override this behaviour, you can define APP_BUILD_SCRIPT 155> to point to an alternate build script. A non-absolute path will always 156> be interpreted as relative to the NDK's top-level directory. 157 158- - - - 159APP_ABI 160> By default, the NDK build system will generate machine code for the 161> '`armeabi`' ABI. This corresponds to an ARMv5TE based CPU with software 162> floating point operations. You can use APP_ABI to select a different 163> ABI. 164> 165> For example, to support hardware FPU instructions on ARMv7 based devices, 166> use: 167 168 APP_ABI := armeabi-v7a 169 170> Or to support the IA-32 instruction set, use: 171 172 APP_ABI := x86 173 174> Or to support the MIPS instruction set, use: 175 176 APP_ABI := mips 177 178> Or to support all at the same time, use: 179 180 APP_ABI := armeabi armeabi-v7a x86 mips 181 182> Or even better, since NDK r7, you can also use the special value 183> '`all`' which means "all ABIs supported by this NDK release": 184 185 APP_ABI := all 186 187> For the list of all supported ABIs and details about their usage and 188> limitations, please read [CPU-ARCH-ABIS](CPU-ARCH-ABIS.html). 189 190- - - - 191APP_PLATFORM 192> Name the target Android platform. For example, '`android-3`' correspond 193> to Android 1.5 system images. For a complete list of platform names and 194> corresponding Android system images, read [STABLE-APIS](STABLE-APIS.html). 195 196- - - - 197APP_STL 198> By default, the NDK build system provides C++ headers for the minimal 199> C++ runtime library (`/system/lib/libstdc++.so`) provided by the Android 200> system. 201> 202> However, the NDK comes with alternative C++ implementations that you can 203> use or link to in your own applications. Define APP_STL to select one of 204> them. Examples are: 205 206 APP_STL := stlport_static --> static STLport library 207 APP_STL := stlport_shared --> shared STLport library 208 APP_STL := system --> default C++ runtime library 209 210> For more information on the subject, please read [CPLUSPLUS-SUPPORT](CPLUSPLUS-SUPPORT.html). 211 212- - - - 213APP_GNUSTL_FORCE_CPP_FEATURES 214> In prior NDK versions, the simple fact of using the GNU libstdc++ 215> runtime (i.e. by setting APP_STL to either '`gnustl_static`' or 216> '`gnustl_shared`') enforced the support for exceptions and RTTI in all 217> generated machine code. This could be problematic in specific, but rare, 218> cases, and also generated un-necessarily bigger code for projects that 219> don't require these features. 220> 221> This bug was fixed in NDK r7b, but this means that if your code requires 222> exceptions or RTTI, it should now explicitly say so, either in your 223> APP_CPPFLAGS, or your LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES definitions. 224> 225> To make it easier to port projects to NDK r7b and later, one can 226> optionally defined APP_GNUSTL_CPP_FEATURES to contain one or more of the 227> following values: 228 229 exceptions -> to enforce exceptions support for all modules. 230 rtti -> to enforce rtti support for all modules. 231 232> For example, to get the exact same behaviour than NDK r7: 233 234 APP_GNUSTL_FORCE_CPP_FEATURES := exceptions rtti 235 236> IMPORTANT: This variable is provided here as a convenience to make it 237> easier to transition to a newer version of the NDK. It will 238> be removed in a future revision. We thus encourage all 239> developers to modify the module definitions properly instead 240> of relying on it here. 241 242- - - - 243APP_SHORT_COMMANDS 244> The equivalent of LOCAL_SHORT_COMMANDS for your whole project. See the 245> documentation for this variable in [ANDROID-MK](ANDROID-MK.html). 246 247- - - - 248NDK_TOOLCHAIN_VERSION 249> Define this variable to either 4.6, 4.7 or 4.8 to select version of 250> the GCC compiler. 4.6 is the default 251 252- - - - 253APP_PIE 254> Starting from Jelly Bean (4.1), Android's dynamic linker supports 255> position-independent executables (PIE), which are built with `-fPIE`. 256> This flag makes it harder to exploit memory corruption bugs by 257> randomization the location of the code. 258> By default, `ndk-build` will automatically set this value to '`true`' if 259> your project targets `android-16` or higher. You may set it manually 260> to either '`true`' or '`false`'. 261> 262> IMPORTANT: PIE executables *cannot* run on Android releases prior to 4.1. 263> 264> Note that this only applies to executables. It has no effect when 265> building shared or static libraries. 266 267- - - - 268APP_THIN_ARCHIVE 269> Sets the default value of LOCAL_THIN_ARCHIVE for all static library 270> modules in this project. For more information, see the documentation 271> for LOCAL_THIN_ARCHIVE in [ANDROID-MK](ANDROID-MK.html). 272 273- - - - 274A trivial `Application.mk` file would be: 275 276 -------------- cut here ------------------------- 277 APP_PROJECT_PATH := <path to project> 278 -------------- cut here ------------------------- 279 280