1 `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 [OVERVIEW](OVERVIEW.html) file that explains their role and 10 usage. 11 12 Readers of this document should have read [OVERVIEW](OVERVIEW.html) and 13 [ANDROID-MK](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/<myapp>/`Application.mk` 30 31 Where <myapp> 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 - - - - 39 APP_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 - - - - 49 APP_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 - - - - 75 APP_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 - - - - 96 APP_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 - - - - 128 APP_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 - - - - 133 APP_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 - - - - 142 APP_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 - - - - 148 APP_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 - - - - 159 APP_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 Intel64 instruction set, use: 175 176 APP_ABI := x86-64 177 178 > Or to support the MIPS instruction set, use: 179 180 APP_ABI := mips 181 182 > Or to support all at the same time, use: 183 184 APP_ABI := armeabi armeabi-v7a x86 mips x86-64 185 186 > Or even better, since NDK r7, you can also use the special value 187 > '`all`' which means "all ABIs supported by this NDK release": 188 189 APP_ABI := all 190 191 > For the list of all supported ABIs and details about their usage and 192 > limitations, please read [CPU-ARCH-ABIS](CPU-ARCH-ABIS.html). 193 194 - - - - 195 APP_PLATFORM 196 > Name the target Android platform. For example, '`android-3`' correspond 197 > to Android 1.5 system images. For a complete list of platform names and 198 > corresponding Android system images, read [STABLE-APIS](STABLE-APIS.html). 199 200 - - - - 201 APP_STL 202 > By default, the NDK build system provides C++ headers for the minimal 203 > C++ runtime library (`/system/lib/libstdc++.so`) provided by the Android 204 > system. 205 > 206 > However, the NDK comes with alternative C++ implementations that you can 207 > use or link to in your own applications. Define APP_STL to select one of 208 > them. Examples are: 209 210 APP_STL := stlport_static --> static STLport library 211 APP_STL := stlport_shared --> shared STLport library 212 APP_STL := system --> default C++ runtime library 213 214 > For more information on the subject, please read [CPLUSPLUS-SUPPORT](CPLUSPLUS-SUPPORT.html). 215 216 - - - - 217 APP_GNUSTL_FORCE_CPP_FEATURES 218 > In prior NDK versions, the simple fact of using the GNU libstdc++ 219 > runtime (i.e. by setting APP_STL to either '`gnustl_static`' or 220 > '`gnustl_shared`') enforced the support for exceptions and RTTI in all 221 > generated machine code. This could be problematic in specific, but rare, 222 > cases, and also generated un-necessarily bigger code for projects that 223 > don't require these features. 224 > 225 > This bug was fixed in NDK r7b, but this means that if your code requires 226 > exceptions or RTTI, it should now explicitly say so, either in your 227 > APP_CPPFLAGS, or your LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES definitions. 228 > 229 > To make it easier to port projects to NDK r7b and later, one can 230 > optionally defined APP_GNUSTL_CPP_FEATURES to contain one or more of the 231 > following values: 232 233 exceptions -> to enforce exceptions support for all modules. 234 rtti -> to enforce rtti support for all modules. 235 236 > For example, to get the exact same behaviour than NDK r7: 237 238 APP_GNUSTL_FORCE_CPP_FEATURES := exceptions rtti 239 240 > IMPORTANT: This variable is provided here as a convenience to make it 241 > easier to transition to a newer version of the NDK. It will 242 > be removed in a future revision. We thus encourage all 243 > developers to modify the module definitions properly instead 244 > of relying on it here. 245 246 - - - - 247 APP_SHORT_COMMANDS 248 > The equivalent of LOCAL_SHORT_COMMANDS for your whole project. See the 249 > documentation for this variable in [ANDROID-MK](ANDROID-MK.html). 250 251 - - - - 252 NDK_TOOLCHAIN_VERSION 253 > Define this variable to either 4.6, 4.7 or 4.8 to select version of 254 > the GCC compiler. 4.6 is the default 255 256 - - - - 257 APP_PIE 258 > Starting from Jelly Bean (4.1), Android's dynamic linker supports 259 > position-independent executables (PIE), which are built with `-fPIE`. 260 > This flag makes it harder to exploit memory corruption bugs by 261 > randomization the location of the code. 262 > By default, `ndk-build` will automatically set this value to '`true`' if 263 > your project targets `android-16` or higher. You may set it manually 264 > to either '`true`' or '`false`'. 265 > 266 > IMPORTANT: PIE executables *cannot* run on Android releases prior to 4.1. 267 > 268 > Note that this only applies to executables. It has no effect when 269 > building shared or static libraries. 270 271 - - - - 272 APP_THIN_ARCHIVE 273 > Sets the default value of LOCAL_THIN_ARCHIVE for all static library 274 > modules in this project. For more information, see the documentation 275 > for LOCAL_THIN_ARCHIVE in [ANDROID-MK](ANDROID-MK.html). 276 277 - - - - 278 A trivial `Application.mk` file would be: 279 280 -------------- cut here ------------------------- 281 APP_PROJECT_PATH := <path to project> 282 -------------- cut here ------------------------- 283 284
