1 Preface
This document describes the syntax structure of the compiled file android.mk for programs written in C and C + + when compiling with the Android NDK. For the sake of understanding the following, assume that you have read the previous overview section to understand their role and usage.
2 Overview
Android.mk is used to describe how the source files are compiled. More specifically:-ANDROID.MK is actually a lightweight makefile that will be parsed one or more times by the compiled system. Therefore, you should declare as few variables as possible, and do not assume that nothing is defined in the parsing process. -ANDROID.MK is used to allow you to organize your source files in a ' modeles '. A modele is one of the following two forms:
-A static library
-A shared library dynamic libraries
Only dynamic libraries are installed or copied into your application package, but static libraries can be used to generate dynamic libraries. You can define one or more modeles in each android.mk, or you can use the same source files in multiple modeles.
-the compilation system handles a lot of details for you. For example, you do not need to list the files in the android.mk, nor do you need to display the dependencies between the listed files. The NDK compilation system will automatically calculate these things for you. This also means that when you upgrade to the new NDK version, you can get support for new cross tools and platforms without needing to modify your android.mk files.
Simple example:
Before introducing the syntax details, let's take a look at the simple example of "Hello JNI", which looks like this:
Apps/hello-jni/project
Here we can see:
-The ' src ' directory contains all Java source files for Android engineering.
-The ' JNI ' directory contains local source files. For example, ' jni/hello-jni.c '. This source file implements a simple dynamic library, and this dynamic library implements a native method that returns a string to the VM application.
-The ' jni/android.mk ' file describes the dynamic library of the NDK compilation system. Including:
----------------------Split Line----------------------------------
Local_path: =$ (call My-dir)
include$ (Clear_vars)
Local_module: = Hello-jni
Local_src_files: = Hello-jni.c
include$ (Build_shared_library)
----------------------Split Line----------------------------------
Now, let's explain:
Local_path: = $ (Callmy-dir)
The Android.mk file must first define the Local_path variable, which is used to locate the source file in the development tree. In this example, the system-supplied macro ' My-dir ' is compiled to return the current directory (that is, the directory contains the android.mk file itself).
include$ (Clear_vars)
The Clear_vars variable is provided by the compilation system, which points to a special GNU Makefile, which will clear a lot of variables for you local_xxx such as Local_module,local_src_fiels, Local_, Makefile Static_libaries, etc.), except of course local_path. This is necessary because all the compilation control files are parsed in a single GNU make executable context, and all variables in this context are global.
Local_module: = Hello-jni
The Local_module variable is used to uniquely label each module in the Android.mk file. The name must be unique and cannot contain any whitespace characters. The compilation system automatically adds prefixes and suffixes based on the generated files. In other words, a dynamic library module called ' foo ' generates ' libfoo.so '.
Important NOTES:
If your module is named ' Libfoo ', the build system will not add the ' lib ' prefix, and the libfoo.so will be generated as well. (Note: In order to develop a unified habit, the individual recommends not to add Lib prefix yourself)
Local_src_files: = Hello-jni.c
The local_src_files variable must contain a list of C and C + + source files, which are compiled and assembled into a module. Note that you do not have to list header files and include files, because the compilation system will automatically calculate the dependencies between them; you only need to list the source files, which will be passed directly to the compiler.
Note that the default C + + source file extension is '. cpp ' and of course you can specify a different extension by defining the variable local_cpp_extension, but remember not to forget the previous point (that is, '. Cxx ' can work, but ' cxx ' does not).
Include $ (build_shared_library)
Build_shared_library is a variable provided by the compilation system that points to a GNU makefile script that collects all the information defined in the LOCAL_XXX variable from the most recent ' include $ (clear_vars) '. Also decide what to compile and how to compile it. Obviously, build_static_library is used to generate static libraries.
There are many more complex examples in the Samples directory, which are commented on in the Android.mk file and can be viewed on your own.
Reference:
------------
There is a sequence of variables in android.mk, you either depend on it or define it. You can define other variables according to your own usage, but the NDK compilation system retains the following variable names:
-Name starting with Local_ (e.g., local_module)
-Names starting with Private_, Ndk_, app_ (internal use)
-Lowercase names (internal use, such as ' My-dir ')
If you need to define your own variables in android.mk, it is recommended to use My_ as a prefix, a simple example:
----------------------Split Line----------------------------------
My_sources: =FOO.C
Ifneq ($ (my_config_bar),)
My_sources + = Bar.c
endif
Local_src_files + = $ (my_sources)
----------------------Split Line----------------------------------
The NDK provides variables:
----------------------
These GNU make variables are defined by the compilation system before the Android.mk file is parsed. Note In some specific environments, the NDK may parse the android.mk file multiple times and may use different definitions for each of the following variables:
Clear_vars
Point to a compilation script that clears all the local_xxx variables listed under the "Module-descrption" section. Before you start declaring a new module, you must include this script, such as:
Include $ (clear_vars)
Build_shared_library
Point to a compilation script that collects all the information about the LOCAL_XXX variable you provide in the module and determines how the target dynamic library is compiled from the source files you list. Note that you must define Local_module and local_src_files at least before you include this file. Such as:
include$ (Build_shared_library)
Remember, this generates a lib$ (local_module). so file
Build_static_library
Build_static_library is used to compile target static libraries. A static library is not copied to your project or application package, but it can be used to compile dynamic libraries (see Local_static_libraries and Local_whole_static_libraries below).
Examples of Use:
Include $ (build_static_library)
Note that this generates a lib$ (local_module). a file.
Prebuilt_shared_library
Point to a compilation script that specifies a precompiled dynamic library. Unlike Build_shared_library and Build_static_library,local_src_files, the value must be a path to a compiled dynamic library (such as foo/libfoo.so) instead of a source file.
You can use the Local_prebuilts variable to refer to a compiled library in another module (see Related content in Prebuilts).
Prebuilt_static_library
This is the same as prebuilt_shared_library, it just represents a static library. Also see the relevant content in Prebuilts.
Target_arch
It is the name of the target CPU architecture specified by the entire Android open source compilation. This value is ' arm ', which is compatible with any arm compilation and is independent of the revision of the CPU architecture.
Target_platform
The name of the Android target platform when the Android.mk file is parsed. For example, ' android-3 ' corresponds to Android1.5 system image. If you want to know the platform name and complete information about the Android system image, please see Stable-apis.
Target_arch_abi
The name of the target Cpu+abi when the Android.mk file is parsed. Currently supports two values:
Armabi
For ARMv5TE
armabi-v7a
Note: To upgrade to Android NDK1.6_R1, this variable is defined only by ' arm '. However, this value has now been redefined to better match the internal use of Android.
To learn more about the ABI architecture and related compatibility issues, please read the Cpu-arch-abis related section.
In future versions of the NDK release, Abis of other targets may be introduced and may have different names. Note that all arm-based abis will define ' target_arch ' as ' arm ', but there may be different ' target_arch_abi '.
Target_abi
The Association of the target platform and the ABI is actually defined as $ (target_platform)-$ (Target_arch_abi). This is very useful when you want to test a specified target system image for a real device.
By default, it has a value of ' Android-3-armeabi '.
(Update to Android NDK 1.6_r1, default value ' Android-3-arm ')
The NDK provides macros:
----------------------
The following is the ' function ' macro for GNU make, called by ' $ (call <function>) '. They return text information:
My-dir
Returns the most recent path containing the makefile file, usually the directory where the current android.mk is located. It is very useful to define local_path at the beginning of android.mk:
Local_path: = $ (call My-dir)
Important: Because of how GNU make works, it actually returns the last path containing the makefile file during the parsing of the compilation script. Do not call My-dir after you include another file.
For example, consider the following example:
Local_path: = $ (call My-dir)
... Declaring a module
include$ (Local_path)/foo/android.mk
Local_path: = $ (Callmy-dir)
... declaring another module
In the second call to My-dir, because the $ (Local_path)/FOO/ANDROID.MK is included in front of it, Local_path is defined as $path/foo, not $path.
Because of this, it is better to include other files at the end of the ANDROID.MK, for example:
Local_path: = $ (call My-dir)
... declare one module
Local_path: = $ (call My-dir)
... declare another module
# Extra includes at the end of the ANDROID.MK
Include $ (local_path)/foo/android.mk
If this is inconvenient, save the value of the first call to My-dir in a variable. Such as:
My_local_path: = $ (call My-dir)
Local_path: = $ (My_local_path)
... declare one module
Include $ (local_path)/foo/android.mk
Local_path: = $ (My_local_path)
... declare another module
All-subdir-makefiles
Returns a list of the current ' My-dir ' directories and all android.mk file locations in all subdirectories. 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 this line:
Include $ (call All-subdir-makefiles)
Then it will automatically contain sources/foo/lib1/android.mk and sources/foo/lib2/android.mk.
This function is mainly used to provide a deeper source code directory structure for the compilation system. Note By default, the NDK only looks for files in sources/*/android.mk.
This-makefiles
Returns the path where the current makefile is located (that is, where the function was called).
Parent-makefile
Returns the path to the parentmakefile in the directory tree structure. The path to the makefile file that is contained by the current makefile.
Grand-parent-makefile
You guess... (Khan ... ）
Import-module
Allows you to find and include the Android.mk file in another module by name. A typical example is:
$ (call Import-module, <name>)
It finds all mudule marked as <name> in the list of directories referenced by the NDK_MODULE_PATH environment variable, and automatically contains the Android.mk file for you.
Read about Import-module for more details.
Module-description variables:
----------------------------------
The following variables are used to describe the module in the compilation system. You must define some variables between ' include $ (clear_vars) ' and ' include $ ' (build_xxxxx). According to the preceding description, $ (clear_vars) clears all definitions of these variables unless indicated in their descriptions.
Local_path
This variable represents the path of the current file. You must define at the beginning of the ANDROID.MK:
Local_path: = $ (call My-dir)
This variable is not cleared by $ (clear_vars), so each android.mk needs to be defined only once (even if many modules are defined in a file).
Local_module
This is the name of the module. In all modules, it must be unique and cannot contain whitespace characters. You must define it before containing the $ (build_xxxx) script.
By default, module name determines the name of the generated file, such as the name of the module, <foo>, and the name of the shared library is lib<foo>.so. However, in the NDK compilation script (Android.mk or application.mk), you refer to the other module, just by referring to the generic name (such as <foo>).
You can override this default value (see below) by Local_module_filename.
Local_module_filename
This variable is optional and allows you to redefine the name of the generated file. By default, module <foo> always generates LIB<FOO>.A static libraries or lib<foo>.so dynamic libraries, all of which are UNIX conventions.
You can overwrite this default value with Local_module_filename, for example:
Local_module: = foo-version-1
Local_module_filename: = Libfoo
Note: In your local_module_filename you do not need to add a path or file suffix, these compilation systems will automatically help you handle it.
Local_src_files
This is the list of source files for compiling the module. Only the source files in these lists can be passed to the compiler, and the compilation system automatically calculates the dependencies for you.
Note that these source files are relative to Local_path, and you can use PATH components such as:
Local_src_files: = foo.c \
Toto/bar.c
Note: In the compilation file, always use the Unix-style forward slash (/) instead of the Windows-style backslash.
Local_cpp_extception
This is an optional variable that defines the suffix for the C + + source file. You have to start with a point, the default is '. cpp ', but you can modify it. Such as:
Local_cpp_extception: =. cxx
Starting with NDK R7, you can define a sequence of suffixes in this variable, such as:
Local_cpp_extception: =. cxx. CPP. cc
Local_cpp_features
This is an optional variable that allows your code to use some C + + features. In order for your code to use RTTI (RunTime Type information), you can use:
Local_cpp_features: = Rtti
In order for your code to support C + + exceptions, you can use:
Local_cpp_features: = Exceptions
You can use them at the same time (not important in order)
Local_cpp_features: = Rtti FEATURES
The function of this variable is to enable the correct Compiler/linker flag when compiling the module from source code. For precompiled binaries, this also helps to declare the attributes on which the binaries depend, thus ensuring that the final linker works correctly.
It is recommended that you use this variable instead of directly defining-frtti,-fexceptions in Local_cppflags.
Local_c_includes
A list of optional paths relative to the NDK root, which is added to the containing search path when all source code is compiled (c,c++ or a combination of the two). Such as:
Local_c_includes: = Sources/foo
or even:
Local_c_includes: = $ (Local_path)/. /foo
These are placed in front of the corresponding flag contained in the Local_cflags/local_cppflags.
The local_c_includes is also automatically used when starting local debugging with Ndk-gdb.
Local_cflags
An optional collection of flags that are passed to the compiler when compiling C and C + + source code.
It is helpful to specify the definition of additional macros or compile options.
Important: Do not attempt to change the level of optimization/debugging in Android.mk, by specifying the appropriate information in the APPLICATION.MK, the system will help you automatically, and during the debug process, the NDK will generate useful data files.
Note: In ANDROID-NDK-1.5_R1, the corresponding flags can only be applied on C files and not on C + +. This issue has been corrected to match the behavior of the entire Android compilation system. (You can use Local_cppflags to specify a flag for C + + source files)
You can specify additional include paths by local_cflags + =-i<path>, but it would be better to use local_c_includes for this, because these paths might be used when debugging locally with NDK-GDB.
Local_cxxflags
The alias of the Local_cppflags. Note In later versions, this flag may be removed.
Local_cppflags
An optional set of flags passed to the compiler when compiling C + + source files (c + + only). They appear on the command line of the compiler after local_cflags.
Note: In Android-ndk-1.5_r1, the corresponding flag is applied to both C and C + + source code. These have been modified to match the entire Android compilation system. (You can now use Local_cflags to specify the flags for C and C + + source code).
Local_static_libraries
A list of static libraries modules (compiled with build_static_library) that should be linked to this module. This is only meaningful in shared library modules.
Local_shared_libraries
Runtime This module relies on the dynamic shared library ' modules ' list. This is necessary at the time of the link, and the corresponding information is embedded in the generated file.
Local_whole_static_libraries
It is a variant of local_static_libraries (used to express the corresponding library module) and it should use ' whole archives ' for the linker. You can view the GNU Linker's documentation to learn about the –whole-archive logo.
This is often useful when there are ring dependencies between many static libraries. Note that when you use it to compile a dynamic library, all the object files in your entire static library are forced to be added to the final binary file. Although it is not correct to generate the executable file.
Local_ldlibs
The list of additional linker flags that are used when compiling the module. It is useful to use the "-l" prefix to pass the name of the specified system library. For example, the following will tell the linker to generate a module that is linked to/system/lib/libz.so when it is loaded.
Local_ldlibs: =-lz
Check out Stable-apis for a list of system libraries that this NDK version can link to.
Local_allow_undefined_symbols
By default, when you attempt to compile a dynamic library, if you do not define any references, you will cause the "Undefined symbol" error. This is useful for catching bugs in your code.
However, for some reason you need to disable this check and set this value to ' true '. Note that the corresponding dynamic library may fail to load at run time.
Local_arm_mode
By default, the arm target binaries will be generated in the ' thumb ' mode, where each instruction is 16 bits wide. If you want to force an object file of module in the ' Arm ' (32-bit instruction) mode, you can define this variable as ' arm '. For example:
Local_arm_mode: = ARM
Note that you can also add the suffix '. Arm ' to the source file to tell the compilation system that you only want to use arm instructions for a source file. For example:
Local_src_files: =foo.c bar.c.arm
Tell the compilation system to always compile ' bar.c ' in ARM mode, compiling foo.c based on local_arm_mode values.
Note: The APPLICATION.MK setting App_optm as ' Debug ' will also force the generation of arm binaries. This is because there is a bug in the tool chain debugger that does not handle the thumb code well.
Local_arm_neon
Defining this variable as ' true ' allows the use of the arm Advanced SIMD (aka NEON) GCC directive in C and C + + code to use the NEON directive in an organization file.
It should only be defined if the target is ' armeabi-v7a ' ABI (corresponding to the ARMv7 instruction set). Note Not all ARMV7-based CPUs support neon instruction set extensions, and it is safer to detect the use of this code at run time. For more details, please read Cpu-arm-neon and cpu-features related content.
You can also use the '. Neon ' suffix to specify that a particular source file supports neon instruction compilation, for example:
Local_src_files =foo.c.neon bar.c Zoo.c.arm.neon
In this example, ' FOO.C ' is compiled in Thumb+neon mode, ' Bar.c ' is compiled in ' thumb ' mode, ' ZOO.C ' is compiled in ' Arm+neon ' mode.
Note that the '. Neon ' suffix must appear behind '. Arm ' If you use it at the same time. (such as Foo.c.arm.neon can work, but foo.c.neon.arm not!) ）
Local_disable_no_execute
Android NDK R4 supports the security features of NX bit. This is enabled by default, and if you do need to disable it, you can set this variable to ' true '.
Note: This feature does not modify the ABI, but is enabled only on devices with kernel target armv6+cpu.
To learn more, see:
Http://en.wikipedia.org/wiki/NX_bit
Http://www.gentoo.org/proj/en/hardened/gnu-stack.xml
Local_disable_relro
By default, the NDK compiled code is read-only to move the location and get got protection. This indicates that the runtime linker tag-specific memory area is read-only, after moving the location. This makes certain security vulnerabilities, such as got overrides, more difficult to perform.
By default it is enabled, but if you do need it, you can disable it by setting the variable to ' true '.
Note: These protections are only valid for new Android devices ("Jellybean" and higher versions). The code can still run on the older version (although there is no memory protection).
To learn more, see:
Http://isisblogs.poly.edu/2011/06/01/relro-relocation-read-only/http://www.akkadia.org/drepper/nonselsec.pdf ( Section 6)
Local_export_cflags
This variable is defined in order to record the collection of flags for A/C + + compiler, which is added to any other module-defined local_cflags, and this module is local_static_libraries or Local_ Shared_libraries use it.
For example, consider the definition under module ' foo ':
Include $ (clear_vars)
Local_module: = Foo
Local_src_files: = foo/foo.c
Local_export_cflags: =-dfoo=1
Include $ (build_static_library)
Another module, ' Bar ', relies on it:
Include $ (clear_vars)
Local_module: = Bar
Local_src_files: = bar.c
Local_cflags: =-dbar=2
Local_static_libraries: = Foo
Include $ (build_shared_library)
When compiling bar.c, the flag '-dfoo=1-dbar=2 ' will be passed to the compiler.
Exported flags are added to your module's local_cflags, so you can simply cover them. They can also be passed: if ' Zoo ' relies on ' bar ', ' bar ' relies on ' foo ', then ' Zoo ' will inherit all flags exported by ' Foo '.
Finally, when the compiled module exports them, the exported flags are not used. In the example above, when compiling foo/foo.c,-dfoo=1 is not passed to the compiler.
Local_export_cppflags
Same as Local_export_cflags, but only for C + + flags.
Local_export_c_includes
Same as Local_export_cflags, but it is for the C include path. This is very useful if ' bar.c ' wants to include the header file provided by module ' Foo '.
Local_export_ldlibs
Same as Local_export_cflags, but it is for linker flags. Note Because of how the UNIX linker works, the linker flags that are imported will be append into the local_ldlibs of your module.
This is very useful when module ' foo ' is a static library and it has code that relies on the system library. Local_export_ldlibs can be used to derive this dependency. For example:
Include $ (clear_vars)
Local_module: = Foo
Local_src_files: = foo/foo.c
Local_export_ldlibs: =-llog
Include $ (build_static_library)
Include $ (clear_vars)
Local_module: = Bar
Local_src_files: = bar.c
Local_static_libraries: =foo
Here, Libbar.so is compiled with-llog at the tail end of the linker command, indicating that it relies on the System log library because it relies on ' foo '.
Local_short_commands
Set this variable to ' true ' when your module has a lot of source files, or relies on a lot of static or dynamic libraries. This forces the compilation system to use an intermediate list file and use @$ (listfile) syntax with the library archiver or static linker.
This is very useful on Windows because its command line only receives a maximum of 8,191 characters, which is too small for complex projects.
This also affects the compilation of a single source file, if all compiler options are placed inside the list file.
Note If you set a value other than ' true ', it reverts to the default behavior. You can also define App_short_commands in the Android.mk file to force all modules in your project to use this feature.
Note: By default we do not recommend enabling this feature because it slows down compilation.
Local_filter_asm
Defining this variable for the shell command will filter the files compiled or generated from your local_src_files.
When it is defined, the following things will happen:
-all C or C + + will be generated to a temporary assembly file (not compiled into the object file).
-Any temporary assembly files listed in Local_src_files are sent through the local_filter_asm command to generate another temporary assembly file.
-These filtered assembly files are compiled into the object file.
In other words, if you have:
Local_src_files: = foo.c bar. S
Local_filter_asm: = Myasmfilter
FOO.C--1--> $OBJS _dir/foo. S.original--2--> $OBJS _dir/foo. S--3--> $OBJS _DIR/FOO.O
Bar. S--2--> $OBJS _dir/bar. S--3--> $OBJS _DIR/BAR.O
"1" corresponds to the compiler, "2" corresponds to the filter, "3" corresponds to the assembly. The filter must be a stand-alone shell command that takes the name of the input file as the first parameter and the name of the output file as the second parameter, for example:
Myasmfilter$objs_dir/foo. S.original $OBJS _dir/foo. S
Myasmfilter Bar. S $OBJS _dir/bar. S
Http://android.mk
ANDROID.MK File Syntax Guide
