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/<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 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/<myapp>/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 <application> 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_LDFLAGS 125 A set of linker flags passed when linking application. 126 127 APP_BUILD_SCRIPT 128 By default, the NDK build system will look for a file named Android.mk 129 under $(APP_PROJECT_PATH)/jni, i.e. for the file: 130 131 $(APP_PROJECT_PATH)/jni/Android.mk 132 133 If you want to override this behaviour, you can define APP_BUILD_SCRIPT 134 to point to an alternate build script. A non-absolute path will always 135 be interpreted as relative to the NDK's top-level directory. 136 137 APP_ABI 138 By default, the NDK build system will generate machine code for the 139 'armeabi' ABI. This corresponds to an ARMv5TE based CPU with software 140 floating point operations. You can use APP_ABI to select a different 141 ABI. 142 143 For example, to support hardware FPU instructions on ARMv7 based devices, 144 use: 145 146 APP_ABI := armeabi-v7a 147 148 Or to support the IA-32 instruction set, use: 149 150 APP_ABI := x86 151 152 Or to support the MIPS instruction set, use: 153 154 APP_ABI := mips 155 156 Or to support all at the same time, use: 157 158 APP_ABI := armeabi armeabi-v7a x86 mips 159 160 Or even better, since NDK r7, you can also use the special value 161 'all' which means "all ABIs supported by this NDK release": 162 163 APP_ABI := all 164 165 For the list of all supported ABIs and details about their usage and 166 limitations, please read docs/CPU-ARCH-ABIS.html 167 168 APP_PLATFORM 169 Name the target Android platform. For example, 'android-3' correspond 170 to Android 1.5 system images. For a complete list of platform names and 171 corresponding Android system images, read docs/STABLE-APIS.html. 172 173 APP_STL 174 By default, the NDK build system provides C++ headers for the minimal 175 C++ runtime library (/system/lib/libstdc++.so) provided by the Android 176 system. 177 178 However, the NDK comes with alternative C++ implementations that you can 179 use or link to in your own applications. Define APP_STL to select one of 180 them. Examples are: 181 182 APP_STL := stlport_static --> static STLport library 183 APP_STL := stlport_shared --> shared STLport library 184 APP_STL := system --> default C++ runtime library 185 186 For more information on the subject, please read docs/CPLUSPLUS-SUPPORT.html 187 188 APP_GNUSTL_FORCE_CPP_FEATURES 189 In prior NDK versions, the simple fact of using the GNU libstdc++ 190 runtime (i.e. by setting APP_STL to either 'gnustl_static' or 191 'gnustl_shared') enforced the support for exceptions and RTTI in all 192 generated machine code. This could be problematic in specific, but rare, 193 cases, and also generated un-necessarily bigger code for projects that 194 don't require these features. 195 196 This bug was fixed in NDK r7b, but this means that if your code requires 197 exceptions or RTTI, it should now explicitly say so, either in your 198 APP_CPPFLAGS, or your LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES definitions. 199 200 To make it easier to port projects to NDK r7b and later, one can 201 optionally defined APP_GNUSTL_CPP_FEATURES to contain one or more of the 202 following values: 203 204 exceptions -> to enforce exceptions support for all modules. 205 rtti -> to enforce rtti support for all modules. 206 207 For example, to get the exact same behaviour than NDK r7: 208 209 APP_GNUSTL_FORCE_CPP_FEATURES := exceptions rtti 210 211 IMPORTANT: This variable is provided here as a convenience to make it 212 easier to transition to a newer version of the NDK. It will 213 be removed in a future revision. We thus encourage all 214 developers to modify the module definitions properly instead 215 of relying on it here. 216 217 APP_SHORT_COMMANDS 218 The equivalent of LOCAL_SHORT_COMMANDS for your whole project. See the 219 documentation for this variable in docs/ANDROID-MK.html. 220 221 NDK_TOOLCHAIN_VERSION 222 Define this variable to either 4.4.3 or 4.6 to select version of GCC compiler. 223 4.6 is the default 224 225 APP_PIE 226 Starting from Jelly Bean (4.1), Android's dynamic linker supports 227 position-independent executables (PIE), which are built with -fPIE. 228 This flag makes it harder to exploit memory corruption bugs by 229 randomization the location of the code. 230 By default, ndk-build will automatically set this value to 'true' if 231 your project targets android-16 or higher. You may set it manually 232 to either 'true' or 'false'. 233 234 IMPORTANT: PIE executables *cannot* run on Android releases prior to 4.1. 235 236 Note that this only applies to executables. It has no effect when 237 building shared or static libraries. 238 239 240 A trivial Application.mk file would be: 241 242 -------------- cut here ------------------------- 243 APP_PROJECT_PATH := <path to project> 244 -------------- cut here ------------------------- 245 </pre></body></html> 246
