1Android.mk file syntax specification 2 3Introduction: 4------------- 5 6This document describes the syntax of Android.mk build file 7written to describe your C and C++ source files to the Android 8NDK. To understand what follows, it is assumed that you have 9read the docs/OVERVIEW.TXT file that explains their role and 10usage. 11 12Overview: 13--------- 14 15An Android.mk file is written to describe your sources to the 16build 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 45Note that the syntax is *very* close to the one used in Android.mk files 46distributed with the full open-source Android platform sources. While 47the build system implementation that uses them is different, this is 48an intentional design decision made to allow reuse of 'external' libraries' 49source code easier for application developers. 50 51Simple example: 52--------------- 53 54Before 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 59Here, 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 85Now, let's explain these lines: 86 87 LOCAL_PATH := $(call my-dir) 88 89An Android.mk file must begin with the definition of the LOCAL_PATH variable. 90It is used to locate source files in the development tree. In this example, 91the macro function 'my-dir', provided by the build system, is used to return 92the path of the current directory (i.e. the directory containing the 93Android.mk file itself). 94 95 include $(CLEAR_VARS) 96 97The CLEAR_VARS variable is provided by the build system and points to a 98special GNU Makefile that will clear many LOCAL_XXX variables for you 99(e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...), 100with the exception of LOCAL_PATH. This is needed because all build 101control files are parsed in a single GNU Make execution context where 102all variables are global. 103 104 LOCAL_MODULE := hello-jni 105 106The LOCAL_MODULE variable must be defined to identify each module you 107describe in your Android.mk. The name must be *unique* and not contain 108any spaces. Note that the build system will automatically add proper 109prefix and suffix to the corresponding generated file. In other words, 110a shared library module named 'foo' will generate 'libfoo.so'. 111 112IMPORTANT NOTE: 113If you name your module 'libfoo', the build system will not 114add another 'lib' prefix and will generate libfoo.so as well. 115This is to support Android.mk files that originate from the 116Android platform sources, would you need to use these. 117 118 LOCAL_SRC_FILES := hello-jni.c 119 120The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source 121files that will be built and assembled into a module. Note that you should 122not list header and included files here, because the build system will 123compute dependencies automatically for you; just list the source files 124that will be passed directly to a compiler, and you should be good. 125 126Note that the default extension for C++ source files is '.cpp'. It is 127however possible to specify a different one by defining the variable 128LOCAL_DEFAULT_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' 129will work, but not 'cxx'). 130 131 include $(BUILD_SHARED_LIBRARY) 132 133The BUILD_SHARED_LIBRARY is a variable provided by the build system that 134points to a GNU Makefile script that is in charge of collecting all the 135information you defined in LOCAL_XXX variables since the latest 136'include $(CLEAR_VARS)' and determine what to build, and how to do it 137exactly. There is also BUILD_STATIC_LIBRARY to generate a static library. 138 139There are more complex examples under apps/, with commented 140Android.mk files that you can look at. 141 142Reference: 143---------- 144 145This is the list of variables you should either rely on or define in 146an Android.mk. You can define other variables for your own usage, but 147the 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 153If you need to define your own convenience variables in an Android.mk 154file, 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 165So, here we go: 166 167 168NDK-provided variables: 169- - - - - - - - - - - - 170 171These GNU Make variables are defined by the build system before 172your Android.mk file is parsed. Note that under certain circumstances 173the NDK might parse your Android.mk several times, each with different 174definition for some of these variables. 175 176CLEAR_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 183BUILD_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 194BUILD_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 205TARGET_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 210TARGET_PLATFORM 211 Name of the target Android platform when this Android.mk is parsed. 212 For now, only 'android-3' is supported, which corresponds to the 213 Android 1.5 platform. 214 215TARGET_ARCH_ABI 216 Name of the target CPU+ABI when this Android.mk is parsed. 217 For now, only 'arm' is supported, which really means the following: 218 219 ARMv5TE or higher CPU, with 'softfloat' floating point support 220 221 Other target ABIs will be introduced in future releases of the NDK 222 and will have a different name. Note that all ARM-based ABIs will 223 have 'TARGET_ARCH' defined to 'arm', but may have different 224 'TARGET_ARCH_ABI' 225 226TARGET_ABI 227 The concatenation of target platform and abi, it really is defined 228 as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want 229 to test against a specific target system image for a real device. 230 231 By default, this will be 'android-3-arm' 232 233 234NDK-provided function macros: 235- - - - - - - - - - - - - - - 236 237The following are GNU Make 'function' macros, and must be evaluated 238by using '$(call <function>)'. They return textual information. 239 240my-dir 241 Returns the path of the current Android.mk's directory, relative 242 to the top of the NDK build system. This is useful to define 243 LOCAL_PATH at the start of your Android.mk as with: 244 245 LOCAL_PATH := $(call my-dir) 246 247all-subdir-makefiles 248 Returns a list of Android.mk located in all sub-directories of 249 the current 'my-dir' path. For example, consider the following 250 hierarchy: 251 252 sources/foo/Android.mk 253 sources/foo/lib1/Android.mk 254 sources/foo/lib2/Android.mk 255 256 If sources/foo/Android.mk contains the single line: 257 258 include $(call all-subdir-makefiles) 259 260 Then it will include automatically sources/foo/lib1/Android.mk and 261 sources/foo/lib2/Android.mk 262 263 This function can be used to provide deep-nested source directory 264 hierarchies to the build system. Note that by default, the NDK 265 will only look for files in sources/*/Android.mk 266 267this-makefile 268 Returns the path of the current Makefile (i.e. where the function 269 is called). 270 271parent-makefile 272 Returns the path of the parent Makefile in the inclusion tree, 273 i.e. the path of the Makefile that included the current one. 274 275grand-parent-makefile 276 Guess what... 277 278 279Module-description variables: 280- - - - - - - - - - - - - - - 281 282The following variables are used to describe your module to the build 283system. You should define some of them between an 'include $(CLEAR_VARS)' 284and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is 285a script that will undefine/clear all of these variables, unless explicitely 286noted in their description. 287 288LOCAL_PATH 289 This variable is used to give the path of the current file. 290 You MUST define it at the start of your Android.mk, which can 291 be done with: 292 293 LOCAL_PATH := $(call my-dir) 294 295 This variable is *not* cleared by $(CLEAR_VARS) so only one 296 definition per Android.mk is needed (in case you define several 297 modules in a single file). 298 299LOCAL_MODULE 300 This is the name of your module. It must be unique among all 301 module names, and shall not contain any space. You MUST define 302 it before including any $(BUILD_XXXX) script. 303 304 The module name determines the name of generated files, e.g. 305 lib<foo>.so for a shared library module named <foo>. However 306 you should only refer to other modules with their 'normal' 307 name (e.g. <foo>) in your NDK build files (either Android.mk 308 or Application.mk) 309 310LOCAL_SRC_FILES 311 This is a list of source files that will be built for your module. 312 Only list the files that will be passed to a compiler, since the 313 build system automatically computes dependencies for you. 314 315 Note that source files names are all relative to LOCAL_PATH and 316 you can use path components, e.g.: 317 318 LOCAL_SRC_FILES := foo.c \ 319 toto/bar.c 320 321 NOTE: Always use Unix-style forward slashes (/) in build files. 322 Windows-style back-slashes will not be handled properly. 323 324LOCAL_CPP_EXTENSION 325 This is an optional variable that can be defined to indicate 326 the file extension of C++ source files. The default is '.cpp' 327 but you can change it. For example: 328 329 LOCAL_CPP_EXTENSION := .cxx 330 331LOCAL_C_INCLUDES 332 An optional list of paths, relative to the NDK *root* directory, 333 which will be appended to the include search path when compiling 334 all sources (C, C++ and Assembly). For example: 335 336 LOCAL_C_INCLUDES := sources/foo 337 338 Or even: 339 340 LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo 341 342 These are placed before any corresponding inclusion flag in 343 LOCAL_CFLAGS / LOCAL_CPPFLAGS 344 345 346LOCAL_CFLAGS 347 An optional set of compiler flags that will be passed when building 348 C *and* C++ source files. 349 350 This can be useful to specify additionnal macro definitions or 351 compile options. 352 353 IMPORTANT: Try not to change the optimization/debugging level in 354 your Android.mk, this can be handled automatically for 355 you by specifying the appropriate information in 356 your Application.mk, and will let the NDK generate 357 useful data files used during debugging. 358 359 NOTE: In android-ndk-1.5_r1, the corresponding flags only applied 360 to C source files, not C++ ones. This has been corrected to 361 match the full Android build system behaviour. (You can use 362 LOCAL_CPPFLAGS to specify flags for C++ sources only now). 363 364LOCAL_CXXFLAGS 365 An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete 366 as it may disappear in future releases of the NDK. 367 368LOCAL_CPPFLAGS 369 An optional set of compiler flags that will be passed when building 370 C++ source files *only*. They will appear after the LOCAL_CFLAGS 371 on the compiler's command-line. 372 373 NOTE: In android-ndk-1.5_r1, the corresponding flags applied to 374 both C and C++ sources. This has been corrected to match the 375 full Android build system. (You can use LOCAL_CFLAGS to specify 376 flags for both C and C++ sources now). 377 378LOCAL_STATIC_LIBRARIES 379 The list of static libraries modules (built with BUILD_STATIC_LIBRARY) 380 that should be linked to this module. This only makes sense in 381 shared library modules. 382 383LOCAL_SHARED_LIBRARIES 384 The list of shared libraries *modules* this module depends on at runtime. 385 This is necessary at link time and to embed the corresponding information 386 in the generated file. 387 388 Note that this does not append the listed modules to the build graph, 389 i.e. you should still add them to your application's required modules 390 in your Application.mk 391 392LOCAL_LDLIBS 393 The list of additional linker flags to be used when building your 394 module. This is useful to pass the name of specific system libraries 395 with the "-l" prefix. For example, the following will tell the linker 396 to generate a module that links to /system/lib/libz.so at load time: 397 398 LOCAL_LDLIBS := -lz 399 400 See docs/STABLE-APIS.TXT for the list of exposed system libraries you 401 can linked against with this NDK release. 402 403LOCAL_ALLOW_UNDEFINED_SYMBOLS 404 By default, any undefined reference encountered when trying to build 405 a shared library will result in an "undefined symbol" error. This is a 406 great help to catch bugs in your source code. 407 408 However, if for some reason you need to disable this check, set this 409 variable to 'true'. Note that the corresponding shared library may fail 410 to load at runtime. 411 412LOCAL_ARM_MODE 413 By default, ARM target binaries will be generated in 'thumb' mode, where 414 each instruction are 16-bit wide. You can define this variable to 'arm' 415 if you want to force the generation of the module's object files in 416 'arm' (32-bit instructions) mode. E.g.: 417 418 LOCAL_ARM_MODE := arm 419 420 Note that you can also instruct the build system to only build specific 421 sources in arm mode by appending an '.arm' suffix to its source file 422 name. For example, with: 423 424 LOCAL_SRC_FILES := foo.c bar.c.arm 425 426 Tells the build system to always compile 'bar.c' in arm mode, and to 427 build foo.c according to the value of LOCAL_ARM_MODE. 428 429 NOTE: Setting APP_OPTIM to 'debug' in your Application.mk will also force 430 the generation of ARM binaries as well. This is due to bugs in the 431 toolchain debugger that don't deal too well with thumb code. 432