1 Android.mk file syntax specification 2 3 Introduction: 4 ------------- 5 6 This document describes the syntax of Android.mk build file 7 written to describe your C and C++ source files to the Android 8 NDK. To understand what follows, it is assumed that you have 9 read the docs/OVERVIEW.TXT file that explains their role and 10 usage. 11 12 Overview: 13 --------- 14 15 An Android.mk file is written to describe your sources to the 16 build system. More specifically: 17 18 - The file is really a tiny GNU Makefile fragment that will be 19 parsed one or more times by the build system. As such, you 20 should try to minimize the variables you declare there and 21 do not assume that anything is not defined during parsing. 22 23 - The file syntax is designed to allow you to group your 24 sources into 'modules'. A module is one of the following: 25 26 - a static library 27 - a shared library 28 29 Only shared libraries will be installed/copied to your 30 application package. Static libraries can be used to generate 31 shared libraries though. 32 33 You can define one or more modules in each Android.mk file, 34 and you can use the same source file in several modules. 35 36 - The build system handles many details for you. For example, you 37 don't need to list header files or explicit dependencies between 38 generated files in your Android.mk. The NDK build system will 39 compute these automatically for you. 40 41 This also means that, when updating to newer releases of the NDK, 42 you should be able to benefit from new toolchain/platform support 43 without having to touch your Android.mk files. 44 45 Note that the syntax is *very* close to the one used in Android.mk files 46 distributed with the full open-source Android platform sources. While 47 the build system implementation that uses them is different, this is 48 an intentional design decision made to allow reuse of 'external' libraries' 49 source code easier for application developers. 50 51 Simple example: 52 --------------- 53 54 Before describing the syntax in details, let's consider the simple 55 "hello JNI" example, i.e. the files under: 56 57 apps/hello-jni/project 58 59 Here, we can see: 60 61 - The 'src' directory containing the Java sources for the 62 sample Android project. 63 64 - The 'jni' directory containing the native source for 65 the sample, i.e. 'jni/hello-jni.c' 66 67 This source file implements a simple shared library that 68 implements a native method that returns a string to the 69 VM application. 70 71 - The 'jni/Android.mk' file that describes the shared library 72 to the NDK build system. Its content is: 73 74 ---------- cut here ------------------ 75 LOCAL_PATH := $(call my-dir) 76 77 include $(CLEAR_VARS) 78 79 LOCAL_MODULE := hello-jni 80 LOCAL_SRC_FILES := hello-jni.c 81 82 include $(BUILD_SHARED_LIBRARY) 83 ---------- cut here ------------------ 84 85 Now, let's explain these lines: 86 87 LOCAL_PATH := $(call my-dir) 88 89 An Android.mk file must begin with the definition of the LOCAL_PATH variable. 90 It is used to locate source files in the development tree. In this example, 91 the macro function 'my-dir', provided by the build system, is used to return 92 the path of the current directory (i.e. the directory containing the 93 Android.mk file itself). 94 95 include $(CLEAR_VARS) 96 97 The CLEAR_VARS variable is provided by the build system and points to a 98 special GNU Makefile that will clear many LOCAL_XXX variables for you 99 (e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...), 100 with the exception of LOCAL_PATH. This is needed because all build 101 control files are parsed in a single GNU Make execution context where 102 all variables are global. 103 104 LOCAL_MODULE := hello-jni 105 106 The LOCAL_MODULE variable must be defined to identify each module you 107 describe in your Android.mk. The name must be *unique* and not contain 108 any spaces. Note that the build system will automatically add proper 109 prefix and suffix to the corresponding generated file. In other words, 110 a shared library module named 'foo' will generate 'libfoo.so'. 111 112 IMPORTANT NOTE: 113 If you name your module 'libfoo', the build system will not 114 add another 'lib' prefix and will generate libfoo.so as well. 115 This is to support Android.mk files that originate from the 116 Android platform sources, would you need to use these. 117 118 LOCAL_SRC_FILES := hello-jni.c 119 120 The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source 121 files that will be built and assembled into a module. Note that you should 122 not list header and included files here, because the build system will 123 compute dependencies automatically for you; just list the source files 124 that will be passed directly to a compiler, and you should be good. 125 126 Note that the default extension for C++ source files is '.cpp'. It is 127 however possible to specify a different one by defining the variable 128 LOCAL_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' will 129 work, but not 'cxx'). 130 131 include $(BUILD_SHARED_LIBRARY) 132 133 The BUILD_SHARED_LIBRARY is a variable provided by the build system that 134 points to a GNU Makefile script that is in charge of collecting all the 135 information you defined in LOCAL_XXX variables since the latest 136 'include $(CLEAR_VARS)' and determine what to build, and how to do it 137 exactly. There is also BUILD_STATIC_LIBRARY to generate a static library. 138 139 There are more complex examples in the samples directories, with commented 140 Android.mk files that you can look at. 141 142 Reference: 143 ---------- 144 145 This is the list of variables you should either rely on or define in 146 an Android.mk. You can define other variables for your own usage, but 147 the NDK build system reserves the following variable names: 148 149 - names that begin with LOCAL_ (e.g. LOCAL_MODULE) 150 - names that begin with PRIVATE_, NDK_ or APP_ (used internally) 151 - lower-case names (used internally, e.g. 'my-dir') 152 153 If you need to define your own convenience variables in an Android.mk 154 file, we recommend using the MY_ prefix, for a trivial example: 155 156 ---------- cut here ------------------ 157 MY_SOURCES := foo.c 158 ifneq ($(MY_CONFIG_BAR),) 159 MY_SOURCES += bar.c 160 endif 161 162 LOCAL_SRC_FILES += $(MY_SOURCES) 163 ---------- cut here ------------------ 164 165 So, here we go: 166 167 168 NDK-provided variables: 169 - - - - - - - - - - - - 170 171 These GNU Make variables are defined by the build system before 172 your Android.mk file is parsed. Note that under certain circumstances 173 the NDK might parse your Android.mk several times, each with different 174 definition for some of these variables. 175 176 CLEAR_VARS 177 Points to a build script that undefines nearly all LOCAL_XXX variables 178 listed in the "Module-description" section below. You must include 179 the script before starting a new module, e.g.: 180 181 include $(CLEAR_VARS) 182 183 BUILD_SHARED_LIBRARY 184 Points to a build script that collects all the information about the 185 module you provided in LOCAL_XXX variables and determines how to build 186 a target shared library from the sources you listed. Note that you 187 must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before 188 including this file. Example usage: 189 190 include $(BUILD_SHARED_LIBRARY) 191 192 note that this will generate a file named lib$(LOCAL_MODULE).so 193 194 BUILD_STATIC_LIBRARY 195 A variant of BUILD_SHARED_LIBRARY that is used to build a target static 196 library instead. Static libraries are not copied into your 197 project/packages but can be used to build shared libraries (see 198 LOCAL_STATIC_LIBRARIES and LOCAL_STATIC_WHOLE_LIBRARIES described below). 199 Example usage: 200 201 include $(BUILD_STATIC_LIBRARY) 202 203 Note that this will generate a file named lib$(LOCAL_MODULE).a 204 205 TARGET_ARCH 206 Name of the target CPU architecture as it is specified by the 207 full Android open-source build. This is 'arm' for any ARM-compatible 208 build, independent of the CPU architecture revision. 209 210 TARGET_PLATFORM 211 Name of the target Android platform when this Android.mk is parsed. 212 For example, 'android-3' correspond to Android 1.5 system images. For 213 a complete list of platform names and corresponding Android system 214 images, read docs/STABLE-APIS.TXT. 215 216 TARGET_ARCH_ABI 217 Name of the target CPU+ABI when this Android.mk is parsed. 218 Two values are supported at the moment: 219 220 armeabi 221 For Armv5TE 222 223 armeabi-v7a 224 225 NOTE: Up to Android NDK 1.6_r1, this variable was simply defined 226 as 'arm'. However, the value has been redefined to better 227 match what is used internally by the Android platform. 228 229 For more details about architecture ABIs and corresponding 230 compatibility issues, please read docs/CPU-ARCH-ABIS.TXT 231 232 Other target ABIs will be introduced in future releases of the NDK 233 and will have a different name. Note that all ARM-based ABIs will 234 have 'TARGET_ARCH' defined to 'arm', but may have different 235 'TARGET_ARCH_ABI' 236 237 TARGET_ABI 238 The concatenation of target platform and abi, it really is defined 239 as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want 240 to test against a specific target system image for a real device. 241 242 By default, this will be 'android-3-armeabi' 243 244 (Up to Android NDK 1.6_r1, this used to be 'android-3-arm' by default) 245 246 NDK-provided function macros: 247 - - - - - - - - - - - - - - - 248 249 The following are GNU Make 'function' macros, and must be evaluated 250 by using '$(call <function>)'. They return textual information. 251 252 my-dir 253 Returns the path of the current Android.mk's directory, relative 254 to the top of the NDK build system. This is useful to define 255 LOCAL_PATH at the start of your Android.mk as with: 256 257 LOCAL_PATH := $(call my-dir) 258 259 all-subdir-makefiles 260 Returns a list of Android.mk located in all sub-directories of 261 the current 'my-dir' path. For example, consider the following 262 hierarchy: 263 264 sources/foo/Android.mk 265 sources/foo/lib1/Android.mk 266 sources/foo/lib2/Android.mk 267 268 If sources/foo/Android.mk contains the single line: 269 270 include $(call all-subdir-makefiles) 271 272 Then it will include automatically sources/foo/lib1/Android.mk and 273 sources/foo/lib2/Android.mk 274 275 This function can be used to provide deep-nested source directory 276 hierarchies to the build system. Note that by default, the NDK 277 will only look for files in sources/*/Android.mk 278 279 this-makefile 280 Returns the path of the current Makefile (i.e. where the function 281 is called). 282 283 parent-makefile 284 Returns the path of the parent Makefile in the inclusion tree, 285 i.e. the path of the Makefile that included the current one. 286 287 grand-parent-makefile 288 Guess what... 289 290 291 Module-description variables: 292 - - - - - - - - - - - - - - - 293 294 The following variables are used to describe your module to the build 295 system. You should define some of them between an 'include $(CLEAR_VARS)' 296 and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is 297 a script that will undefine/clear all of these variables, unless explicitely 298 noted in their description. 299 300 LOCAL_PATH 301 This variable is used to give the path of the current file. 302 You MUST define it at the start of your Android.mk, which can 303 be done with: 304 305 LOCAL_PATH := $(call my-dir) 306 307 This variable is *not* cleared by $(CLEAR_VARS) so only one 308 definition per Android.mk is needed (in case you define several 309 modules in a single file). 310 311 LOCAL_MODULE 312 This is the name of your module. It must be unique among all 313 module names, and shall not contain any space. You MUST define 314 it before including any $(BUILD_XXXX) script. 315 316 The module name determines the name of generated files, e.g. 317 lib<foo>.so for a shared library module named <foo>. However 318 you should only refer to other modules with their 'normal' 319 name (e.g. <foo>) in your NDK build files (either Android.mk 320 or Application.mk) 321 322 LOCAL_SRC_FILES 323 This is a list of source files that will be built for your module. 324 Only list the files that will be passed to a compiler, since the 325 build system automatically computes dependencies for you. 326 327 Note that source files names are all relative to LOCAL_PATH and 328 you can use path components, e.g.: 329 330 LOCAL_SRC_FILES := foo.c \ 331 toto/bar.c 332 333 NOTE: Always use Unix-style forward slashes (/) in build files. 334 Windows-style back-slashes will not be handled properly. 335 336 LOCAL_CPP_EXTENSION 337 This is an optional variable that can be defined to indicate 338 the file extension of C++ source files. The default is '.cpp' 339 but you can change it. For example: 340 341 LOCAL_CPP_EXTENSION := .cxx 342 343 LOCAL_C_INCLUDES 344 An optional list of paths, relative to the NDK *root* directory, 345 which will be appended to the include search path when compiling 346 all sources (C, C++ and Assembly). For example: 347 348 LOCAL_C_INCLUDES := sources/foo 349 350 Or even: 351 352 LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo 353 354 These are placed before any corresponding inclusion flag in 355 LOCAL_CFLAGS / LOCAL_CPPFLAGS 356 357 358 LOCAL_CFLAGS 359 An optional set of compiler flags that will be passed when building 360 C *and* C++ source files. 361 362 This can be useful to specify additionnal macro definitions or 363 compile options. 364 365 IMPORTANT: Try not to change the optimization/debugging level in 366 your Android.mk, this can be handled automatically for 367 you by specifying the appropriate information in 368 your Application.mk, and will let the NDK generate 369 useful data files used during debugging. 370 371 NOTE: In android-ndk-1.5_r1, the corresponding flags only applied 372 to C source files, not C++ ones. This has been corrected to 373 match the full Android build system behaviour. (You can use 374 LOCAL_CPPFLAGS to specify flags for C++ sources only now). 375 376 LOCAL_CXXFLAGS 377 An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete 378 as it may disappear in future releases of the NDK. 379 380 LOCAL_CPPFLAGS 381 An optional set of compiler flags that will be passed when building 382 C++ source files *only*. They will appear after the LOCAL_CFLAGS 383 on the compiler's command-line. 384 385 NOTE: In android-ndk-1.5_r1, the corresponding flags applied to 386 both C and C++ sources. This has been corrected to match the 387 full Android build system. (You can use LOCAL_CFLAGS to specify 388 flags for both C and C++ sources now). 389 390 LOCAL_STATIC_LIBRARIES 391 The list of static libraries modules (built with BUILD_STATIC_LIBRARY) 392 that should be linked to this module. This only makes sense in 393 shared library modules. 394 395 LOCAL_SHARED_LIBRARIES 396 The list of shared libraries *modules* this module depends on at runtime. 397 This is necessary at link time and to embed the corresponding information 398 in the generated file. 399 400 Note that this does not append the listed modules to the build graph, 401 i.e. you should still add them to your application's required modules 402 in your Application.mk 403 404 LOCAL_LDLIBS 405 The list of additional linker flags to be used when building your 406 module. This is useful to pass the name of specific system libraries 407 with the "-l" prefix. For example, the following will tell the linker 408 to generate a module that links to /system/lib/libz.so at load time: 409 410 LOCAL_LDLIBS := -lz 411 412 See docs/STABLE-APIS.TXT for the list of exposed system libraries you 413 can linked against with this NDK release. 414 415 LOCAL_ALLOW_UNDEFINED_SYMBOLS 416 By default, any undefined reference encountered when trying to build 417 a shared library will result in an "undefined symbol" error. This is a 418 great help to catch bugs in your source code. 419 420 However, if for some reason you need to disable this check, set this 421 variable to 'true'. Note that the corresponding shared library may fail 422 to load at runtime. 423 424 LOCAL_ARM_MODE 425 By default, ARM target binaries will be generated in 'thumb' mode, where 426 each instruction are 16-bit wide. You can define this variable to 'arm' 427 if you want to force the generation of the module's object files in 428 'arm' (32-bit instructions) mode. E.g.: 429 430 LOCAL_ARM_MODE := arm 431 432 Note that you can also instruct the build system to only build specific 433 sources in arm mode by appending an '.arm' suffix to its source file 434 name. For example, with: 435 436 LOCAL_SRC_FILES := foo.c bar.c.arm 437 438 Tells the build system to always compile 'bar.c' in arm mode, and to 439 build foo.c according to the value of LOCAL_ARM_MODE. 440 441 NOTE: Setting APP_OPTIM to 'debug' in your Application.mk will also force 442 the generation of ARM binaries as well. This is due to bugs in the 443 toolchain debugger that don't deal too well with thumb code. 444 445 LOCAL_ARM_NEON 446 Defining this variable to 'true' allows the use of ARM Advanced SIMD 447 (a.k.a. NEON) GCC intrinsics in your C and C++ sources, as well as 448 NEON instructions in Assembly files. 449 450 You should only define it when targetting the 'armeabi-v7a' ABI that 451 corresponds to the ARMv7 instruction set. Note that not all ARMv7 452 based CPUs support the NEON instruction set extensions and that you 453 should perform runtime detection to be able to use this code at runtime 454 safely. To lean more about this, please read the documentation at 455 docs/CPU-ARM-NEON.TXT and docs/CPU-FEATURES.TXT. 456 457 Alternatively, you can also specify that only specific source files 458 may be compiled with NEON support by using the '.neon' suffix, as 459 in: 460 461 LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon 462 463 In this example, 'foo.c' will be compiled in thumb+neon mode, 464 'bar.c' will be compiled in 'thumb' mode, and 'zoo.c' will be 465 compiled in 'arm+neon' mode. 466 467 Note that the '.neon' suffix must appear after the '.arm' suffix 468 if you use both (i.e. foo.c.arm.neon works, but not foo.c.neon.arm !) 469 470 LOCAL_DISABLE_NO_EXECUTE 471 Android NDK r4 added support for the "NX bit" security feature. 472 It is enabled by default, but you can disable it if you *really* 473 need to by setting this variable to 'true'. 474 475 NOTE: This feature does not modify the ABI and is only enabled on 476 kernels targetting ARMv6+ CPU devices. Machine code generated 477 with this feature enabled will run unmodified on devices 478 running earlier CPU architectures. 479 480 For more information, see: 481 482 http://en.wikipedia.org/wiki/NX_bit 483 http://www.gentoo.org/proj/en/hardened/gnu-stack.xml 484