Android NDK 学习之Application.mk

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 OVERVIEW file that explains their role and usage.

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

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

If this variable is defined, it tells ndk-build to only list the corresponding modules and those that they depend on. It must be a space-separated list of module names as they appear in theLOCAL_MODULE definition of Android.mk files.

It the variable is undefined, ndk-build looks for the list of all installable top-level modules, i.e. those listed by your Android.mk and any file it includes directly. Imported modules are not top-level though.

An installable module is either a shared library or executable, which will generate a file in libs/$ABI/.

If the variable is undefined, and there are no installable top-level modules in your project, then ndk-build will build all top-level static libraries and their dependencies instead. However, these libraries will be placed at the usual location under obj/ or obj-debug/.

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_LDFLAGS

A set of linker flags passed when linking application. This only applies when building shared libraries and executables, these flags are ignored when building static libraries.

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_ABIto 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 the MIPS instruction set, use:

          APP_ABI := mips

Or to support all at the same time, use:

          APP_ABI := armeabi armeabi-v7a x86 mips

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 CPU-ARCH-ABIS.

APP_PLATFORM

Name the target Android platform. For example, ‘android-3‘ correspond to Android 1.5 system images. For a complete list of platform names and corresponding Android system images, readSTABLE-APIS.

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 CPLUSPLUS-SUPPORT.

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

APP_SHORT_COMMANDS

The equivalent of LOCAL_SHORT_COMMANDS for your whole project. See the documentation for this variable in ANDROID-MK.

NDK_TOOLCHAIN_VERSION

Define this variable to either 4.4.3 or 4.6 to select version of GCC compiler. 4.6 is the default

APP_PIE

Starting from Jelly Bean (4.1), Android’s dynamic linker supports position-independent executables (PIE), which are built with -fPIE. This flag makes it harder to exploit memory corruption bugs by randomization the location of the code. By default, ndk-build will automatically set this value to ‘true‘ if your project targets android-16 or higher. You may set it manually to either ‘true‘ or ‘false‘.

IMPORTANT: PIE executables cannot run on Android releases prior to 4.1.

Note that this only applies to executables. It has no effect when building shared or static libraries.

APP_THIN_ARCHIVE

Sets the default value of LOCAL_THIN_ARCHIVE for all static library modules in this project. For more information, see the documentation for LOCAL_THIN_ARCHIVE in ANDROID-MK.

A trivial Application.mk file would be:

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