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.TXT 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_STATIC_WHOLE_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.TXT for more
    information).

PREBUILT_STATIC_LIBRARY
    This is the same than PREBUILT_SHARED_LIBRARY, but for a static library
    file instead. See docs/PREBUILTS.TXT 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.TXT.

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.TXT

    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 additionnal 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.TXT 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 explicitely
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

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 additionnal 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_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.TXT 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 targetting 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 lean more about this, please read the documentation at
    docs/CPU-ARM-NEON.TXT and docs/CPU-FEATURES.TXT.

    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 targetting 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