    Application.mk file syntax specification

    Introduction:
    -------------

    This document describes the syntax of Application.mk build files
    written to describe the native modules required by your Android
    application. To understand what follows, it is assumed that you have
    read the docs/OVERVIEW.html file that explains their role and
    usage.

    Readers of this document should have read docs/OVERVIEW.html and
    docs/ANDROID-MK.html

    Overview:
    ---------

    The purpose of Application.mk is to describe which native
    'modules' (i.e. static/shared libraries) are needed by your
    application.

    An Application.mk file is usually placed under $PROJECT/jni/Application.mk,
    where $PROJECT points to your application's project directory.

    Another alternative is to place it under a sub-directory of the top-level
    $NDK/apps directory, e.g.:

       $NDK/apps/<myapp>/Application.mk

    Where <myapp> is a short name used to describe your 'application'
    to the NDK build system (this name doesn't go into your generated
    shared libraries or your final packages).

    The Application.mk is really a tiny GNU Makefile fragment that must
    define a few variables:

    APP_PROJECT_PATH
        This variable should give the *absolute* path to your
        Application's project root directory. This is used to copy/install
        stripped versions of the generated JNI shared libraries to a
        specific location known to the APK-generating tools.

        Note that it is optional for $PROJECT/jni/Application.mk, but
        *mandatory* for $NDK/apps/<myapp>/Application.mk

    APP_MODULES
        This variable is optional. If not defined, the NDK will build by
        default _all_ the modules declared by your Android.mk, and any
        sub-makefile it may include.

        If APP_MODULES is defined, it must be a space-separated list of module
        names as they appear in the LOCAL_MODULE definitions of Android.mk
        files. Note that the NDK will compute module dependencies automatically.

        NOTE: This variable's behaviour changed in NDK r4. Before that:

          - the variable was mandatory in your Application.mk
          - all required modules had to be listed explicitly.

    APP_OPTIM
        This optional variable can be defined to either 'release' or
        'debug'. This is used to alter the optimization level when
        building your application's modules.

        A 'release' mode is the default, and will generate highly
        optimized binaries. The 'debug' mode will generate un-optimized
        binaries which are much easier to debug.

        Note that if your application is debuggable (i.e. if your manifest
        sets the android:debuggable attribute to "true" in its <application>
        tag), the default will be 'debug' instead of 'release'. This can
        be overridden by setting APP_OPTIM to 'release'.

        Note that it is possible to debug both 'release' and 'debug'
        binaries, but the 'release' builds tend to provide less information
        during debugging sessions: some variables are optimized out and
        can't be inspected, code re-ordering can make stepping through
        the code difficult, stack traces may not be reliable, etc...

    APP_CFLAGS
        A set of C compiler flags passed when compiling any C or C++ source code
        of any of the modules. This can be used to change the build of a given
        module depending on the application that needs it, instead of modifying
        the Android.mk file itself.

        IMPORTANT WARNING: +++++++++++++++++++++++++++++++++++++++++++++++++++
        +
        + All paths in these flags should be relative to the top-level NDK
        + directory. For example, if you have the following setup:
        +
        +    sources/foo/Android.mk
        +    sources/bar/Android.mk
        +
        +  To specify in foo/Android.mk that you want to add the path to the
        + 'bar' sources during compilation, you should use:
        +
        +   APP_CFLAGS += -Isources/bar
        +
        + Or alternatively:
        +
        +   APP_CFLAGS += -I$(LOCAL_PATH)/../bar
        +
        + Using '-I../bar' will *NOT* work since it will be equivalent to
        + '-I$NDK_ROOT/../bar' instead.
        +
        +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

        NOTE: In android-ndk-1.5_r1, this only applied to C sources, not C++ ones.
              This has been corrected to match the full Android build system.

    APP_CXXFLAGS
        An alias for APP_CPPFLAGS, to be considered obsolete as it may disappear
        in a future release of the NDK.

    APP_CPPFLAGS
        A set of C++ compiler flags passed when building C++ sources *only*.

        NOTE: In android-ndk-1.5_r1, this applied to both C and C++ sources.
              This has been corrected to match the full Android build system.
              You can now use APP_CFLAGS for flags that shall apply to C and
              C++ sources.

    APP_BUILD_SCRIPT
        By default, the NDK build system will look for a file named Android.mk
        under $(APP_PROJECT_PATH)/jni, i.e. for the file:

           $(APP_PROJECT_PATH)/jni/Android.mk

        If you want to override this behaviour, you can define APP_BUILD_SCRIPT
        to point to an alternate build script. A non-absolute path will always
        be interpreted as relative to the NDK's top-level directory.

    APP_ABI
        By default, the NDK build system will generate machine code for the
        'armeabi' ABI. This corresponds to an ARMv5TE based CPU with software
        floating point operations. You can use APP_ABI to select a different
        ABI.

        For example, to support hardware FPU instructions on ARMv7 based devices,
        use:

            APP_ABI := armeabi-v7a

        Or to support the IA-32 instruction set, use:

            APP_ABI := x86

        Or to support all three at the same time, use:

            APP_ABI := armeabi armeabi-v7a x86

        Or even better, since NDK r7, you can also use the special value
        'all' which means "all ABIs supported by this NDK release":

            APP_ABI := all

        For the list of all supported ABIs and details about their usage and
        limitations, please read docs/CPU-ARCH-ABIS.html

    APP_STL
        By default, the NDK build system provides C++ headers for the minimal
        C++ runtime library (/system/lib/libstdc++.so) provided by the Android
        system.

        However, the NDK comes with alternative C++ implementations that you can
        use or link to in your own applications. Define APP_STL to select one of
        them. Examples are:

           APP_STL := stlport_static    --> static STLport library
           APP_STL := stlport_shared    --> shared STLport library
           APP_STL := system            --> default C++ runtime library

        For more information on the subject, please read docs/CPLUSPLUS-SUPPORT.html

    APP_GNUSTL_FORCE_CPP_FEATURES
        In prior NDK versions, the simple fact of using the GNU libstdc++
        runtime (i.e. by setting APP_STL to either 'gnustl_static' or
        'gnustl_shared') enforced the support for exceptions and RTTI in all
        generated machine code. This could be problematic in specific, but rare,
        cases, and also generated un-necessarily bigger code for projects that
        don't require these features.

        This bug was fixed in NDK r7b, but this means that if your code requires
        exceptions or RTTI, it should now explicitely say so, either in your
        APP_CPPFLAGS, or your LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES definitions.

        To make it easier to port projects to NDK r7b and later, one can
        optionally defined APP_GNUSTL_CPP_FEATURES to contain one or more of the
        following values:

           exceptions    -> to enforce exceptions support for all modules.
           rtti          -> to enforce rtti support for all modules.

        For example, to get the exact same behaviour than NDK r7:

           APP_GNUSTL_FORCE_CPP_FEATURES := exceptions rtti

        IMPORTANT: This variable is provided here as a convenience to make it
                   easier to transition to a newer version of the NDK. It will
                   be removed in a future revision. We thus encourage all
                   developers to modify the module definitions properly instead
                   of relying on it here.

    A trivial Application.mk file would be:

    -------------- cut here -------------------------
    APP_PROJECT_PATH := <path to project>
    -------------- cut here -------------------------