docs/APPLICATION-MK.html - platform/ndk - Git at Google

 <html><body><pre>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/&lt;myapp&gt;/Application.mk

 Where &lt;myapp&gt; 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/&lt;myapp&gt;/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 &lt;application&gt;
     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 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 docs/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 docs/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 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 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 docs/ANDROID-MK.html.

 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.


 A trivial Application.mk file would be:

 -------------- cut here -------------------------
 APP_PROJECT_PATH := &lt;path to project&gt;
 -------------- cut here -------------------------
 </pre></body></html>
	<html><body><pre>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 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 docs/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 docs/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 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 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 docs/ANDROID-MK.html.

	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.


	A trivial Application.mk file would be:

	-------------- cut here -------------------------
	APP_PROJECT_PATH := <path to project>
	-------------- cut here -------------------------
	</pre></body></html>