Android.mk variables


These are the variables that you'll commonly see in Android.mk files, listed alphabetically.


But first, a note on variable naming:


    LOCAL_ - These variables are set per-module. They are cleared by the include $(CLEAR_VARS) line, so you can rely on them being empty after including that file. Most of the variables you'll use in most modules are LOCAL_ variables.

    PRIVATE_ - These variables are make-target-specific variables. That means they're only usable within the commands for that module. It also means that they're unlikely to change behind your back from modules that are included after yours. This link to the make documentation describes more about target-specific variables. Please note that there are a couple of these laying around the tree that aren't prefixed with PRIVATE_. It is safe, and they will be fixed as they are discovered. Sorry for the confusion.

    INTERNAL_ - These variables are critical to functioning of the build system, so you shouldn't create variables named like this, and you probably shouldn't be messing with these variables in your makefiles.

    HOST_ and TARGET_ - These contain the directories and definitions that are specific to either the host or the target builds. Do not set variables that start with HOST_ or TARGET_ in your makefiles.

    BUILD_ and CLEAR_VARS - These contain the names of well-defined template makefiles to include. Some examples are CLEAR_VARS and BUILD_HOST_PACKAGE.

    Any other name is fair-game for you to use in your Android.mk. However, remember that this is a non-recursive build system, so it is possible that your variable will be changed by another Android.mk included later, and be different when the commands for your rule / module are executed.


LOCAL_ASSET_FILES


In Android.mk files that include $(BUILD_PACKAGE) set this to the set of files you want built into your app. Usually:


LOCAL_ASSET_FILES += $(call find-subdir-assets)


This will probably change when we switch to ant for the apps' build system.

LOCAL_CC


If you want to use a different C compiler for this module, set LOCAL_CC to the path to the compiler. If LOCAL_CC is blank, the appropriate default compiler is used.

LOCAL_CXX


If you want to use a different C++ compiler for this module, set LOCAL_CXX to the path to the compiler. If LOCAL_CXX is blank, the appropriate default compiler is used.

LOCAL_CFLAGS


If you have additional flags to pass into the C or C++ compiler, add them here. For example:


LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1

LOCAL_CPPFLAGS


If you have additional flags to pass into only the C++ compiler, add them here. For example:


LOCAL_CPPFLAGS += -ffriend-injection

LOCAL_CPPFLAGS is guaranteed to be after LOCAL_CFLAGS on the compile line, so you can use it to override flags listed in LOCAL_CFLAGS.

LOCAL_CPP_EXTENSION


If your C++ files end in something other than ".cpp", you can specify the custom extension here. For example:


LOCAL_CPP_EXTENSION := .cc

Note that all C++ files for a given module must have the same extension; it is not currently possible to mix different extensions.

LOCAL_NO_DEFAULT_COMPILER_FLAGS


Normally, the compile line for C and C++ files includes global include paths and global cflags. If LOCAL_NO_DEFAULT_COMPILER_FLAGS is non-empty, none of the default includes or flags will be used when compiling C and C++ files in this module. LOCAL_C_INCLUDES, LOCAL_CFLAGS, and LOCAL_CPPFLAGS will still be used in this case, as will any DEBUG_CFLAGS that are defined for the module.

LOCAL_COPY_HEADERS


This will be going away.


The set of files to copy to the install include tree. You must also supply LOCAL_COPY_HEADERS_TO.


This is going away because copying headers messes up the error messages, and may lead to people editing those headers instead of the correct ones. It also makes it easier to do bad layering in the system, which we want to avoid. We also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any headers.

LOCAL_COPY_HEADERS_TO


This will be going away.


The directory within "include" to copy the headers listed in LOCAL_COPY_HEADERS to.


This is going away because copying headers messes up the error messages, and may lead to people editing those headers instead of the correct ones. It also makes it easier to do bad layering in the system, which we want to avoid. We also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any headers.

LOCAL_C_INCLUDES


Additional directories to instruct the C/C++ compilers to look for header files in. These paths are rooted at the top of the tree. Use LOCAL_PATH if you have subdirectories of your own that you want in the include paths. For example:


LOCAL_C_INCLUDES += extlibs/zlib-1.2.3

LOCAL_C_INCLUDES += $(LOCAL_PATH)/src


You should not add subdirectories of include to LOCAL_C_INCLUDES, instead you should reference those files in the #include statement with their subdirectories. For example:


#include <utils/KeyedVector.h>

not #include <KeyedVector.h>


There are some components that are doing this wrong, and should be cleaned up.

LOCAL_MODULE_TAGS


Set LOCAL_MODULE_TAGS to any number of whitespace-separated tags. If the tag list is empty or contains droid, the module will get installed as part of a make droid. Modules with the tagshell_$(TARGET_SHELL) will also be installed. Otherwise, it will only get installed by running make <your-module> or with the make all pseudotarget.

LOCAL_REQUIRED_MODULES


Set LOCAL_REQUIRED_MODULES to any number of whitespace-separated module names, like "libblah" or "Email". If this module is installed, all of the modules that it requires will be installed as well. This can be used to, e.g., ensure that necessary shared libraries or providers are installed when a given app is installed.

LOCAL_FORCE_STATIC_EXECUTABLE


If your executable should be linked statically, set LOCAL_FORCE_STATIC_EXECUTABLE:=true. There is a very short list of libraries that we have in static form (currently only libc). This is really only used for executables in /sbin on the root filesystem.

LOCAL_GENERATED_SOURCES


Files that you add to LOCAL_GENERATED_SOURCES will be automatically generated and then linked in when your module is built. See the Custom Tools template makefile for an example.

LOCAL_JAVACFLAGS


If you have additional flags to pass into the javac compiler, add them here. For example:


LOCAL_JAVACFLAGS += -Xlint:deprecation

LOCAL_JAVA_LIBRARIES


When linking Java apps and libraries, LOCAL_JAVA_LIBRARIES specifies which sets of java classes to include. Currently there are two of these: core and framework. In most cases, it will look like this:


LOCAL_JAVA_LIBRARIES := core framework


Note that setting LOCAL_JAVA_LIBRARIES is not necessary (and is not allowed) when building an APK with "include $(BUILD_PACKAGE)". The appropriate libraries will be included automatically.

LOCAL_LDFLAGS


You can pass additional flags to the linker by setting LOCAL_LDFLAGS. Keep in mind that the order of parameters is very important to ld, so test whatever you do on all platforms.

LOCAL_LDLIBS


LOCAL_LDLIBS allows you to specify additional libraries that are not part of the build for your executable or library. Specify the libraries you want in -lxxx format; they're passed directly to the link line. However, keep in mind that there will be no dependency generated for these libraries. It's most useful in simulator builds where you want to use a library preinstalled on the host. The linker (ld) is a particularly fussy beast, so it's sometimes necessary to pass other flags here if you're doing something sneaky. Some examples:


LOCAL_LDLIBS += -lcurses -lpthread

LOCAL_LDLIBS += -Wl,-z,origin

LOCAL_NO_MANIFEST


If your package doesn't have a manifest (AndroidManifest.xml), then set LOCAL_NO_MANIFEST:=true. The common resources package does this.

LOCAL_PACKAGE_NAME


LOCAL_PACKAGE_NAME is the name of an app. For example, Dialer, Contacts, etc. This will probably change or go away when we switch to an ant-based build system for the apps.

LOCAL_PATH


The directory your Android.mk file is in. You can set it by putting the following as the first line in your Android.mk:


LOCAL_PATH := $(my-dir)


The my-dir macro uses the MAKEFILE_LIST variable, so you must call it before you include any other makefiles. Also, consider that any subdirectories you inlcude might reset LOCAL_PATH, so do your own stuff before you include them. This also means that if you try to write several include lines that reference LOCAL_PATH, it won't work, because those included makefiles might reset LOCAL_PATH.

LOCAL_POST_PROCESS_COMMAND


For host executables, you can specify a command to run on the module after it's been linked. You might have to go through some contortions to get variables right because of early or late variable evaluation:


module := $(HOST_OUT_EXECUTABLES)/$(LOCAL_MODULE)

LOCAL_POST_PROCESS_COMMAND := /Developer/Tools/Rez -d __DARWIN__ -t APPL\

       -d __WXMAC__ -o $(module) Carbon.r

LOCAL_PREBUILT_EXECUTABLES


When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to executables that you want copied. They're located automatically into the right bin directory.

LOCAL_PREBUILT_LIBS


When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to libraries that you want copied. They're located automatically into the right lib directory.

LOCAL_SHARED_LIBRARIES


These are the libraries you directly link against. You don't need to pass transitively included libraries. Specify the name without the suffix:


LOCAL_SHARED_LIBRARIES := \

    libutils \

    libui \

    libaudio \

    libexpat \

    libsgl

LOCAL_SRC_FILES


The build system looks at LOCAL_SRC_FILES to know what source files to compile -- .cpp .c .y .l .java. For lex and yacc files, it knows how to correctly do the intermediate .h and .c/.cpp files automatically. If the files are in a subdirectory of the one containing the Android.mk, prefix them with the directory name:


LOCAL_SRC_FILES := \

    file1.cpp \

    dir/file2.cpp

LOCAL_STATIC_LIBRARIES


These are the static libraries that you want to include in your module. Mostly, we use shared libraries, but there are a couple of places, like executables in sbin and host executables where we use static libraries instead.


LOCAL_STATIC_LIBRARIES := \

    libutils \

    libtinyxml

LOCAL_MODULE


LOCAL_MODULE is the name of what's supposed to be generated from your Android.mk. For exmample, for libkjs, the LOCAL_MODULE is "libkjs" (the build system adds the appropriate suffix -- .so .dylib .dll). For app modules, use LOCAL_PACKAGE_NAME instead of LOCAL_MODULE. We're planning on switching to ant for the apps, so this might become moot.

LOCAL_MODULE_PATH


Instructs the build system to put the module somewhere other than what's normal for its type. If you override this, make sure you also set LOCAL_UNSTRIPPED_PATH if it's an executable or a shared library so the unstripped binary has somewhere to go. An error will occur if you forget to.


See Putting modules elsewhere for more.

LOCAL_UNSTRIPPED_PATH


Instructs the build system to put the unstripped version of the module somewhere other than what's normal for its type. Usually, you override this because you overrodeLOCAL_MODULE_PATH for an executable or a shared library. If you overrode LOCAL_MODULE_PATH, but not LOCAL_UNSTRIPPED_PATH, an error will occur.


See Putting modules elsewhere for more.

LOCAL_WHOLE_STATIC_LIBRARIES


These are the static libraries that you want to include in your module without allowing the linker to remove dead code from them. This is mostly useful if you want to add a static library to a shared library and have the static library's content exposed from the shared library.


LOCAL_WHOLE_STATIC_LIBRARIES := \

    libsqlite3_android

LOCAL_YACCFLAGS


Any flags to pass to invocations of yacc for your module. A known limitation here is that the flags will be the same for all invocations of YACC for your module. This can be fixed. If you ever need it to be, just ask.


LOCAL_YACCFLAGS := -p kjsyy

Implementation Details


You should never have to touch anything in the config directory unless you're adding a new platform, new tools, or adding new features to the build system. In general, please consult with the build system owner(s) (android-build-team) before you go mucking around in here. That said, here are some notes on what's going on under the hood.

Environment Setup / buildspec.mk Versioning


In order to make easier for people when the build system changes, when it is necessary to make changes to buildspec.mk or to rerun the environment setup scripts, they contain a version number in the variable BUILD_ENV_SEQUENCE_NUMBER. If this variable does not match what the build system expects, it fails printing an error message explaining what happened. If you make a change that requires an update, you need to update two places so this message will be printed.


    In config/envsetup.make, increment the CORRECT_BUILD_ENV_SEQUENCE_NUMBER definition.

    In buildspec.mk.default, update the BUILD_ENV_SEQUENCE_DUMBER definition to match the one in config/envsetup.make


The scripts automatically get the value from the build system, so they will trigger the warning as well.


Additional makefile variables


You probably shouldn't use these variables. Please consult android-build-team before using them. These are mostly there for workarounds for other issues, or things that aren't completely done right.

LOCAL_ADDITIONAL_DEPENDENCIES


If your module needs to depend on anything else that isn't actually built in to it, you can add those make targets to LOCAL_ADDITIONAL_DEPENDENCIES. Usually this is a workaround for some other dependency that isn't created automatically.

LOCAL_BUILT_MODULE


When a module is built, the module is created in an intermediate directory then copied to its final location. LOCAL_BUILT_MODULE is the full path to the intermediate file. See LOCAL_INSTALLED_MODULE for the path to the final installed location of the module.

LOCAL_HOST


Set by the host_xxx.make includes to tell base_rules.make and the other includes that we're building for the host. Kenneth did this as part of openbinder, and I would like to clean it up so the rules, includes and definitions aren't duplicated for host and target.

LOCAL_INSTALLED_MODULE


The fully qualified path name of the final location of the module. See LOCAL_BUILT_MODULE for the location of the intermediate file that the make rules should actually be constructing.

LOCAL_REPLACE_VARS


Used in some stuff remaining from the openbinder for building scripts with particular values set,

LOCAL_SCRIPTS


Used in some stuff remaining from the openbinder build system that we might find handy some day.

LOCAL_MODULE_CLASS


Which kind of module this is. This variable is used to construct other variable names used to locate the modules. See base_rules.make and envsetup.make.

LOCAL_MODULE_NAME


Set to the leaf name of the LOCAL_BUILT_MODULE. I'm not sure, but it looks like it's just used in the WHO_AM_I variable to identify in the pretty printing what's being built.

LOCAL_MODULE_SUFFIX


The suffix that will be appended to LOCAL_MODULE to form LOCAL_MODULE_NAME. For example, .so, .a, .dylib.

LOCAL_STRIP_MODULE


Calculated in base_rules.make to determine if this module should actually be stripped or not, based on whether LOCAL_STRIPPABLE_MODULE is set, and whether the combo is configured to ever strip modules. With Iliyan's stripping tool, this might change.

LOCAL_STRIPPABLE_MODULE


Set by the include makefiles if that type of module is strippable. Executables and shared libraries are.

LOCAL_SYSTEM_SHARED_LIBRARIES


Used while building the base libraries: libc, libm, libdl. Usually it should be set to "none," as it is in $(CLEAR_VARS). When building these libraries, it's set to the ones they link against. For example, libc, libstdc++ and libdl don't link against anything, and libm links against libc. Normally, when the value is none, these libraries are automatically linked in to execu

+ Recent posts