`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](OVERVIEW.html) file that explains their role and
usage.
Readers of this document should have read [OVERVIEW](OVERVIEW.html) and
[ANDROID-MK](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
> 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 the
> LOCAL_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_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 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](CPU-ARCH-ABIS.html).
- - - -
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, read [STABLE-APIS](STABLE-APIS.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 [CPLUSPLUS-SUPPORT](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 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](ANDROID-MK.html).
- - - -
NDK_TOOLCHAIN_VERSION
> Define this variable to either 4.6, 4.7 or 4.8 to select version of
> the 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](ANDROID-MK.html).
- - - -
A trivial `Application.mk` file would be:
-------------- cut here -------------------------
APP_PROJECT_PATH := <path to project>
-------------- cut here -------------------------