docs/ANDROID-MK.TXT - platform/ndk - Git at Google

 Android.mk file syntax specification

 Introduction:
 -------------

 This document describes the syntax of Android.mk build file
 written to describe your C and C++ source files to the Android
 NDK. To understand what follows, it is assumed that you have
 read the docs/OVERVIEW.TXT file that explains their role and
 usage.

 Overview:
 ---------

 An Android.mk file is written to describe your sources to the
 build system. More specifically:

 - The file is really a tiny GNU Makefile fragment that will be
   parsed one or more times by the build system. As such, you
   should try to minimize the variables you declare there and
   do not assume that anything is not defined during parsing.

 - The file syntax is designed to allow you to group your
   sources into 'modules'. A module is one of the following:

     - a static library
     - a shared library

   Only shared libraries will be installed/copied to your
   application package. Static libraries can be used to generate
   shared libraries though.

   You can define one or more modules in each Android.mk file,
   and you can use the same source file in several modules.

 - The build system handles many details for you. For example, you
   don't need to list header files or explicit dependencies between
   generated files in your Android.mk. The NDK build system will
   compute these automatically for you.

   This also means that, when updating to newer releases of the NDK,
   you should be able to benefit from new toolchain/platform support
   without having to touch your Android.mk files.

 Note that the syntax is *very* close to the one used in Android.mk files
 distributed with the full open-source Android platform sources. While
 the build system implementation that uses them is different, this is
 an intentional design decision made to allow reuse of 'external' libraries'
 source code easier for application developers.

 Simple example:
 ---------------

 Before describing the syntax in details, let's consider a simple
 "hello world" example, i.e. the following files:

     sources/helloworld/helloworld.c
     sources/helloworld/Android.mk

 Where 'helloworld.c' is the source of a simple JNI shared library
 that implements a native method that returns the "hello world"
 string.

 The corresponding Android.mk file will look like this:

    ---------- cut here ------------------
    LOCAL_PATH := $(call my-dir)

    include $(CLEAR_VARS)

    LOCAL_MODULE    := helloworld
    LOCAL_SRC_FILES := helloworld.c

    include $(BUILD_SHARED_LIBRARY)
    ---------- cut here ------------------

 Now, let's explain these lines:

   LOCAL_PATH := $(call my-dir)

 An Android.mk file must begin with the definition of the LOCAL_PATH variable.
 It is used to locate source files in the development tree. In this example,
 the macro function 'my-dir', provided by the build system, is used to return
 the path of the current directory (i.e. the directory containing the
 Android.mk file itself).

   include $(CLEAR_VARS)

 The CLEAR_VARS variable is provided by the build system and points to a
 special GNU Makefile that will clear many LOCAL_XXX variables for you
 (e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...),
 with the exception of LOCAL_PATH. This is needed because all build
 control files are parsed in a single GNU Make execution context where
 all variables are global.

   LOCAL_MODULE := helloworld

 The LOCAL_MODULE variable must be defined to identify each module you
 describe in your Android.mk. The name must be *unique* and not contain
 any spaces. Note that the build system will automatically add proper
 prefix and suffix to the corresponding generated file. In other words,
 a shared library module named 'foo' will generate 'libfoo.so'.

 IMPORTANT NOTE:
 If you name your module 'libfoo', the build system will not
 add another 'lib' prefix and will generate libfoo.so as well.
 This is to support Android.mk files that originate from the
 Android platform sources, would you need to use these.

   LOCAL_SRC_FILES := helloworld.c

 The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source
 files that will be built and assemble into a module. Note that you should
 not list header and included files here, because the build system will
 compute dependencies automatically for you; just list the source files
 that will be passed directly to a compiler, and you should be good.

 Note that the default extension for C++ source files is '.cpp'. It is
 however possible to specify a different one by defining the variable
 LOCAL_DEFAULT_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx'
 will work, but not 'cxx').

   include $(BUILD_SHARED_LIBRARY)

 The BUILD_SHARED_LIBRARY is a variable provided by the build system that
 points to a GNU Makefile script that is in charge of collecting all the
 information you defined in LOCAL_XXX variables since the latest
 'include $(CLEAR_VARS)' and determine what to build, and how to do it
 exactly. There is also BUILD_STATIC_LIBRARY to generate a static library.

 There are more complex examples under sources/samples, with commented
 Android.mk files that you can look at.

 Reference:
 ----------

 This is the list of variables you should either rely on or define in
 an Android.mk. You can define other variables for your own usage, but
 the NDK build system reserves the following variable names:

 - names that begin with LOCAL_  (e.g. LOCAL_MODULE)
 - names that begin with PRIVATE_, NDK_ or APP_  (used internally)
 - lower-case names (used internally, e.g. 'my-dir')

 If you need to define your own convenience variables in an Android.mk
 file, we recommend using the MY_ prefix, for a trivial example:

    ---------- cut here ------------------
     MY_SOURCES := foo.c
     ifneq ($(MY_CONFIG_BAR),)
       MY_SOURCES += bar.c
     endif

     LOCAL_SRC_FILES += $(MY_SOURCES)
    ---------- cut here ------------------

 So, here we go:


 NDK-provided variables:
 - - - - - - - - - - - -

 These GNU Make variables are defined by the build system before
 your Android.mk file is parsed. Note that under certain circumstances
 the NDK might parse your Android.mk several times, each with different
 definition for some of these variables.

 CLEAR_VARS
     Points to a build script that undefines nearly all LOCAL_XXX variables
     listed in the "Module-description" section below. You must include
     the script before starting a new module, e.g.:

       include $(CLEAR_VARS)

 BUILD_SHARED_LIBRARY
     Points to a build script that collects all the information about the
     module you provided in LOCAL_XXX variables and determines how to build
     a target shared library from the sources you listed. Note that you
     must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before
     including this file. Example usage:

       include $(BUILD_SHARED_LIBRARY)

     note that this will generate a file named lib$(LOCAL_MODULE).so

 BUILD_STATIC_LIBRARY
     A variant of BUILD_SHARED_LIBRARY that is used to build a target static
     library instead. Static libraries are not copied into your
     project/packages but can be used to build shared libraries (see
     LOCAL_STATIC_LIBRARIES and LOCAL_STATIC_WHOLE_LIBRARIES described below).
     Example usage:

       include $(BUILD_STATIC_LIBRARY)

     Note that this will generate a file named lib$(LOCAL_MODULE).a

 TARGET_ARCH
     Name of the target CPU architecture as it is specified by the
     full Android open-source build. This is 'arm' for any ARM-compatible
     build, independent of the CPU architecture revision.

 TARGET_PLATFORM
     Name of the target Android platform when this Android.mk is parsed.
     For now, only 'cupcake' is supported.

 TARGET_ARCH_ABI
     Name of the target CPU+ABI when this Android.mk is parsed.
     For now, only 'arm' is supported, which really means the following:

        ARMv5TE or higher CPU, with 'softfloat' floating point support

     Other target ABIs will be introduced in future releases of the NDK
     and will have a different name. Note that all ARM-based ABIs will
     have 'TARGET_ARCH' defined to 'arm', but may have different
     'TARGET_ARCH_ABI'

 TARGET_ABI
     The concatenation of target platform and abi, it really is defined
     as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want
     to test against a specific target system image for a real device.

     By default, this will be 'cupcake-arm'


 NDK-provided function macros:
 - - - - - - - - - - - - - - -

 The following are GNU Make 'function' macros, and must be evaluated
 by using '$(call <function>)'. They return textual information.

 my-dir
     Returns the path of the current Android.mk's directory, relative
     to the top of the NDK build system. This is useful to define
     LOCAL_PATH at the start of your Android.mk as with:

         LOCAL_PATH := $(call my-dir)

 all-subdir-makefiles
     Returns a list of Android.mk located in all sub-directories of
     the current 'my-dir' path. For example, consider the following
     hierarchy:

         sources/foo/Android.mk
         sources/foo/lib1/Android.mk
         sources/foo/lib2/Android.mk

     If sources/foo/Android.mk contains the single line:

         include $(call all-subdir-makefiles)

     Then it will include automatically sources/foo/lib1/Android.mk and
     sources/foo/lib2/Android.mk

     This function can be used to provide deep-nested source directory
     hierarchies to the build system. Note that by default, the NDK
     will only look for files in sources/*/Android.mk

 this-makefile
     Returns the path of the current Makefile (i.e. where the function
     is called).

 parent-makefile
     Returns the path of the parent Makefile in the inclusion tree,
     i.e. the path of the Makefile that included the current one.

 grand-parent-makefile
     Guess what...


 Module-description variables:
 - - - - - - - - - - - - - - -

 The following variables are used to describe your module to the build
 system. You should define some of them between an 'include $(CLEAR_VARS)'
 and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is
 a script that will undefine/clear all of these variables, unless explicitely
 noted in their description.

 LOCAL_PATH
     This variable is used to give the path of the current file.
     You MUST define it at the start of your Android.mk, which can
     be done with:

       LOCAL_PATH := $(call my-dir)

     This variable is *not* cleared by $(CLEAR_VARS) so only one
     definition per Android.mk is needed (in case you define several
     modules in a single file).

 LOCAL_MODULE
     This is the name of your module. It must be unique among all
     module names, and shall not contain any space. You MUST define
     it before including any $(BUILD_XXXX) script.

     The module name determines the name of generated files, e.g.
     lib<foo>.so for a shared library module named <foo>. However
     you should only refer to other modules with their 'normal'
     name (e.g. <foo>) in your NDK build files (either Android.mk
     or Application.mk)

 LOCAL_SRC_FILES
     This is a list of source files that will be built for your module.
     Only list the files that will be passed to a compiler, since the
     build system automatically computes dependencies for you.

     Note that source files names are all relative to LOCAL_PATH and
     you can use path components, e.g.:

       LOCAL_SRC_FILES := foo.c \
                          toto/bar.c

     NOTE: Always use Unix-style forward slashes (/) in build files.
           Windows-style back-slashes will not be handled properly.

 LOCAL_CPP_EXTENSION
     This is an optional variable that can be defined to indicate
     the file extension of C++ source files. The default is '.cpp'
     but you can change it. For example:

         LOCAL_CPP_EXTENSION := .cxx

 LOCAL_CFLAGS
     An optional set of compiler flags that will be passed when building
     C source files (*not* C++ sources).

     This can be useful to specify an additionnal include path
     (relative to the top of the NDK directory), macro definitions
     or compile options.

     IMPORTANT: Try not to change the optimization/debugging level in
                your Android.mk, this can be handled automatically for
                you by specifying the appropriate information in
                your Application.mk, and will let the NDK generate
                useful data files used during debugging.

 LOCAL_CXXFLAGS
     Same as LOCAL_CFLAGS for C++ source files

 LOCAL_CPPFLAGS
     Same as LOCAL_CFLAGS but used for both C and C++ source files

 LOCAL_STATIC_LIBRARIES
     The list of static libraries modules (built with BUILD_STATIC_LIBRARY)
     that should be linked to this module. This only makes sense in
     shared library modules.

 LOCAL_STATIC_WHOLE_LIBRARIES
     A variant of LOCAL_STATIC_LIBRARIES, but which contains a list of
     static libraries which will be linked into the target module
     with the --whole-archive GNU ld linker option. If you don't know
     what this means, you don't need this variable :-)

 LOCAL_SHARED_LIBRARIES
     The list of shared libraries *modules* this module depends on at runtime.
     This is necessary at link time and to embed the corresponding information
     in the generated file.

     Note that this does not append the listed modules to the build graph,
     i.e. you should still add them to your application's required modules
     in your Application.mk
	Android.mk file syntax specification

	Introduction:
	-------------

	This document describes the syntax of Android.mk build file
	written to describe your C and C++ source files to the Android
	NDK. To understand what follows, it is assumed that you have
	read the docs/OVERVIEW.TXT file that explains their role and
	usage.

	Overview:
	---------

	An Android.mk file is written to describe your sources to the
	build system. More specifically:

	- The file is really a tiny GNU Makefile fragment that will be
	parsed one or more times by the build system. As such, you
	should try to minimize the variables you declare there and
	do not assume that anything is not defined during parsing.

	- The file syntax is designed to allow you to group your
	sources into 'modules'. A module is one of the following:

	- a static library
	- a shared library

	Only shared libraries will be installed/copied to your
	application package. Static libraries can be used to generate
	shared libraries though.

	You can define one or more modules in each Android.mk file,
	and you can use the same source file in several modules.

	- The build system handles many details for you. For example, you
	don't need to list header files or explicit dependencies between
	generated files in your Android.mk. The NDK build system will
	compute these automatically for you.

	This also means that, when updating to newer releases of the NDK,
	you should be able to benefit from new toolchain/platform support
	without having to touch your Android.mk files.

	Note that the syntax is very close to the one used in Android.mk files
	distributed with the full open-source Android platform sources. While
	the build system implementation that uses them is different, this is
	an intentional design decision made to allow reuse of 'external' libraries'
	source code easier for application developers.

	Simple example:
	---------------

	Before describing the syntax in details, let's consider a simple
	"hello world" example, i.e. the following files:

	sources/helloworld/helloworld.c
	sources/helloworld/Android.mk

	Where 'helloworld.c' is the source of a simple JNI shared library
	that implements a native method that returns the "hello world"
	string.

	The corresponding Android.mk file will look like this:

	---------- cut here ------------------
	LOCAL_PATH := $(call my-dir)

	include $(CLEAR_VARS)

	LOCAL_MODULE := helloworld
	LOCAL_SRC_FILES := helloworld.c

	include $(BUILD_SHARED_LIBRARY)
	---------- cut here ------------------

	Now, let's explain these lines:

	LOCAL_PATH := $(call my-dir)

	An Android.mk file must begin with the definition of the LOCAL_PATH variable.
	It is used to locate source files in the development tree. In this example,
	the macro function 'my-dir', provided by the build system, is used to return
	the path of the current directory (i.e. the directory containing the
	Android.mk file itself).

	include $(CLEAR_VARS)

	The CLEAR_VARS variable is provided by the build system and points to a
	special GNU Makefile that will clear many LOCAL_XXX variables for you
	(e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...),
	with the exception of LOCAL_PATH. This is needed because all build
	control files are parsed in a single GNU Make execution context where
	all variables are global.

	LOCAL_MODULE := helloworld

	The LOCAL_MODULE variable must be defined to identify each module you
	describe in your Android.mk. The name must be unique and not contain
	any spaces. Note that the build system will automatically add proper
	prefix and suffix to the corresponding generated file. In other words,
	a shared library module named 'foo' will generate 'libfoo.so'.

	IMPORTANT NOTE:
	If you name your module 'libfoo', the build system will not
	add another 'lib' prefix and will generate libfoo.so as well.
	This is to support Android.mk files that originate from the
	Android platform sources, would you need to use these.

	LOCAL_SRC_FILES := helloworld.c

	The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source
	files that will be built and assemble into a module. Note that you should
	not list header and included files here, because the build system will
	compute dependencies automatically for you; just list the source files
	that will be passed directly to a compiler, and you should be good.

	Note that the default extension for C++ source files is '.cpp'. It is
	however possible to specify a different one by defining the variable
	LOCAL_DEFAULT_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx'
	will work, but not 'cxx').

	include $(BUILD_SHARED_LIBRARY)

	The BUILD_SHARED_LIBRARY is a variable provided by the build system that
	points to a GNU Makefile script that is in charge of collecting all the
	information you defined in LOCAL_XXX variables since the latest
	'include $(CLEAR_VARS)' and determine what to build, and how to do it
	exactly. There is also BUILD_STATIC_LIBRARY to generate a static library.

	There are more complex examples under sources/samples, with commented
	Android.mk files that you can look at.

	Reference:
	----------

	This is the list of variables you should either rely on or define in
	an Android.mk. You can define other variables for your own usage, but
	the NDK build system reserves the following variable names:

	- names that begin with LOCAL_ (e.g. LOCAL_MODULE)
	- names that begin with PRIVATE_, NDK_ or APP_ (used internally)
	- lower-case names (used internally, e.g. 'my-dir')

	If you need to define your own convenience variables in an Android.mk
	file, we recommend using the MY_ prefix, for a trivial example:

	---------- cut here ------------------
	MY_SOURCES := foo.c
	ifneq ($(MY_CONFIG_BAR),)
	MY_SOURCES += bar.c
	endif

	LOCAL_SRC_FILES += $(MY_SOURCES)
	---------- cut here ------------------

	So, here we go:


	NDK-provided variables:
	- - - - - - - - - - - -

	These GNU Make variables are defined by the build system before
	your Android.mk file is parsed. Note that under certain circumstances
	the NDK might parse your Android.mk several times, each with different
	definition for some of these variables.

	CLEAR_VARS
	Points to a build script that undefines nearly all LOCAL_XXX variables
	listed in the "Module-description" section below. You must include
	the script before starting a new module, e.g.:

	include $(CLEAR_VARS)

	BUILD_SHARED_LIBRARY
	Points to a build script that collects all the information about the
	module you provided in LOCAL_XXX variables and determines how to build
	a target shared library from the sources you listed. Note that you
	must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before
	including this file. Example usage:

	include $(BUILD_SHARED_LIBRARY)

	note that this will generate a file named lib$(LOCAL_MODULE).so

	BUILD_STATIC_LIBRARY
	A variant of BUILD_SHARED_LIBRARY that is used to build a target static
	library instead. Static libraries are not copied into your
	project/packages but can be used to build shared libraries (see
	LOCAL_STATIC_LIBRARIES and LOCAL_STATIC_WHOLE_LIBRARIES described below).
	Example usage:

	include $(BUILD_STATIC_LIBRARY)

	Note that this will generate a file named lib$(LOCAL_MODULE).a

	TARGET_ARCH
	Name of the target CPU architecture as it is specified by the
	full Android open-source build. This is 'arm' for any ARM-compatible
	build, independent of the CPU architecture revision.

	TARGET_PLATFORM
	Name of the target Android platform when this Android.mk is parsed.
	For now, only 'cupcake' is supported.

	TARGET_ARCH_ABI
	Name of the target CPU+ABI when this Android.mk is parsed.
	For now, only 'arm' is supported, which really means the following:

	ARMv5TE or higher CPU, with 'softfloat' floating point support

	Other target ABIs will be introduced in future releases of the NDK
	and will have a different name. Note that all ARM-based ABIs will
	have 'TARGET_ARCH' defined to 'arm', but may have different
	'TARGET_ARCH_ABI'

	TARGET_ABI
	The concatenation of target platform and abi, it really is defined
	as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want
	to test against a specific target system image for a real device.

	By default, this will be 'cupcake-arm'


	NDK-provided function macros:
	- - - - - - - - - - - - - - -

	The following are GNU Make 'function' macros, and must be evaluated
	by using '$(call <function>)'. They return textual information.

	my-dir
	Returns the path of the current Android.mk's directory, relative
	to the top of the NDK build system. This is useful to define
	LOCAL_PATH at the start of your Android.mk as with:

	LOCAL_PATH := $(call my-dir)

	all-subdir-makefiles
	Returns a list of Android.mk located in all sub-directories of
	the current 'my-dir' path. For example, consider the following
	hierarchy:

	sources/foo/Android.mk
	sources/foo/lib1/Android.mk
	sources/foo/lib2/Android.mk

	If sources/foo/Android.mk contains the single line:

	include $(call all-subdir-makefiles)

	Then it will include automatically sources/foo/lib1/Android.mk and
	sources/foo/lib2/Android.mk

	This function can be used to provide deep-nested source directory
	hierarchies to the build system. Note that by default, the NDK
	will only look for files in sources/*/Android.mk

	this-makefile
	Returns the path of the current Makefile (i.e. where the function
	is called).

	parent-makefile
	Returns the path of the parent Makefile in the inclusion tree,
	i.e. the path of the Makefile that included the current one.

	grand-parent-makefile
	Guess what...


	Module-description variables:
	- - - - - - - - - - - - - - -

	The following variables are used to describe your module to the build
	system. You should define some of them between an 'include $(CLEAR_VARS)'
	and an 'include $(BUILD_XXXXX)'. As written previously, $(CLEAR_VARS) is
	a script that will undefine/clear all of these variables, unless explicitely
	noted in their description.

	LOCAL_PATH
	This variable is used to give the path of the current file.
	You MUST define it at the start of your Android.mk, which can
	be done with:

	LOCAL_PATH := $(call my-dir)

	This variable is not cleared by $(CLEAR_VARS) so only one
	definition per Android.mk is needed (in case you define several
	modules in a single file).

	LOCAL_MODULE
	This is the name of your module. It must be unique among all
	module names, and shall not contain any space. You MUST define
	it before including any $(BUILD_XXXX) script.

	The module name determines the name of generated files, e.g.
	lib<foo>.so for a shared library module named <foo>. However
	you should only refer to other modules with their 'normal'
	name (e.g. <foo>) in your NDK build files (either Android.mk
	or Application.mk)

	LOCAL_SRC_FILES
	This is a list of source files that will be built for your module.
	Only list the files that will be passed to a compiler, since the
	build system automatically computes dependencies for you.

	Note that source files names are all relative to LOCAL_PATH and
	you can use path components, e.g.:

	LOCAL_SRC_FILES := foo.c \
	toto/bar.c

	NOTE: Always use Unix-style forward slashes (/) in build files.
	Windows-style back-slashes will not be handled properly.

	LOCAL_CPP_EXTENSION
	This is an optional variable that can be defined to indicate
	the file extension of C++ source files. The default is '.cpp'
	but you can change it. For example:

	LOCAL_CPP_EXTENSION := .cxx

	LOCAL_CFLAGS
	An optional set of compiler flags that will be passed when building
	C source files (not C++ sources).

	This can be useful to specify an additionnal include path
	(relative to the top of the NDK directory), macro definitions
	or compile options.

	IMPORTANT: Try not to change the optimization/debugging level in
	your Android.mk, this can be handled automatically for
	you by specifying the appropriate information in
	your Application.mk, and will let the NDK generate
	useful data files used during debugging.

	LOCAL_CXXFLAGS
	Same as LOCAL_CFLAGS for C++ source files

	LOCAL_CPPFLAGS
	Same as LOCAL_CFLAGS but used for both C and C++ source files

	LOCAL_STATIC_LIBRARIES
	The list of static libraries modules (built with BUILD_STATIC_LIBRARY)
	that should be linked to this module. This only makes sense in
	shared library modules.

	LOCAL_STATIC_WHOLE_LIBRARIES
	A variant of LOCAL_STATIC_LIBRARIES, but which contains a list of
	static libraries which will be linked into the target module
	with the --whole-archive GNU ld linker option. If you don't know
	what this means, you don't need this variable :-)

	LOCAL_SHARED_LIBRARIES
	The list of shared libraries modules this module depends on at runtime.
	This is necessary at link time and to embed the corresponding information
	in the generated file.

	Note that this does not append the listed modules to the build graph,
	i.e. you should still add them to your application's required modules
	in your Application.mk