This document explains the Application.mk
build file used by ndk-build
.
We recommend that you read the Concepts and Android.mk pages before this one. Doing so will help maximize your understanding of the material on this page.
Overview
The Application.mk
file is really a tiny GNU Makefile fragment that defines
several variables for compilation. It usually resides under $PROJECT/jni/
,
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. For example:
$NDK/apps/<myapp>/Application.mk
Here, <myapp>
is a short name used to describe your app to the NDK build
system. It doesn't actually go into your generated shared libraries or your
final packages.
Variables
APP_PROJECT_PATH
This variable stores the absolute path to your app's project-root directory. The build system uses this information to place stripped-down versions of the generated JNI shared libraries into a specific location known to the APK-generating tools.
If you place your Application.mk
file under $NDK/apps/<myapp>/
, you must
define this variable. If you place it under $PROJECT/jni/
, it is optional.
APP_MODULES
If this variable is defined, it tells ndk-build
to build only 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.
If the variable is undefined, ndk-build
looks for the list of all installable
top-level modules, i.e. those listed by your Android.mk
file 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
builds all top-level static libraries and their
dependencies instead. These libraries are placed at the usual location under
obj/
or obj-debug/
.
APP_OPTIM
Define this optional variable as either release
or debug
. You use it to
alter the optimization level when building your application's modules.
Release mode is the default, and generates highly optimized binaries. Debug mode generates unoptimized binaries that are much easier to debug.
Note that you can debug either release or debug binaries. Release binaries, however, provide less information during debugging. For example, the build system optimizes out some variables, preventing you from inspecting them. Also, code re-ordering can make it more difficult to step through the code; stack traces may not be reliable.
Declaring android:debuggable
in your application manifest's <application>
tag will cause this variable to default to debug
instead of release
.
Override this default value by setting APP_OPTIM
to release
.
APP_CFLAGS
This variable stores a set of C compiler flags that the build system passes to
the compiler when compiling any C or C++ source code for any of the modules. You
can use this variable to change the build of a given module according to the
application that needs it, instead of having to modify the Android.mk
file
itself. Use APP_CPPFLAGS
to specify flags for C++ only.
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
-I../bar
will not work since it is equivalent to -I$NDK_ROOT/../bar
.
APP_CPPFLAGS
This variable contains a set of C++ compiler flags that the build system passes
to the compiler when building only C++ sources. Use APP_CFLAGS
to specify
flags for C and C++.
APP_LDFLAGS
A set of linker flags that the build system passes when linking the application. This variable is only relevant when the build system is building shared libraries and executables. When the build system builds static libraries, it ignores these flags.
APP_BUILD_SCRIPT
By default, the NDK build system looks under jni/
for a file named
Android.mk.
If you want to override this behavior, you can define APP_BUILD_SCRIPT
to
point to an alternate build script. The build system always interprets a
non-absolute path as relative to the NDK's top-level directory.
APP_ABI
By default, the NDK build system generates machine code for all non-deprecated
ABIs. You can use the APP_ABI
setting to generate machine code for specific
ABIs. Table 1 shows the APP_ABI
settings for different instruction sets.
Table 1. APP_ABI
settings for different instruction sets.
Instruction set | Value |
---|---|
Hardware FPU instructions on ARMv7 based devices | APP_ABI := armeabi-v7a |
ARMv8 AArch64 | APP_ABI := arm64-v8a |
IA-32 | APP_ABI := x86 |
Intel64 | APP_ABI := x86_64 |
All supported instruction sets | APP_ABI := all |
You can also specify multiple values by placing them on the same line, delimited by spaces. For example:
APP_ABI := armeabi-v7a arm64-v8a x86
For the list of all supported ABIs and details about their usage and limitations, refer to ABI Management.
APP_PLATFORM
This variable contains the minimum Android platform version you want to support.
For example, a value of android-15
specifies that your library uses APIs that
are not available below Android 4.0.3 (API level 15) and can't be used on
devices running a lower platform version. For a complete list of platform names
and corresponding Android system images, see Android NDK Native
APIs.
Instead of changing this flag directly, you should set the minSdkVersion
property in the defaultConfig
or productFlavors
blocks of your
module-level build.gradle
file. This
makes sure your library is used only by apps installed on devices running an
adequate version of Android. The ndk-build toolchain uses the following logic to
choose the minimum platform version for your library based the ABI you're
building and the minSdkVersion
you specify:
- If there exists a platform version for the ABI equal to
minSdkVersion
, ndk-build uses that version. - Otherwise, if there exists platform versions lower than
minSdkVersion
for the ABI, ndk-build uses the highest of those platform versions. This is a reasonable choice because a missing platform version typically means that there were no changes to the native platform APIs since the previous available version. - Otherwise, ndk-build uses the next available platform version higher than
minSdkVersion
.
APP_STL
The NDK build system defaults to STL system
. Other choices are c++_shared
,
c++_static
, and none
. See NDK Runtimes and
Features.
APP_SHORT_COMMANDS
The equivalent of LOCAL_SHORT_COMMANDS
in Application.mk
for your whole
project. For more information, see the documentation for this variable on
Android.mk.
APP_THIN_ARCHIVE
Sets the default value of LOCAL_THIN_ARCHIVE
in the Android.mk
file for all
static library modules in this project. For more information, see the
documentation for LOCAL_THIN_ARCHIVE
on Android.mk.