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 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 - - - - 191 APP_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 - - - - 197 APP_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 - - - - 213 APP_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 - - - - 243 APP_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 - - - - 248 NDK_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 - - - - 253 APP_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 - - - - 268 APP_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 - - - - 274 A trivial `Application.mk` file would be: 275 276 -------------- cut here ------------------------- 277 APP_PROJECT_PATH := <path to project> 278 -------------- cut here ------------------------- 279 280
