Android.mk介绍
Introduction to Android.mk:
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 the sample Android project. - The 'jni' directory containing the native source for the sample, i.e. 'jni/hello-jni.c' This source file implements a simple shared library that implements a native method that returns a string to the VM application. - The 'jni/Android.mk' file that describes the shared library to the NDK build system. Its content is: LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE := hello-jni LOCAL_SRC_FILES := hello-jni.c include $(BUILD_SHARED_LIBRARY)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 return the path of the current directory (i.e. the directory containing the Android.mk file itself). include $(CLEAR_VARS)
The CLEAR_VARS variable is provided by the build system and points to a special 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 build control files are parsed in a single GNU Make execution context where all variables are global. LOCAL_MODULE := hello-jni
The LOCAL_MODULE variable must be defined to identify each module you describe in your Android.mk. The name must be *unique* and not contain any spaces. Note that the build system will automatically add proper prefix 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 not add 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++ source files that will be built and assembled into a module. Note that you should not list header and included files here, because the build system will compute dependencies automatically for you; just list the source files that will be passed directly to a compiler, and you should be good. Note that the default extension for C++ source files is '.cpp'. It is however possible to specify a different one by defining the variable LOCAL_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' will work, but not 'cxx'). include $(BUILD_SHARED_LIBRARY)
The BUILD_SHARED_LIBRARY is a variable provided by the build system that points to a GNU Makefile script that is in charge of collecting all the information you defined in LOCAL_XXX variables since the latest 'include $(CLEAR_VARS)' and determine what to build, and how to do it exactly. There is also BUILD_STATIC_LIBRARY to generate a static library. There are more complex examples in the samples directories, with commented Android.mk files that you can look at. Reference:
This is the list of variables you should either rely on or define in an Android.mk. You can define other variables for your own usage, but the 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.mk file, we recommend using the MY_ prefix, for a trivial example:MY_SOURCES := foo.c ifneq ($(MY_CONFIG_BAR),) MY_SOURCES += bar.c endif LOCAL_SRC_FILES += $(MY_SOURCES)So, here we go:
NDK-provided variables:
These GNU Make variables are defined by the build system before your Android.mk file is parsed. Note that under certain circumstances the NDK might parse your Android.mk several times, each with different definition for some of these variables. CLEAR_VARS Points to a build script that undefines nearly all LOCAL_XXX variables listed in the "Module-description" section below. You must include the 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 the module you provided in LOCAL_XXX variables and determines how to build a target shared library from the sources you listed. Note that you must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before including 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 your project/packages but can be used to build shared libraries (see LOCAL_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 shared library (e.g. foo/libfoo.so), instead of a source file. You can reference the prebuilt library in another module using the LOCAL_PREBUILTS variable (see docs/PREBUILTS.html for more information). PREBUILT_STATIC_LIBRARY This is the same as PREBUILT_SHARED_LIBRARY, but for a static library file instead. See docs/PREBUILTS.html for more. TARGET_ARCH Name of the target CPU architecture as it is specified by the full Android open-source build. This is 'arm' for any ARM-compatible build, 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. For a complete list of platform names and corresponding Android system images, 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 defined as 'arm'. However, the value has been redefined to better match what is used internally by the Android platform. For more details about architecture ABIs and corresponding compatibility issues, please read docs/CPU-ARCH-ABIS.html Other target ABIs will be introduced in future releases of the NDK and will have a different name. Note that all ARM-based ABIs will have 'TARGET_ARCH' defined to 'arm', but may have different 'TARGET_ARCH_ABI' TARGET_ABI The concatenation of target platform and ABI, it really is defined as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want to 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 evaluated by using '$(call <function>)'. They return textual information. my-dir Returns the path of the last included Makefile, which typically is the current Android.mk's$(call import-module,<name>)
Module-description variables:
The following variables are used to describe your module to the build system. You should define some of them between an 'include $(CLEAR_VARS)' and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is a script that will undefine/clear all of these variables, unless explicitly noted 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 can be done with:LOCAL_PATH := $(call my-dir)
This variable is *not* cleared by $(CLEAR_VARS) so only one definition per Android.mk is needed (in case you define several modules in a single file). LOCAL_MODULE This is the name of your module. It must be unique among all module names, and shall not contain any space. You MUST define it before including any $(BUILD_XXXX) script. By default, the module name determines the name of generated files, e.g. lib<foo>.so for a shared library module named <foo>. However you should only refer to other modules with their 'normal' name (e.g. <foo>) in your NDK build files (either Android.mk or 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 of generated files. By default, module <foo> will always generate a static library named lib<foo>.a or a shared library named lib<foo>.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 your LOCAL_MODULE_FILENAME, these will be handled automatically by the build 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 the build 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 indicate the file extension of C++ source files. The default is '.cpp' but you can change it. For example: LOCAL_CPP_EXTENSION := .cxx
Since NDK r7, you can list several extensions in this variable, as in: LOCAL_CPP_EXTENSION := .cxx .cpp .cc
LOCAL_CPP_FEATURES This is an optional variable that can be defined to indicate that your code relies on specific C++ features. To indicate that your code uses RTTI (RunTime Type Information), use the following: LOCAL_CPP_FEATURES := rtti
To indicate that your code uses C++ exceptions, use: LOCAL_CPP_FEATURES := exceptions
You can also use both of them with (order is not important): LOCAL_CPP_FEATURES := rtti exceptions
The effect of this variable is to enable the right compiler/linker flags when building your modules from sources. For prebuilt binaries, this also helps declare which features the binary relies on to ensure the final link works correctly. It is recommended to use this variable instead of enabling -frtti and -fexceptions directly in your LOCAL_CPPFLAGS definition. LOCAL_C_INCLUDES An optional list of paths, relative to the NDK *root* directory, which will be appended to the include search path when compiling all 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 in LOCAL_CFLAGS / LOCAL_CPPFLAGS The LOCAL_C_INCLUDES path are also used automatically when launching native debugging with ndk-gdb. LOCAL_CFLAGS An optional set of compiler flags that will be passed when building C *and* C++ source files. This can be useful to specify additional macro definitions or compile options. IMPORTANT: Try not to change the optimization/debugging level in your Android.mk, this can be handled automatically for you by specifying the appropriate information in your Application.mk, and will let the NDK generate useful data files used during debugging. NOTE: In android-ndk-1.5_r1, the corresponding flags only applied to C source files, not C++ ones. This has been corrected to match the full Android build system behaviour. (You can use LOCAL_CPPFLAGS to specify flags for C++ sources only now). It is possible to specify additional include paths with LOCAL_CFLAGS += -I<path>, however, it is better to use LOCAL_C_INCLUDES for this, since the paths will then also be used during native debugging with ndk-gdb. LOCAL_CXXFLAGS An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete as it may disappear in future releases of the NDK. LOCAL_CPPFLAGS An optional set of compiler flags that will be passed when building C++ source files *only*. They will appear after the LOCAL_CFLAGS on the compiler's command-line. NOTE: In android-ndk-1.5_r1, the corresponding flags applied to both C and C++ sources. This has been corrected to match the full Android build system. (You can use LOCAL_CFLAGS to specify flags 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 in shared 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 information in the generated file. LOCAL_WHOLE_STATIC_LIBRARIES A variant of LOCAL_STATIC_LIBRARIES used to express that the corresponding library module should be used as "whole archives" to the linker. See the GNU linker's documentation for the --whole-archive flag. This is generally useful when there are circular dependencies between several static libraries. Note that when used to build a shared library, this will force all object files from your whole static libraries to be added to the final binary. This is not true when generating executables though. LOCAL_LDLIBS The list of additional linker flags to be used when building your module. This is useful to pass the name of specific system libraries with the "-l" prefix. For example, the following will tell the linker to 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 you can linked against with this NDK release. LOCAL_ALLOW_UNDEFINED_SYMBOLS By default, any undefined reference encountered when trying to build a 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 this variable to 'true'. Note that the corresponding shared library may fail to load at runtime. Building a simple APK
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # Build all java files in the java subdirectory LOCAL_SRC_FILES := $(call all-subdir-java-files) # Name of the APK to build LOCAL_PACKAGE_NAME := LocalPackage # Tell it to build an APK include $(BUILD_PACKAGE)
Building a APK that depends on a static .jar file
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # List of static libraries to include in the package LOCAL_STATIC_JAVA_LIBRARIES := static-library # Build all java files in the java subdirectory LOCAL_SRC_FILES := $(call all-subdir-java-files) # Name of the APK to build LOCAL_PACKAGE_NAME := LocalPackage # Tell it to build an APK include $(BUILD_PACKAGE)
Building a APK that should be signed with the platform key
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # Build all java files in the java subdirectory LOCAL_SRC_FILES := $(call all-subdir-java-files) # Name of the APK to build LOCAL_PACKAGE_NAME := LocalPackage LOCAL_CERTIFICATE := platform # Tell it to build an APK include $(BUILD_PACKAGE)
Building a APK that should be signed with a specific vendor key
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # Build all java files in the java subdirectory LOCAL_SRC_FILES := $(call all-subdir-java-files) # Name of the APK to build LOCAL_PACKAGE_NAME := LocalPackage LOCAL_CERTIFICATE := vendor/example/certs/app # Tell it to build an APK include $(BUILD_PACKAGE)
Adding a prebuilt APK
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # Module name should match apk name to be installed. LOCAL_MODULE := LocalModuleName LOCAL_SRC_FILES := $(LOCAL_MODULE).apk LOCAL_MODULE_CLASS := APPS LOCAL_MODULE_SUFFIX := $(COMMON_ANDROID_PACKAGE_SUFFIX) include $(BUILD_PREBUILT)
Adding a Static Java Library
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) # Build all java files in the java subdirectory LOCAL_SRC_FILES := $(call all-subdir-java-files) # Any libraries that this library depends on LOCAL_JAVA_LIBRARIES := android.test.runner # The name of the jar file to create LOCAL_MODULE := sample # Build a static jar file. include $(BUILD_STATIC_JAVA_LIBRARY)
Android.mk Variables
- 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.
- 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.
Parameter | Description |
---|---|
LOCAL_AAPT_FLAGS | |
LOCAL_ACP_UNAVAILABLE | |
LOCAL_ADDITIONAL_JAVA_DIR | |
LOCAL_AIDL_INCLUDES | |
LOCAL_ALLOW_UNDEFINED_SYMBOLS | |
LOCAL_ARM_MODE | |
LOCAL_ASFLAGS | |
LOCAL_ASSET_DIR | |
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_BUILT_MODULE_STEM | |
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
You should not add subdirectories of include to
|
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_CERTIFICATE | |
LOCAL_CFLAGS | If you have additional flags to pass into the C or C++ compiler, add them here. For example:
|
LOCAL_CLASSPATH | |
LOCAL_COMPRESS_MODULE_SYMBOLS | |
LOCAL_COPY_HEADERS | The set of files to copy to the install include tree. You must also supply 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 | The directory within "include" to copy the headers listed in 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_CPP_EXTENSION | If your C++ files end in something other than ".cpp ", you can specify the custom extension here. For example:
|
LOCAL_CPPFLAGS | If you have additional flags to pass into only the C++ compiler, add them here. For example:
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_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_DX_FLAGS | |
LOCAL_EXPORT_PACKAGE_RESOURCES | |
LOCAL_FORCE_STATIC_EXECUTABLE | If your executable should be linked statically, set |
LOCAL_GENERATED_SOURCES | Files that you add to |
LOCAL_INSTRUMENTATION_FOR | |
LOCAL_INSTRUMENTATION_FOR_PACKAGE_NAME | |
LOCAL_INTERMEDIATE_SOURCES | |
LOCAL_INTERMEDIATE_TARGETS | |
LOCAL_IS_HOST_MODULE | |
LOCAL_JAR_MANIFEST | |
LOCAL_JARJAR_RULES | |
LOCAL_JAVA_LIBRARIES | When linking Java apps and libraries,
Note that setting |
LOCAL_JAVA_RESOURCE_DIRS | |
LOCAL_JAVA_RESOURCE_FILES | |
LOCAL_JNI_SHARED_LIBRARIES | |
LOCAL_LDFLAGS | You can pass additional flags to the linker by setting |
LOCAL_LDLIBS |
|
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 . |
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_MODULE_STEM | |
LOCAL_MODULE_TAGS | Set This variable controls what build flavors the package gets included in. For example:
|
LOCAL_NO_DEFAULT_COMPILER_FLAGS | |
LOCAL_NO_EMMA_COMPILE | |
LOCAL_NO_EMMA_INSTRUMENT | |
LOCAL_NO_STANDARD_LIBRARIES | |
LOCAL_OVERRIDES_PACKAGES | |
LOCAL_PACKAGE_NAME | LOCAL_PACKAGE_NAME is the name of an app. For example, Dialer, Contacts, etc. |
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:
|
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_JAVA_LIBRARIES | |
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_PREBUILT_OBJ_FILES | |
LOCAL_PREBUILT_STATIC_JAVA_LIBRARIES | |
LOCAL_PRELINK_MODULE | |
LOCAL_REQUIRED_MODULES | Set |
LOCAL_RESOURCE_DIR | |
LOCAL_SDK_VERSION | |
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_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_STATIC_JAVA_LIBRARIES | |
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_UNINSTALLABLE_MODULE | |
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 overrode LOCAL_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_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.
|
OVERRIDE_BUILT_MODULE_PATH |
If you would like to contribute, fork https://github.com/kanassar/android.mk and submit a pull request.