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