Android_mk

Android.mk file syntax specification Introduction: ------------- This document describes the syntax of Android.mk build filewritten to describe your C and C++ source files to the AndroidNDK. To understand what follows, it is assumed that you haveread the docs/OVERVIEW.html file that explains their role andusage. Overview: --------- An Android.mk file is written to describe your sources to thebuild system. More specifically: - The file is really a tiny GNU Makefile fragment that will be parsed one or more times by the build system. As such, youshould try to minimize the variables you declare there and do not assume that anything is not defined during parsing. - The file syntax is designed to allow you to group your sources into 'modules'. A module is one of the following: - a static library - a shared library Only shared libraries will be installed/copied to yourapplication package. Static libraries can be used to generateshared libraries though. You can define one or more modules in each Android.mk file, and you can use the same source file in several modules. - The build system handles many details for you. For example, youdon't need to list header files or explicit dependencies betweengenerated files in your Android.mk. The NDK build system willcompute these automatically for you. This also means that, when updating to newer releases of the NDK,you should be able to benefit from new toolchain/platform supportwithout having to touch your Android.mk files. Note that the syntax is *very* close to the one used in Android.mk filesdistributed with the full open-source Android platform sources. Whilethe build system implementation that uses them is different, this isan intentional design decision made to allow reuse of 'external' libraries'source code easier for application developers. Simple example: --------------- Before describing the syntax in details, let's consider the simple"hello JNI" example, i.e. the files under: apps/hello-jni/project Here, we can see: - The 'src' directory containing the Java sources for thesample Android project. - The 'jni' directory containing the native source forthe sample, i.e. 'jni/hello-jni.c' This source file implements a simple shared library thatimplements a native method that returns a string to theVM application. - The 'jni/Android.mk' file that describes the shared libraryto the NDK build system. Its content is: ---------- cut here ------------------ LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_module := hello-jni LOCAL_SRC_FILES := hello-jni.c include $(BUILD_SHARED_LIBRARY) ---------- cut here ------------------ Now, let's explain these lines: LOCAL_PATH := $(call my-dir) An Android.mk file must begin with the definition of the LOCAL_PATH variable.It is used to locate source files in the development tree. In this example,the macro function 'my-dir', provided by the build system, is used to returnthe path of the current directory (i.e. the directory containing theAndroid.mk file itself). include $(CLEAR_VARS) The CLEAR_VARS variable is provided by the build system and points to aspecial GNU Makefile that will clear many LOCAL_XXX variables for you(e.g. LOCAL_module, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...),with the exception of LOCAL_PATH. This is needed because all buildcontrol files are parsed in a single GNU Make execution context whereall variables are global. LOCAL_module := hello-jni The LOCAL_MODULE variable must be defined to identify each module youdescribe in your Android.mk. The name must be *unique* and not containany spaces. Note that the build system will automatically add properprefix and suffix to the corresponding generated file. In other words,a shared library module named 'foo' will generate 'libfoo.so'. IMPORTANT NOTE: If you name your module 'libfoo', the build system will notadd another 'lib' prefix and will generate libfoo.so as well.This is to support Android.mk files that originate from the Android platform sources, would you need to use these. LOCAL_SRC_FILES := hello-jni.c The LOCAL_SRC_FILES variables must contain a list of C and/or C++ sourcefiles that will be built and assembled into a module. Note that you shouldnot list header and included files here, because the build system willcompute dependencies automatically for you; just list the source filesthat will be passed directly to a compiler, and you should be good. Note that the default extension for C++ source files is '.cpp'. It ishowever possible to specify a different one by defining the variableLOCAL_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' willwork, but not 'cxx'). include $(BUILD_SHARED_LIBRARY) The BUILD_SHARED_LIBRARY is a variable provided by the build system thatpoints to a GNU Makefile script that is in chARGe of collecting all theinformation you defined in LOCAL_XXX variables since the latest'include $(CLEAR_VARS)' and determine what to build, and how to do itexactly. There is also BUILD_STATIC_LIBRARY to generate a static library. There are more complex examples in the samples directories, with commentedAndroid.mk files that you can look at. Reference: ---------- This is the list of variables you should either rely on or define inan Android.mk. You can define other variables for your own usage, butthe NDK build system reserves the following variable names: - names that begin with LOCAL_ (e.g. LOCAL_module) - names that begin with PRIVATE_, NDK_ or APP_ (used internally) - lower-case names (used internally, e.g. 'my-dir') If you need to define your own convenience variables in an Android.mkfile, we recommend using the MY_ prefix, for a trivial example: ---------- cut here ------------------ MY_SOURCES := foo.c ifneq ($(MY_CONFIG_BAR),) MY_SOURCES += bar.c endif LOCAL_SRC_FILES += $(MY_SOURCES) ---------- cut here ------------------ So, here we go: NDK-provided variables: - - - - - - - - - - - - These GNU Make variables are defined by the build system beforeyour Android.mk file is parsed. Note that under certain circumstancesthe NDK might parse your Android.mk several times, each with differentdefinition for some of these variables. CLEAR_VARS Points to a build script that undefines nearly all LOCAL_XXX variableslisted in the "module-description" section below. You must includethe script before starting a new module, e.g.: include $(CLEAR_VARS) BUILD_SHARED_LIBRARY Points to a build script that collects all the information about themodule you provided in LOCAL_XXX variables and determines how to builda tARGet shared library from the sources you listed. Note that youmust have LOCAL_module and LOCAL_SRC_FILES defined, at a minimum beforeincluding this file. Example usage: include $(BUILD_SHARED_LIBRARY) note that this will generate a file named lib$(LOCAL_module).so BUILD_STATIC_LIBRARY A variant of BUILD_SHARED_LIBRARY that is used to build a tARGet static library instead. Static libraries are not copied into yourproject/packages but can be used to build shared libraries (seeLOCAL_STATIC_LIBRARIES and LOCAL_WHOLE_STATIC_LIBRARIES described below). Example usage: include $(BUILD_STATIC_LIBRARY) Note that this will generate a file named lib$(LOCAL_MODULE).a PREBUILT_SHARED_LIBRARY Points to a build script used to specify a prebuilt shared library.Unlike BUILD_SHARED_LIBRARY and BUILD_STATIC_LIBRARY, the value of LOCAL_SRC_FILES must be a single path to a prebuilt sharedlibrary (e.g. foo/libfoo.so), instead of a source file. You can reference the prebuilt library in another module usingthe LOCAL_PREBUILTS variable (see docs/PREBUILTS.html for moreinformation). PREBUILT_STATIC_LIBRARY This is the same as PREBUILT_SHARED_LIBRARY, but for a static libraryfile instead. See docs/PREBUILTS.html for more. TARGET_ARCH Name of the target CPU architecture as it is specified by thefull Android open-source build. This is 'arm' for any ARM-compatiblebuild, independent of the CPU architecture revision. TARGET_PLATFORM Name of the target Android platform when this Android.mk is parsed.For example, 'android-3' correspond to Android 1.5 system images. Fora complete list of platform names and corresponding Android systemimages, read docs/STABLE-APIS.html. TARGET_ARCH_ABI Name of the target CPU+ABI when this Android.mk is parsed.Two values are supported at the moment: armeabi For ARMv5TE armeabi-v7a NOTE: Up to Android NDK 1.6_r1, this variable was simply definedas 'arm'. However, the value has been redefined to bettermatch what is used internally by the Android platform. For more details about architecture ABIs and correspondingcompatibility issues, please read docs/CPU-ARCH-ABIS.html Other tARGet ABIs will be introduced in future releases of the NDKand will have a different name. Note that all ARM-based ABIs willhave 'TARGET_ARCH' defined to 'arm', but may have different'TARGET_ARCH_ABI' TARGET_ABI The concatenation of target platform and ABI, it really is definedas $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you wantto test against a specific target system image for a real device. By default, this will be 'android-3-armeabi' (Up to Android NDK 1.6_r1, this used to be 'android-3-arm' by default) NDK-provided function macros: - - - - - - - - - - - - - - - The following are GNU Make 'function' macros, and must be evaluatedby using '$(call )'. They return textual information. my-dir Returns the path of the last included Makefile, which typically isthe current Android.mk's directory. This is useful to defineLOCAL_PATH at the start of your Android.mk as with: LOCAL_PATH := $(call my-dir) IMPORTANT NOTE: Due to the way GNU Make works, this really returnsthe path of the *last* *included* *Makefile* during the parsing ofbuild scripts. Do not call my-dir after including another file. For example, consider the following example: LOCAL_PATH := $(call my-dir) ... declare one module include $(LOCAL_PATH)/foo/Android.mk LOCAL_PATH := $(call my-dir) ... declare another module The problem here is that the second call to 'my-dir' will defineLOCAL_PATH to $PATH/foo instead of $PATH, due to the include thatwas performed before that. For this reason, it's better to put additional includes aftereverything else in an Android.mk, as in: LOCAL_PATH := $(call my-dir) ... declare one module LOCAL_PATH := $(call my-dir) ... declare another module # extra includes at the end of the Android.mk include $(LOCAL_PATH)/foo/Android.mk If this is not convenient, save the value of the first my-dir callinto another variable, for example: MY_LOCAL_PATH := $(call my-dir) LOCAL_PATH := $(MY_LOCAL_PATH) ... declare one module include $(LOCAL_PATH)/foo/Android.mk LOCAL_PATH := $(MY_LOCAL_PATH) ... declare another module all-subdir-makefiles Returns a list of Android.mk located in all sub-directories ofthe current 'my-dir' path. For example, consider the followinghierarchy: sources/foo/Android.mk sources/foo/lib1/Android.mk sources/foo/lib2/Android.mk If sources/foo/Android.mk contains the single line: include $(call all-subdir-makefiles) Then it will include automatically sources/foo/lib1/Android.mk andsources/foo/lib2/Android.mk This function can be used to provide deep-nested source directoryhierarchies to the build system. Note that by default, the NDKwill only look for files in sources/*/Android.mk this-makefile Returns the path of the current Makefile (i.e. where the functionis called). parent-makefile Returns the path of the parent Makefile in the inclusion tree,i.e. the path of the Makefile that included the current one. grand-parent-makefile Guess what... import-module A function that allows you to find and include the Android.mkof another module by name. A typical example is: $(call import-module,) And this will look for the module tagged in the list ofdirectories referenced by your NDK_MODULE_PATH environmentvariable, and include its Android.mk automatically for you. Read docs/IMPORT-MODULE.html for more details. Module-description variables: - - - - - - - - - - - - - - - The following variables are used to describe your module to the buildsystem. You should define some of them between an 'include $(CLEAR_VARS)'and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) isa script that will undefine/clear all of these variables, unless explicitlynoted in their description. LOCAL_PATH This variable is used to give the path of the current file.You MUST define it at the start of your Android.mk, which canbe done with: LOCAL_PATH := $(call my-dir) This variable is *not* cleared by $(CLEAR_VARS) so only onedefinition per Android.mk is needed (in case you define severalmodules in a single file). LOCAL_MODULE This is the name of your module. It must be unique among allmodule names, and shall not contain any space. You MUST defineit before including any $(BUILD_XXXX) script. By default, the module name determines the name of generated files, e.g. lib.so for a shared library module named . Howeveryou should only refer to other modules with their 'normal'name (e.g. ) in your NDK build files (either Android.mkor Application.mk) You can override this default with LOCAL_MODULE_FILENAME (see below) LOCAL_MODULE_FILENAME This variable is optional, and allows you to redefine the name ofgenerated files. By default, module will always generate astatic library named lib.a or a shared library named lib.so,which are standard Unix conventions. You can override this by defining LOCAL_MODULE_FILENAME, For example: LOCAL_MODULE := foo-version-1 LOCAL_MODULE_FILENAME := libfoo NOTE: You should not put a path or file extension in yourLOCAL_module_FILENAME, these will be handled automatically by thebuild system. LOCAL_SRC_FILES This is a list of source files that will be built for your module.Only list the files that will be passed to a compiler, since thebuild system automatically computes dependencies for you. Note that source files names are all relative to LOCAL_PATH and you can use path components, e.g.: LOCAL_SRC_FILES := foo.c \ toto/bar.c NOTE: Always use Unix-style forward slashes (/) in build files.Windows-style back-slashes will not be handled properly. LOCAL_CPP_EXTENSION This is an optional variable that can be defined to indicatethe file extension of C++ source files. The default is '.cpp'but you can change it. For example: LOCAL_CPP_EXTENSION := .cxx LOCAL_C_INCLUDES An optional list of paths, relative to the NDK *root* directory,which will be appended to the include search path when compilingall sources (C, C++ and Assembly). For example: LOCAL_C_INCLUDES := sources/foo Or even: LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo These are placed before any corresponding inclusion flag inLOCAL_CFLAGS / LOCAL_CPPFLAGS The LOCAL_C_INCLUDES path are also used automatically whenlaunching native debugging with ndk-gdb. LOCAL_CFLAGS An optional set of compiler flags that will be passed when buildingC *and* C++ source files. This can be useful to specify additional macro definitions orcompile options. IMPORTANT: Try not to change the optimization/debugging level inyour Android.mk, this can be handled automatically foryou by specifying the appropriate information in your Application.mk, and will let the NDK generateuseful data files used during debugging. NOTE: In android-ndk-1.5_r1, the corresponding flags only appliedto C source files, not C++ ones. This has been corrected tomatch the full Android build system behaviour. (You can useLOCAL_CPPFLAGS to specify flags for C++ sources only now). It is possible to specify additional include paths withLOCAL_CFLAGS += -I, however, it is better to use LOCAL_C_INCLUDESfor this, since the paths will then also be used during nativedebugging with ndk-gdb. LOCAL_CXXFLAGS An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsoleteas it may disappear in future releases of the NDK. LOCAL_CPPFLAGS An optional set of compiler flags that will be passed when buildingC++ source files *only*. They will appear after the LOCAL_CFLAGSon the compiler's command-line. NOTE: In android-ndk-1.5_r1, the corresponding flags applied toboth C and C++ sources. This has been corrected to match thefull Android build system. (You can use LOCAL_CFLAGS to specifyflags for both C and C++ sources now). LOCAL_STATIC_LIBRARIES The list of static libraries modules (built with BUILD_STATIC_LIBRARY)that should be linked to this module. This only makes sense inshared library modules. LOCAL_SHARED_LIBRARIES The list of shared libraries *modules* this module depends on at runtime.This is necessary at link time and to embed the corresponding informationin the generated file. LOCAL_WHOLE_STATIC_LIBRARIES A variant of LOCAL_STATIC_LIBRARIES used to express that the correspondinglibrary module should be used as "whole archives" to the linker. See theGNU linker's documentation for the --whole-archive flag. This is generally useful when there are circular dependencies betweenseveral static libraries. Note that when used to build a shared library,this will force all object files from your whole static libraries to beadded to the final binary. This is not true when generating executablesthough. LOCAL_LDLIBS The list of additional linker flags to be used when building yourmodule. This is useful to pass the name of specific system librarieswith the "-l" prefix. For example, the following will tell the linkerto generate a module that links to /system/lib/libz.so at load time: LOCAL_LDLIBS := -lz See docs/STABLE-APIS.html for the list of exposed system libraries youcan linked against with this NDK release. LOCAL_ALLOW_UNDEFINED_SYMBOLS By default, any undefined reference encountered when trying to builda shared library will result in an "undefined symbol" error. This is a great help to catch bugs in your source code. However, if for some reason you need to disable this check, set thisvariable to 'true'. Note that the corresponding shared library may failto load at runtime. LOCAL_ARM_MODE By default, ARM tARGet binaries will be generated in 'thumb' mode, whereeach instruction are 16-bit wide. You can define this variable to 'arm'if you want to force the generation of the module's object files in'arm' (32-bit instructions) mode. E.g.: LOCAL_ARM_MODE := arm Note that you can also instruct the build system to only build specificsources in ARM mode by appending an '.arm' suffix to its source filename. For example, with: LOCAL_SRC_FILES := foo.cbar.c.arm Tells the build system to always compile 'bar.c' in ARM mode, and tobuild foo.c according to the value of LOCAL_ARM_MODE. NOTE: Setting APP_OPTIM to 'debug' in your Application.mk will also forcethe generation of ARM binaries as well. This is due to bugs in thetoolchain debugger that don't deal too well with thumb code. LOCAL_ARM_NEON Defining this variable to 'true' allows the use of ARM Advanced SIMD(a.k.a. NEON) GCC intrinsics in your C and C++ sources, as well asNEON instructions in Assembly files. You should only define it when tARGeting the 'armeabi-v7a' ABI thatcorresponds to the ARMv7 instruction set. Note that not all ARMv7based CPUs support the NEON instruction set extensions and that youshould perform runtime detection to be able to use this code at runtimesafely. To learn more about this, please read the documentation atdocs/CPU-ARM-NEON.html and docs/CPU-FEATURES.html. Alternatively, you can also specify that only specific source filesmay be compiled with NEON support by using the '.neon' suffix, asin: LOCAL_SRC_FILES = foo.c.neonbar.czoo.c.arm.neon In this example, 'foo.c' will be compiled in thumb+neon mode,'bar.c' will be compiled in 'thumb' mode, and 'zoo.c' will becompiled in 'arm+neon' mode. Note that the '.neon' suffix must appear after the '.arm' suffixif you use both (i.e. foo.c.arm.neon works, but not foo.c.neon.arm !) LOCAL_DISABLE_NO_EXECUTE Android NDK r4 added support for the "NX bit" security feature.It is enabled by default, but you can disable it if you *really*need to by setting this variable to 'true'. NOTE: This feature does not modify the ABI and is only enabled onkernels targeting ARMv6+ CPU devices. Machine code generatedwith this feature enabled will run unmodified on devicesrunning earlier CPU architectures. For more information, see: LOCAL_EXPORT_CFLAGS Define this variable to record a set of C/C++ compiler flags that willbe added to the LOCAL_CFLAGS definition of any other module that usesthis one with LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES. For example, consider the module 'foo' with the following definition: include $(CLEAR_VARS) LOCAL_MODULE := foo LOCAL_SRC_FILES := foo/foo.c LOCAL_EXPORT_CFLAGS := -DFOO=1 include $(BUILD_STATIC_LIBRARY) And another module, named 'bar' that depends on it as: include $(CLEAR_VARS) LOCAL_MODULE := bar LOCAL_SRC_FILES := bar.c LOCAL_CFLAGS := -DBAR=2 LOCAL_STATIC_LIBRARIES := foo include $(BUILD_SHARED_LIBRARY) Then, the flags '-DFOO=1 -DBAR=2' will be passed to the compiler when buildingbar.c Exported flags are prepended to your module's LOCAL_CFLAGS so you can easily override them. They are also transitive: if 'zoo' depends on'bar' which depends on 'foo', then 'zoo' will also inherit all flagsexported by 'foo'. Finally, exported flags are *not* used when building the module thatexports them. In the above example, -DFOO=1 would not be passed to thecompiler when building foo/foo.c. LOCAL_EXPORT_CPPFLAGS Same as LOCAL_EXPORT_CFLAGS, but for C++ flags only. LOCAL_EXPORT_C_INCLUDES Same as LOCAL_EXPORT_CFLAGS, but for C include paths.This can be useful if 'bar.c' wants to include headersthat are provided by module 'foo'. LOCAL_EXPORT_LDLIBS Same as LOCAL_EXPORT_CFLAGS, but for linker flags. Note that theimported linker flags will be appended to your module's LOCAL_LDLIBSthough, due to the way Unix linkers work. This is typically useful when module 'foo' is a static library and hascode that depends on a system library. LOCAL_EXPORT_LDLIBS can then beused to export the dependency. For example: include $(CLEAR_VARS) LOCAL_MODULE := foo LOCAL_SRC_FILES := foo/foo.c LOCAL_EXPORT_LDLIBS := -llog include $(BUILD_STATIC_LIBRARY) include $(CLEAR_VARS) LOCAL_module := bar LOCAL_SRC_FILES := bar.c LOCAL_STATIC_LIBRARIES := foo include $(BUILD_SHARED_LIBRARY) There, libbar.so will be built with a -llog at the end of the linkercommand to indicate that it depends on the system logging library,because it depends on 'foo'. LOCAL_FILTER_ASM Define this variable to a shell command that will be used to filterthe assembly files from, or generated from, your LOCAL_SRC_FILES. When it is defined, the following happens: - Any C or C++ source file is generated into a temporary assemblyfile (instead of being compiled into an object file). - Any temporary assembly file, and any assembly file listed inLOCAL_SRC_FILES is sent through the LOCAL_FILTER_ASM commandto generate _another_ temporary assembly file. - These filtered assembly files are compiled into object file. In other words, If you have: LOCAL_SRC_FILES := foo.cbar.S LOCAL_FILTER_ASM := myasmfilter foo.c --1--> $OBJS_DIR/foo.S.original --2--> $OBJS_DIR/foo.S --3--> $OBJS_DIR/foo.o bar.S --2--> $OBJS_DIR/bar.S --3--> $OBJS_DIR/bar.o Were "1" corresponds to the compiler, "2" to the filter, and "3" to theassembler. The filter must be a standalone shell command that takes thename of the input file as its first ARGument, and the name of the outputfile as the second one, as in: myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S myasmfilterbar.S $OBJS_DIR/bar.S