翻译在最下面
Android.mk file syntax specification
Introduction:
-------------
This document describes the syntax of Android.mk build file
written to describe your C and C++ source files to the Android
NDK. To understand what follows, it is assumed that you have
read the docs/OVERVIEW.html file that explains their role and
usage.
Overview:
---------
An Android.mk file is written to describe your sources to the
build 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, you
should 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 your
application package. Static libraries can be used to generate
shared 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, you
don't need to list header files or explicit dependencies between
generated files in your Android.mk. The NDK build system will
compute 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 support
without having to touch your Android.mk files.
Note that the syntax is *very* close to the one used in Android.mk files
distributed with the full open-source Android platform sources. While
the build system implementation that uses them is different, this is
an 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 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:
---------- 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 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:
---------- 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 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 directory. This is useful to define
LOCAL_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 returns
the path of the *last* *included* *Makefile* during the parsing of
build 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 define
LOCAL_PATH to $PATH/foo instead of $PATH, due to the include that
was performed before that.
For this reason, it's better to put additional includes after
everything 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 call
into 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 of
the current 'my-dir' path. For example, consider the following
hierarchy:
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 and
sources/foo/lib2/Android.mk
This function can be used to provide deep-nested source directory
hierarchies to the build system. Note that by default, the NDK
will only look for files in sources/*/Android.mk
this-makefile
Returns the path of the current Makefile (i.e. where the function
is 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.mk
of another module by name. A typical example is:
$(call import-module,<name>)
And this will look for the module tagged <name> in the list of
directories referenced by your NDK_MODULE_PATH environment
variable, 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 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(s) of C++ source files. They must begin with a dot.
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 features
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.
LOCAL_ARM_MODE
By default, ARM target binaries will be generated in 'thumb' mode, where
each 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 specific
sources in ARM mode by appending an '.arm' suffix to its source file
name. For example, with:
LOCAL_SRC_FILES := foo.c bar.c.arm
Tells the build system to always compile 'bar.c' in ARM mode, and to
build foo.c according to the value of LOCAL_ARM_MODE.
NOTE: Setting APP_OPTIM to 'debug' in your Application.mk will also force
the generation of ARM binaries as well. This is due to bugs in the
toolchain 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 as
NEON instructions in Assembly files.
You should only define it when targeting the 'armeabi-v7a' ABI that
corresponds to the ARMv7 instruction set. Note that not all ARMv7
based CPUs support the NEON instruction set extensions and that you
should perform runtime detection to be able to use this code at runtime
safely. To learn more about this, please read the documentation at
docs/CPU-ARM-NEON.html and docs/CPU-FEATURES.html.
Alternatively, you can also specify that only specific source files
may be compiled with NEON support by using the '.neon' suffix, as
in:
LOCAL_SRC_FILES = foo.c.neon bar.c zoo.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 be
compiled in 'arm+neon' mode.
Note that the '.neon' suffix must appear after the '.arm' suffix
if 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 on
kernels targeting ARMv6+ CPU devices. Machine code generated
with this feature enabled will run unmodified on devices
running earlier CPU architectures.
For more information, see:
http://en.wikipedia.org/wiki/NX_bit
http://www.gentoo.org/proj/en/hardened/gnu-stack.xml
LOCAL_EXPORT_CFLAGS
Define this variable to record a set of C/C++ compiler flags that will
be added to the LOCAL_CFLAGS definition of any other module that uses
this 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
building bar.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 flags
exported by 'foo'.
Finally, exported flags are *not* used when building the module that
exports them. In the above example, -DFOO=1 would not be passed to the
compiler 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 headers
that are provided by module 'foo'.
LOCAL_EXPORT_LDLIBS
Same as LOCAL_EXPORT_CFLAGS, but for linker flags. Note that the
imported linker flags will be appended to your module's LOCAL_LDLIBS
though, due to the way Unix linkers work.
This is typically useful when module 'foo' is a static library and has
code that depends on a system library. LOCAL_EXPORT_LDLIBS can then be
used 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 linker
command 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 filter
the 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 assembly
file (instead of being compiled into an object file).
- Any temporary assembly file, and any assembly file listed in
LOCAL_SRC_FILES is sent through the LOCAL_FILTER_ASM command
to generate _another_ temporary assembly file.
- These filtered assembly files are compiled into object file.
In other words, If you have:
LOCAL_SRC_FILES := foo.c bar.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 the
assembler. The filter must be a standalone shell command that takes the
name of the input file as its first argument, and the name of the output
file as the second one, as in:
myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S
myasmfilter bar.S $OBJS_DIR/bar.S
----------------------------------------------------------------------------------------------------------------------------------------------------------
Android.mk文件语法规范
序言：
-------------
此文档旨在描述Android.mk文件的语法，Android.mk文件为Android NDK 描述你的C/C++源文件。
要明白接下来的内容，你必须阅读docs/OVERVIEW.html文件，它解释了Android.mk文件担任的角色和用途。
概述：
---------
写一个Android.mk文件是为了向编译系统描述你的代码。更明确的说：
- 这个文件实际上是GNU Make文件的一小片段，它会被编译系统解析一次或多次。
因此，你应该在Android.mk里尽量少地声明变量，而不要误以为在解析的过程中没有任何东西被定义。
- Android.mk文件旨在让你使用其语法将你的源代码组织为模块（module).一个模块指的是下面的一项：
- 一个静态库（static library)
- 一个共享库（shared library)
只有动态库可以被java程序加载后使用。但是静态库可用来生成动态库。
你可以在每个Android.mk文件定义一个或多个模块，并且我可以在几个模块中使用相同的源文件。
- 编译系统帮你处理了许多零散琐碎之事。比如，在你的Android.mk里，你不需要列出头文件或者要编译的文件之间明确的依赖关系。NDK会为你计算生成。
也就是说，当你更新NDK版本时，新的工具链/平台支持（toolchain/platform support)让你无需修改你的android.mk文件。
注意：此语法非常接近于Android平台的Android.mk文件的语法，但它们的编译系统的实现不同，这是为了让开发者能更容易复用第三方库的源代码。
简单例子：
---------------
在学习语法之前，先看一个简单的“hello JNI”例子，它的文件位于：
samples\hello-jni
这里，我们能看到：
- 放有Java源文件的src文件夹。
- 放有native源文件，即jni/hello-jni.c的jni文件夹。
这套源文件可以编译成一个动态库。这个动态库有一个native方法（native method)，它将一个字符串
返回给Java应用程序.
- jni/Anroid.mk文件为编译系统描述了这个动态库。如下：
---------- 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 ------------------
现在，让我们逐行解释：
LOCAL_PATH := $(call my-dir)
每个Android.mk文件都必须以定义LOCAL_PATH变量开始。其目的是为了描述源文件的位置。在这个例子，
编译系统提供的宏函数（macro function)‘my-dir'用来返回当前路径（即放有Android.mk文件的文件夹）
include $(CLEAR_VARS)
CLEAR_VARS变量是编译系统提供的，它指向一个特殊的GNU Makefile.这个Makefile将会为你自动清除许多名为LOCAL_XXX的变量(比如：LOCAL_MODULE,LOCAL_SRC_FILES,LOCAL_STATIC_LIBRARIES,等),但LOCAL_PATH除外，它不会被清除。清除这些变量是必须的，因为所有的控制文件是在一个GNU make执行环境中解析的，在这里所有的变量都是全局的。
LOCAL_MODULE := hello-jni
为了在Android.mk文件识别每个模块，必须定义LOCAL_MODULE变量。这个名字必须要唯一的并且不能包含空格。
注意：编译系统会自动地为生成的库文件加上前缀或后缀。例如，一个名为foo的动态库模块会生成'libfoo.so'.
重要注意事项：
如果模块取名为‘libfoo',生成系统将不会加上‘lib'前缀，还是生成libfoo.so。
LOCAL_SRC_FILES := hello-jni.c
LOCAL_SRC_FILES变量必须包含一系列将被编译和组合成模块的C/C++源文件。
注意：你不需要列出头文件或include文件，因为NDK会为你自动计算出源文件的依赖关系。列出那些源文件就够了。
注意，默认的C++源文件的扩展名是‘.cpp'。但你可以通过定义LOCAL_DEFAULT_EXTENSION来指定一个扩展名。别忘了扩展名开始的那一点（比如,‘.cxx’,能行，但‘cxx'不行)。
include $(BUILD_SHARED_LIBRARY)
编译系统提供的BUIL_SHARED_LIBRARY变量指向一个GNU Makefile脚本，这个脚本主要收集在最近的一次
#include $(CLEAR_VARS)(著：即清除'本地'变量)之后你所定义的LOCAL_XXX变量的信息，并决定生成什么库，如何准确的编译。
BUILD_STATIC_LIBRARY可生成一个静态库。
在samples目录下有一些复杂点的例子，它带有注释的Android.mk文件以供你学习。
参考：
-----------
以下列出你在Android.mk里应该依赖或定义的变量。你能定义其它变量，但下列的变量名是
由NDK编译系统保留的。
- 以LOCAL_ 开头的变量名 (比如，LOCAL_MODULE)
- 以PRIVATE_ ,NDK_ 或 APP_ (内部使用)开头的变量名
_ 小写字母变量名(内部使用,如 my-dir).
如果你需要在Android.mk里定义方便自己使用的变量名，我们建议使用MY_ 前缀,
如下面一个简单例子:
---------- 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提供的变量：
- - - - - - - - - - - - - -
下列的这些GNU Make变量是在你的Android.mk被解析之前，就被NDK系统事先定义的了.
注意,在某些情况下,NDK可能会多次解析你的Android.mk，每次解析都会定义不同的变量。
CLEAR_VARS
指向一个编译脚本(编译时就会执行这个脚本)，这个脚本清除所有LOCAL_XXX变量的定义（除了LOCAL_PATH)。
在开始描述一个新的模块之前，你必须include这个脚本，e.g.：
include $(CLEAR_VARS)
BUILD_SHARED_LIBRARY
指向一个编译脚本，这个脚本通过LOCAL_XXX变量收集关于模块的信息，
并根据你列出来的源文件生成目标动态库。注意，在include这个脚本文件之前你必须
至少已经定义了LOCAL_MODULE和LOCAL_SRC_FILES。用法：
include $(BUILD_SHARED_LIBRARY)
注意，这会生成一个名为 lib$(LOCAL_MODULE).so的文件。（$(BUILD_SHARED_MODULE)为文件名）
BUILD_STATIC_LIBRARY
与BUILD_SHARED_LIBRARY类似，但用来生成目标静态库。静态库不会被拷贝至你的
project/packages文件夹下，但可用来生成动态库（参考 LOCAL_STATIC_LIBRARIES
和LOCAL_STATIC_WHOLE_LIBRARIES，将在后面解释）
用法示例：
include $(BUILD_STATIC_LIBRARY)
注意，这会生成一个方件名叫lib$(LOCAL_MODULE).a
PREBUILT_SHARED_LIBRARY
指向一个编译脚本,用于指定预编译好的动态库。
与BUILD_SHARED_LIBRARY和BUIDL_STATIC_LIBRARY不同的是，
LOCAL_SRC_FILES的值必须是一个单独的预编译动态库的路径(e.g. foo/libfoo.so)来代替一个源文件路径。
参考docs/PREBUILTS.html 你可以将预编译好的库集成到其它模块中。
PREBUILT_STATIC_LIBRARY
与PREBUILT_SHARED_LIBRARY一样，不同的是使用的预编译库是一个静态库。
请参考docs/PREBUILTS.html.
TARGET_ARCH
指定目标CPU的架构。这个值是 'arm' ,也就是基于ARM兼容的CPU，
,与CPU架构的修订无关。
TARGET_PLATFORM
当解析该Android.mk文件时用它来指定Andoid目标平台的名称。譬如，'android-3'与
Android 1.5系统镜像相对应。若要了解所有的平台名称及其相应的Android系统镜像，
请阅读docs/STABLE-APIS.TXT
TARGET_ARCH_ABI
当解析该Android.mk时，CPU+ABI的名称。目前支持两个值。
(注：ABI,Application Binary Interface，二进制应用程序接口）
armeabi For Armv5TE
armeabi-v7a
注意：到NDK 1.6_r1为止，仅简单的定义这个变量为'arm'。但为了更好地配合
Android平台的内部使用，该值已重定义。
关于ABI与相应的兼容问题更多详情，请阅读docs/CPU-ARCH-ABIS.TXT
未来的NDK版本将会引入其它的平台的ABI并会有不同的名称。注意，所有基于ARM的ABI会
使TARGET_ARCH定义为'arm',但可能拥有不同的TARGET_ARCH_ABI
TARGET_ABI
目标平台与abi的连接，它实际上被定义为 $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI)，
当你想在一个真实的装置上测试特定的目标系统镜像时，它就很有用了。
默认下，它的值为'android-3-armeabi'
(在Android NDK 1.6_r1及之前的版本，它的默认值为'android-3-arm'）
NDK提供的宏函数:
----------------------------
以下是一些GNU Make的宏‘函数’，必须通过这样的形式调用：'$(call <function>)'。
函数返回文本信息。
my-dir
返回最后 include 的make文件(.mk)的路径，也就是当前的Android.mk的目录。可用来
在Android.mk的开始处定义LOCAL_PATH的值：
LOCAL_PATH := $(call my-dir)
注意：由于NDK使用的是GNU Make的工作环境,my-dir函数实际返回的是最后include的make文件的路径，
不要在include其它文件之后 call my-dir。
举例：
LOCAL_PATH := $(call my-dir)
... 声明一个模块
include $(LOCAL_PATH)/foo/Android.mk
LOCAL_PATH := $(call my-dir)
... 声明一个模块
这里的问题是:在第二次调用 'my-dir' 宏函数时,因为之前执行了一次include make文件的操作,
已经将LOCAL_PATH的值定义为$PATH/foo而不是$PATH.
正确的做法是：将Android.mk中的 include mk文件的操作放到最后。如在：
LOCAL_PATH := $(call my-dir)
... 声明一个模块
LOCAL_PATH := $(call my-dir)
... declare another module
# extra includes at the end of the Android.mk
include $(LOCAL_PATH)/foo/Android.mk
如果不喜欢这么做的话，也可以将第一次call my-dir的返回值，存在一个变量里来使用:
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
返回‘my-dir’子目录下的所有Android.mk。比如，代码的结构如下：
sources/foo/Android.mk
sources/foo/lib1/Android.mk
sources/foo/lib2/Android.mk
如果sources/foo/Android.mk里有这样一行:
include $(call all-subdir-makefiles)
那么，它将会自动地include sources/foo/lib1/Android.mk和sources/foo/lib2/Android.mk
这个函数能将深层嵌套的代码文件夹提供给编译系统。注意，默认情况下，NDK仅在
source/*/Android.mk里寻找文件。
this-makefile
返回当前Makefile（注：指的应该是GNU Makefile)的路径（即，这个函数是在哪里调用的）
parent-makefile
返回当前make文件在列入树（inclusion tree)中的父makefile的路径。
即，包含当前makefile的那个makefile的路径。
grand-parent-makefile
猜猜看...（注：原文为Guess what...)
import-module
此函数可以根据模块名称找到并include Android.mk的另一个模块。
例如：
$(call import-module,<name>)
此函数将在你的 NDK_MODULE_PATH 环境变量中引用的目录列表中查找目标名称<name>的模块，
并自动为你 include 对应的Android.mk文件。
更多详情请阅读docs/IMPORT-MODULE.html.
模块描述相关的变量：
- - - - - - - - - -
接下来的变量是用来向编译系统描述你的组件的。你应该在'include $(CLEAR_VARS)'
和'include $(BUILD_XXXXX)'之间定义这些变量。正如在前面所说的，$(CLEAR_VARS)
是一个将会清除之前定义的所有变量的值，除非在对变量的描述时有显式的说明。
LOCAL_PATH
这个变量用来设置当前文件的路径。你必须在Android.mk的开始处定义它，比如：
LOCAL_PATH := $(call my-dir)
这个变量不会被$(CLEAR_VARS)消除，所以每个Android.mk仅需一个定义（以防你在
同一个文件里定义几个模块）。
LOCAL_MODULE
定义组件的名称。对于所有的组件名，它必须是唯一，且不能包含空格。
在include $(BUILD_XXX）之前你必须定义它。
这个组件名决定生成的文件名。比如，lib<foo>，即这个模块的名称
为<foo>。但是在你的NDK mk文件（不管是Android.mk还是Application.mk)中
你只能通过‘正常’的名称(如，<foo>)来引用其它的组件。
你可以复写这个LOCAL_MODULE_FILENAME这个变量的默认值（下一个讲）
LOCAL_MODULE_FILENAME
这是一个可选变量，你可以重新定义要生成文件的文件名。举例：
LOCAL_MODULE := foo-version-1
LOCAL_MODULE_FILENAME := libfoo (生成的文件名)
注意：不需要指定后缀和路径，编译系统会自动帮你处理。
LOCAL_SRC_FILES
用它来列出编译的模块所需的源文件。仅须列出传给编译器的文件，因为
编译系统会自动地计算源文件之间依赖关系。
注意，所有文件名都是相对于LOCAL_PATH的，你可以用到路径来表示（path component)
如：
LOCAL_SRC_FILES := foo.c \ (注：‘\’为连接符）
toto/bar.c
路径分隔符都要用Unix风格的做斜杠 /，‘\’无效。
LOCAL_CPP_EXTENSION
这是一个可选的变量，可用它来指明C++源文件的扩展名。默认情况下是'.cpp',
但你可以改变它。比如：
LOCAL_CPP_EXTENSION := .cxx
在NDK r7 版本，你可以列出多个后缀名，如下：
LOCAL_CPP_EXTENSION := .cpp .cxx .cc (不知道要不要用空格隔开 没做过实验)
LOCAL_CPP_FEATURES
这是一个可选变量,定义它可以表明你的代码所依赖的C++特性,如果你的代码依赖RTTI特性，则
LOCAL_CPP_FEATURES := rtti
表明你代码使用C++ 异常exceptions:
LOCAL_CPP_FEATURES := exceptions
或者可以一起声明：
LOCAL_CPP_FEATURES := rtti features这个变量的作用是在编译代码时使用正确的编译器标记，对于预编译的二进制包，也有助于声明其二进制所依赖的特性
以确保最后的链接环节正常工作。（推荐使用它来带他LOCAL_CPPFLAGS）
LOCAL_C_INCLUDES
一个相对于NDK*根*目录可选的路径名单，当编译所有的源文件（C,C++和汇编）时，
它将被添加进include搜索路径。例如：
LOCAL_C_INCLUDES := sources/foo
或者：
LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo
要放置在对应的 LOCAL_CFLAGS / LOACL_CPPFLAGS inclusion 标记之前
The LOCAL_C_INCLUDES path are also used automatically when
launching native debugging with ndk-gdb.
LOCAL_CFLAGS
一个可选的编译标记集，在编译C与C++源文件时，将解析它。
对指定额外的宏定义或编译选项很有用。
重要：不要试图改变你Android.mk里的optimization/debuggin level,通过
在你的Applicaction.mk里指定合适的信息，它将被自动处理，并使NDK编译
调试时生成有用的数据文件。
注意：在android-ndk-1.5_r1，相应的标记（flags)只适用于C源文件，对C++
源文件并不适用。为了适用于完整的Android编译系统的特性，已作了修
正。（现在，你可以使用LOCAL_CPPFLAGS为C++文件指定标记）
LOCAL_CPPFLAGS的别名。注意，不建议使用这个变量，因为在未来的NDK版本中，
它可能会废除。
LOCAL_CPPFLAGS
一个可选的编译标记集，*仅*在编译C++源文件时解析它。在编译器的命令行里它将在LOCAL_CFLAGS之后出现。
注意：在android-ndk-1.5_r1，相应的标记（flags)适用于C与C++源文件。
为了适用于完整的Android生成系统的特性，已作了修
正。（现在，你可以使用LOCAL_CFLAGS为C和C++源文件指定标记）
一份static libraries模块的名单（以BUILD_STATIC_LIBRARY的方式生成），它将被
连接到欲生成的模块上。这仅在生成shared library模块时有意义。（注：将指定
的一个或多个static library module转化为一个shared library module)
LOCAL_WHOLE_STATIC_LIBRARIES
是一个用于表示相应的库模块被用作为“整个档案”被链接到程序的变量。
See the GNU linker's documentation for the --whole-archive flag.当几个静态库之间有循环依赖关系的时候，使用这个变量是很有用的。注意，当编译一个动态库时，
使用此变量指定的静态库中的所有对象文件将被添加到最终的二进制文件中,但生成可执行程序时，这是不确定的。
一份该模块在运行期依赖于它的shared libraries *模块*。在连接时间(link time)里
以及为生成的文件嵌入相应的信息都要用到它。
LOCAL_LDLIBS
当额外的链接标志列表被用于编译你的模块时,通过用 '-l' 前缀的特定系统库传递名字是很有用的。比如，下面的语句会告诉连接器在加载时（load time)里生成连接到/system/lib/libz.so的模块。LOCAL_LDLIBS := -lz
若想知道在这个NDK版本可以连接哪些暴露的系统库（exposed system libraries)，
请参见docs/STABLE-APIS。
默认情况下，当尝试生成一个shared library遇到没有定义的引用时，会导致“undefined
symbol”error。这对在你的源代码里捕捉bugs有很大的帮助。
但是，因为一些原因你须要disable这个检查，可以将这个变量设置为'true’。注意，相应
的动态库可能在运行期间加载失败。
默认情况下，在"thumb"模式下ui生成ARM目标的二进制,这时每个指令都是16-bit宽的。
如果你想强迫模块的object文件以‘arm’（32位的指令）的模式生成，你可以将这个变量
定义为'arm'。即：
LOCAL_ARM_MODE := arm
注意，你也可以通过将‘.arm’后缀添加到源文件名字的后面指示编译系统将指定的
源文件以arm模式生成。例如：
LOCAL_SRC_FILES := foo.c bar.c.arm
告诉生成系统总是以arm模式编译‘bar.c’，但根据LOCAL_ARM_MODE的值生成foo.c
注意：在你的Application.mk里将APP_OPTIM设置为'debug',这也会强迫生成ARM二进制
代码。这是因为工具链的调试其中的bug不会处理thumb代码
LOCAL_ARM_NEON
定义这个变量为"true"会允许在你的C或C++源文件的GCC的内部函数中使用ARM高级SIMD（又名NEON），以及在聚合文件中的NEON指令。
当针对"armeabi-v7a"ABI对应的ARMv7指令集时你应该定义它。注意，并不是所有的ARMv7都是基于NEON指令集扩展的CPU，你应该执行运行时来检测在运行时中这段代码的安全。
另外，你也可以指定特定的源文件，比如用支持NEON".neon"后缀的源文件也可以被编译。
LOCAL_SRC_FILES :=foo.c.neon bar.c zoo.c.arm.neon
在这个例子中，"foo.c"将会被编译在thumb+neon模式中，"bar.c"以thumb模式编译，zoo.c以arm+neon模式编译。
注意，如果你使用两个的话，".neon"后缀必须出现在".arm"后缀之后。
（就是foo.c.arm.neon可以工作，但是foo.c.neon.arm不工作）
LOCAL_DISABLE_NO_EXECUTE
Android NDK r4开始添加了支持"NX位"安全功能特性。它是默认启用的，如果你需要的话，可以通过设置变量为“true”来禁用它。
注意：此功能不修改ABI，并且只在ARMv6及以上的CPU设备的内核上被启用。
更多信息，可以参见：
http://en.wikipedia.org/wiki/NX_bit
http://www.gentoo.org/proj/en/hardened/gnu-stack.xml
LOCAL_EXPORT_CFLAGS
定义这个变量用来记录C/C++编译器标志集合，并且会被添加到其他任何以LOCAL_STATIC_LIBRARIES和LOCAL_SHARED_LIBRARIES的模块的LOCAL_CFLAGS定义中。
例如：这样定义"foo"模块
include $(CLEAR_VARS)
LOCAL_MODULE :=foo
LOCAL_SRC_FILES :=foo/foo.c
LOCAL_EXPORT_CFLAGS :=-DFOO=1
include $(BUILD_STATIC_LIBRARY)
另一个模块，叫做"bar"，并且依赖于上面的模块
include $(CLEAR_VARS)
LOCAL_MODULE :=bar
LOCAL_SRC_FILES :=bar.c
LOCAL_CFLAGS:=-DBAR=2
LOCAL_STATIC_LIBRARIES:=foo
include $(BUILD_SHARED_LIBRARY)
然后，当编译bar.c的时候，标志"-DFOO=1 -DBAR=2"将被传递到编译器。
输出的标志被添加到模块的LOCAL_CFLAGS上，所以你可以很容易复写它们。它们也有传递性：如果"zoo"依赖"bar"，“bar”依赖"foo"，那么"zoo"也将继承"foo"输出的所有标志。
最后，当编译模块输出标志的时候，这些标志并不会被使用。在上面的例子中，当编译foo/foo.c时，
-DFOO=1将不会被传递给编译器。
LOCAL_EXPORT_CPPFLAGS
类似LOCAL_EXPORT_CFLAGS,但适用于C++标志。
LOCAL_EXPORT_C_INCLUDES
类似LOCAL_EXPORT_C_CFLAGS,但是只有C能包含路径，如果"bar.c"想包含一些由"foo"模块提供的头文件的时候这会很有用。
LOCAL_EXPORT_LDLIBS
类似于LOCAL_EXPORT_CFLAGS,但是只用于链接标志。注意，引入的链接标志将会被追加到模块的LOCAL_LDLIBS，这是因为UNIX连接器的工作方式。
当模块foo是一个静态库的时候并且代码依赖于系统库时会很有用的。LOCAL_EXPORT_LDLIBS可以用于输出依赖，例如：
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)
这里，在连接器命令最后，libbar.so将以-llog参数进行编译来表明它依赖于系统日志库，因为它依赖于foo。
LOCAL_FILTER_ASM
这个变量定义了一个shell命令，将用于过滤，从你的LOCAL_SRC_FILES中产生的或者聚合文件。
当它被定义了，将会出现如下的情况：
--任何C或C++源文件将会生成到一个临时的聚合的文件中（而不是被编译成目标文件）
--任何临时聚合文件，任何在LOCAL_SRC_FILES中列出的聚合文件将通过LOCAL_FILER_ASM命令生成另一个临时聚合文件
--这些过滤聚合文件被编译成目标文件。
换种说法，如果
LOCAL_SRC_FILES := foo.c bar.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
“1”对应的编译器，“2”的过滤器，和“3”的汇编。过滤器必须是一个独立的shell命令作为第一个参数输入文件的名称，和输出的名称第二，如文件为：
myasmfilter$ OBJS_DIR/ foo.S.original$ OBJS_DIR/ foo.S
myasmfilter bar.S$ OBJS_DIR/ bar.S
1506
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
