ANDROID.MK Official Description Chinese Translation

Reprint Please specify source: http://blog.csdn.net/qq_15650553/article/details/51548025

Translator Note: The first time to do such a translation, I feel still a lot of shortcomings, some concepts do not have a good understanding, so the translation of Chinese may also have problems. This article is mainly used to record their learning income. So it is not impossible for netizens to study according to the following translation, but please be cautious.

This article describes the syntax of the android.mk file, which links the android Ndk with your C + + code.

Overview

This android.mk file exists in a subdirectory of the JNI directory under your project, and it describes your source code and shared library to the compilation system. This file is a small fragment of the GNU Makefile, and the compilation system reads it one or more times. The android.mk file is useful for defining project-wide settings that application.mk, the build system, and your Environme NT variables leave undefined. It can also override project-wide settings for specific modules.

You can use Android.mk's syntax to divide your source code into multiple module. A module can be a static library, a shared library, or a standalone executable file. You can define one or more module in each android.mk file, and you can also use the same source file in different module. Compiling the system will only put the shared library in your app's package. In addition, a static library can generate a shared library.

In order to package these libraries, the compilation system handles a lot of detail for you. For example, you do not need to list the files in the android.mk, and you do not need a clear dependency between the generated files. The NDK compilation system has automatically calculated these relationships for you. Therefore, you should be able to benefit from future support for the new Toolchain/platform NDK version without having to edit the Android.mk file.

The syntax for this Android. File is very close to the Android.mk file that is used in Android Open Source project. While the build system implementation this uses them is different, their similarity was an intentional design decision AIME D at making it easier for application developers to reuse source code for external libraries.

Basics

Before you begin exploring the syntax of the android.mk file, it is useful to understand the basic components of android.mk. This chapter uses the ANDROID.MK in the Hello-jni sample project and explains the role of each line in the file.

A android.mk file must start with the definition Local_path:

LOCAL_PATH := $(call my-dir)

This variable indicates the location of the source file in the development tree. Here, MY-DIR This macro function is provided by the compiled system and returns the path to the current directory (this directory contains the android.mk file itself).
The next line defines the Clear_vars variable that is provided by the build system.

include $(CLEAR_VARS)

Clear_vars This variable points to a special GNU Makefile, a Makefile that clears a lot of variables like local_xxx for you, such as Local_module,local_src_files, and Local_ Static_libraries. Note that Local_path is not cleared here. This variable must keep its value because the system parses all build control files in a single GNU make execution context where all variables is Glob Al You have to declare this variable before you describe each module.

Then, local_module this variable to save the name of the MODULE you want to compile. Use this variable once in each module of your app.

LOCAL_MODULE := hello-jni

The name of each module must be unique and cannot contain spaces. When the compilation system generates the final shared library, the value you give to Local_module is automatically prefixed and suffixed, for example, the above example generates a library named libhello-jni.so.

Note: If the prefix of your module's name has been added to Lib, the compilation system will no longer prefix you, it will directly use the name of the module as the name of the shared library, plus the extension of. So. So, if the name of a source file is originally called LIBFOO.C, then the name of the generated shared library is libfoo.so. This feature is intended to support the shared library generated by the Android platform sources through android.mk; the names of libraries like this will start with Lib.

The next line lists the source files, using spaces to isolate the different source files:

LOCAL_SRC_FILES := hello-jni.c

The local_src_files must include a list of source files that you want to include in the module.

The last line helps the system connect everything together.

include $(BUILD_SHARED_LIBRARY)

Build_shared_library This variable points to a GNU Makefile script that collects information from each LOCAL_XXX variable that you define from the most recent include. This script determines what to build and how to build it.

There are more complex sample code, which in the Samples folder contains annotated android.mk files. In addition, Sample:native-activity provides a very detailed explanation of the ANDROID.MK document. Finally, Variables and macros provide a more in-depth explanation of the variables in this chapter.

Variables and Macros

The compilation system provides a number of variables that can be used in android.mk. Most of the variables are pre-specified values. The value of the other variables you have to specify.

In addition to these variables, you can also define your own variables. If you intend to do this, remember that the NDK system retains the following variable names:

• A name that begins with Local_, such as Local_module.

• Start with a private_, Ndk_, or app. These variable names are used internally by the compiling system.

• A lowercase variable name, such as My-dir. These variable names are also used internally by the compilation system.

If you want to define your own variables in android.mk, we recommend that you precede the names with My_.

NDK-Defined variables

In this chapter we discuss GNU make variables, which are defined before the compilation system parses the Android.mk file. In some cases, the NDK will parse your android.mk file several times, each time using a different definition to parse some of the variables.

Clear_vars

This variable points to a build script that clears almost all of the local_xxx variables mentioned in the previous chapter. Using this variable to refer to this script before describing a new module uses its syntax:

include $(CLEAR_VARS)

Build_shared_library

This variable points to a script that collects the LOCAL_XXX variable information you define in each module, and this variable also determines how to use your source code to compile a shared library. Note that using this variable requires that you have at least defined local_module and local_src_files. (For more information, see Module-description Variables)

The syntax for using this variable is as follows:

include $(BUILD_SHARED_LIBRARY)

One such variable causes the compilation system to generate a library that ends with. So.

Build_static_library

This variable is a variant of build_shared_library and is used to generate a static library. The build system does not include static libraries in your project, but you can use static libraries to generate shared libraries (refer to Local_static_libraries and local_whole_static_libraries, below). The syntax for this variable is:

include $(BUILD_STATIC_LIBRARY)

Such a variable causes the compilation system to generate a library that ends in. A.

Prebuilt_shared_library

Point to a script that is used to designate a pre-built shared library. Unlike Build_shared_library and Build_static_library, the value of local_src_files cannot be a source file, it must be a separate path to a pre-built shared library, such as foo/libfoo.so. The syntax for using this variable is:

include $(PREBUILT_SHARED_LIBRARY)

You can also use the Local_prebuilts variable in another module to refer to a pre-built library. See the Using prebuilt Libraries for more information.

Prebuilt_static_library

Same as Prebuilt_shared_library, just point to a pre-built static library. For more information, see Using prebuilt Libraries.

Target_arch

This variable is the name of the target CPU architecture, just like the target CPU architecture specified in Android Open Source Project. This variable is used for any arm-compatible build, or arm, or a revision independent of the CPU structure, or ABI (see Target_arch_abi below).

The value of this variable is obtained from the app_abi you defined in the Android.mk file, and the system reads App_abi before parsing the android.mk file.

Target_platform

This variable represents the number of target Android APIs that the system builds. For example, Android 5.1 corresponds to Android API 22:android-22. For complete system and API-related relationships, refer to the Android NDK Native APIs. The following example shows how to use this variable:

TARGET_PLATFORM := android-22

Target_arch_abi

When the compilation system parses the Android.mk file, this variable stores the CPU and schema name. You can specify one or more names listed below, use spaces to separate two names, and Table 1 shows the ABI settings when using each CPU and schema.

Table 1. For unused CPUs and schemas, the ABI is set.

CPU and Architecture	Set
ARMv5TE	Armeabi
ARMv7	armeabi-v7a
ARMV8 AArch64	arm64-v8a
i686	x86
X86-64	x86_64
MIPS32 (R1)	Mips
MIPS64 (R6)	Mips64
All	All

The following example shows how to set the ARMv8 AArch64 as the target schema:

TARGET_ARCH_ABI := arm64-v8a

Note: Before the Android NDK 1.6_r1 this variable was defined as arm.

For more information on architecture Abis and related issues, refer to ABI Management;

The new schema ABI that appears in the future will have different values.

Target_abi

Linking the level of the API to the ABI is especially useful when you are debugging a system on a real machine. For example, specify a 64-bit ARM device that is powered by Android 22:

TARGET_ABI := android-22-arm64-v8a

Note: until the Android NDK 1.6_r1, the default value is Android-3-arm.

Module-description Variables describes the variables of module

These variables in this chapter are used to describe your module for system building. The description of each module should follow these guidelines:

1. To initialize or remove the variables associated with this module, use Clear_vars.
2. The module is described by assigning values to these variables.
3. To set up the NDK use the appropriate script to compile the module, use Build_xxx.

Local_path

The function of this variable is to give the path to the current file. You must define it at the beginning of the Android.mk file. The following example shows how to use:

LOCAL_PATH := $(call my-dir)

The script pointing to Clear_vars does not clear this variable. So, even if you have a few module definitions in your Android.mk file, you still need to define this variable only once.

Local_module

This variable stores the name of your module. In all defined module, the value of this variable must be unique and cannot contain spaces. You must define it between any script files (except Clear_vars). You do not need to add the Lib prefix or the. So and. a suffixes. The compilation system automatically adds prefixes and suffixes. The module is represented in the android.mk and application.mk files by referring to the module's name. (Throughout your android.mk and application.mk files, refer to your module by its unmodified name). For example, the following sentence generates a shared library module named libfoo.so:

LOCAL_MODULE := "foo"

If the name of the library you want to generate is not the value of Lib plus local_module, you can use Local_module_filename to set the name you want.

Local_module_filename

This variable is optional and allows you to use this variable to set the name of the generated library instead of the system default name. For example, the value of your local_module is foo, and you can force the system to generate a library whose name is Libnewfoo. The following line shows how to do this:

LOCAL_MODULE := foo
LOCAL_MODULE_FILENAME := libnewfoo

If you are building a shared library, the name of the file will be libnewfoo.so.

Note: You cannot modify the file path or suffix name.

Local_src_files

This variable contains the list of source files that you want to make up the module. As long as you list the source files that need to be compiled by the compiler, the compilation system automatically calculates the dependencies.

Note the absolute path and relative path you can use.

We recommend that you avoid using absolute paths, which will make your android.mk files more portable.

Note: only UNIX-style forward slashes (/) should be used in the build file. The build system does not recognize the Windows-style backslash (\).

Local_cpp_extension

You can use this optional variable to specify the suffix name of your C + + source file other than. cpp. For example, the following example changes the suffix name to. cxx (must contain the preceding '. '):

LOCAL_CPP_EXTENSION := .cxx

Since NDK R7, you can use this variable to specify multiple suffix names. For example:

LOCAL_CPP_EXTENSION := .cxx .cpp .cc

Local_cpp_features

You can use this optional variable to indicate that your code relies on special C + + features. It will use the corresponding compilers and linker during the build process. This variable also defines the attributes that the prebuilt binaries depend on to help make the final link process correct. We recommend that you use this variable instead of using Local_cppflags to directly open the Frtti and fexceptions features. Use this variable to help the compilation system set a separate appropriate signal value (flags) for each module. Using local_cppflags causes the compiler to set all of the specified signal values for all module, regardless of what is really needed.

For example, specify that your code uses RTTI (run-time type information), and write down:

LOCAL_CPP_FEATURES := rtti

Specify that your code uses C + + exceptions:

LOCAL_CPP_FEATURES := exceptions

You can also specify multiple values:

LOCAL_CPP_FEATURES := rtti features

The order of the values is not important.

Local_c_includes

You can use this variable to specify the path of the include in the NDK compile code (c,c++, assembly). For example:

LOCAL_C_INCLUDES := sources/foo

Even:

LOCAL_C_INCLUDES := $(LOCAL_PATH)//foo

Define this variable before you set up include with Local_cflags and Local_cppflags.

The compiled system also uses the path defined by Local_c_includes when using Ndk-gdb Debugging for native debugging.

Local_cflags

This optional variable sets the compiler tag (compiler Flags) that the compilation system needs to pass when compiling C and C + + code. This feature is useful when specifying additional macro definitions or compilation options.

Try not to change the level of optimization/debugging in Android.mk. The compilation system will automatically set this variable for you based on the information in the APPLICATION.MK. Compiling the system in this way generates a data file that is useful when debugging.

Note: in ANDROID-NDK-1.5_R1, this flag value is only used in C files, not C + + files. Now they are fitted with the features of the complete Android build system. (You can now use Local_cppflags to set up flag for C + + files specifically).

It is possible to specify an additional include path in this way through the line surface:

LOCAL_CFLAGS += -I<path>,

This is better than using local_c_includes, because these paths can be used when debugging native programs using NDK-GDB.

Local_cppflags

This variable is an optional compiler token that needs to be passed only when compiling a C + + source file. The local_cppflags variable appears in the compiler's command line, after the local_cflags appears.

* Note: * In android-ndk-1.5_r1, this variable acts on both C and C + + source files. If you want to specify compiler tags for both C and C + +, use Local_cflags.

Local_static_libraries

This variable specifies the static library that the current module depends on.

If the current module is a shared library or executable file, this variable forces the libraries to be connected to the last generated binary file.

If the current module is a static library, this variable only indicates that the other module that relies on the current module also relies on the library specified by this variable.

Local_shared_libraries

This variable specifies the shared library that the current module depends on at run time. The information for this variable is required at link time, and this variable embeds the corresponding information in the resulting file.

Local_whole_static_libraries

This variable is a variant of local_static_libraries, which indicates that the linker should consider the associated library to be whole archives. For more information about whole archives you can view the GNU Linker's documentation to see the –whole-archive tag.

This variable is useful when there are cyclic dependencies in several static libraries. When you use this variable to build a shared library, this variable forces the compilation system to copy all the object files from the static library to the last library. Then it's wrong to do this when you want to generate the executable file.

Local_ldlibs

This variable contains additional linker tags that are used when building your shared library or executable file. This variable allows you to pass the name of the library in the system you specify by using the-l prefix. For example, the following example tells the linker to generate a module that, when loaded, links the/system/lib/libz.so.

LOCAL_LDLIBS := -lz

If you want to view a list of system libraries that can be used in the NDK, view the Android ndk Native APIs.

Note: If you define this variable in a static library, the compilation system ignores it and ndk-build prints a warning.

Local_ldflags

This variable represents the list of other linker tags that the compilation system needs when building a shared library or executable. The following example uses the LD.BFD linker of the arm/x86 GCC 4.6+ platform, where Ld.gold is the default:

LOCAL_LDFLAGS += -fuse-ld=bfd

Note: If you define this variable in a static library, the compilation system ignores it and ndk-build prints a warning.

Local_allow_undefined_symbols

By default, the compilation system throws an undefined error (undefined symbol error) If an undefined reference is found when building a shared library. This error is useful when you are looking for a bug.

To turn this check off, set this variable to true. Note this may cause the shared library to load at run time.

Note: If you define this variable in a static library, the compilation system ignores it and ndk-build prints a warning.

Local_arm_mode

By default, compiling the system in Thumb mode generates the binary of the ARM architecture, which is 16-bit in size and links the STL library files in the thumb/directory. Defining this variable as arm will force the compilation system to generate the module's object file in 32-bit arm mode. Here's how to do it:

LOCAL_ARM_MODE := arm

You can also have the compilation system compiled in arm mode only for the files you specify, and you need to add the. arm suffix to the name of the source file. For example, the following example tells the compiler to always compile bar.c in ARM mode, but for FOO.C is compiled based on the value of Local_arm_mode.

LOCAL_SRC_FILES := foo.c bar.c.arm

Note: You can also use the App_optim in the application.mk to create an arm binary file for debugging. Specifying debug forces the build in arm mode because the debugger of the toolchain does not correctly handle the code in thumb mode.

Local_arm_neon

This variable is only useful when specified as armeabi-v7a ABI. This variable allows you to use the ARM Advanced SIMD (NEON) GCC credit function in your C, C + +, and assembler.

Note that not all CPUs of the ARMV7 series support the neon instruction set extension. For this reason, you must check at run time to make it safe to run the code. See Neon Support and the Cpufeatures Library for more information.

Alternatively, you can have the compiler take neon support for the specified file by adding the. Neon to the name of the source file. In the following example, the compilation system compiles the foo.c in the form of thumb and neon support, compiles the bar.c in a thumb-supported fashion, and compiles zoo.c in the way that arm and neon support.

LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon

If you want to use these suffixes, then make sure. Arm is before. Neon.

Local_disable_no_execute

Android NDK R4 adds support for the security features of "NX bit". This is turned on by default, but you can turn it off by setting this variable to true. We do not recommend that you do so in the absence of a good reason.

This feature does not modify the ABI and is only enabled in the kernel of the armv6+ CPU. Machine code with this feature turned on without modification to a device that uses an earlier CPU architecture.

For more information, refer to Wikipedia:nx bit and the GNU stack kickstart.

Local_disable_relro

By default, the NDK takes advantage of read-only relocation addresses and got protection. This variable makes some security vulnerabilities more difficult (such as got rewriting) by making the runtime's linker tag some memory areas after relocation as read-only memory. Note that these protections are only after API 16, and when the API is below 16, the code will still run, but there is no memory protection.

This variable is open by default, and you can also turn it off by setting the variable to true. We do not recommend that you do this without a good reason.

See Relro:relocation Read-only and Security enhancements in RedHat Enterprise Linux (section 6) for more information.

Local_disable_format_string_checks

By default, the compile-time system compiles with string protection. Doing so causes a compiler error if a very non-constant string is used in a function similar to printf.

This variable is open by default, and you can also turn it off by setting the variable to true. We do not recommend that you do this without a good reason.

Local_export_cflags

This variable adds a series of C/C + + compile tags for this module to the Local_cflags values of those module that refer to this module through Local_static_libraries and Local_shared_libraries.

For example, observe the following two Module,foo and Bar,bar dependent on foo:

include $(CLEAR_VARS)
LOCAL_MODULE := foo
LOCAL_SRC_FILES := foo/foo.c
LOCAL_EXPORT_CFLAGS := -DFOO=1
include $(BUILD_STATIC_LIBRARY)

include $(CLEAR_VARS)
LOCAL_MODULE := bar
LOCAL_SRC_FILES := bar.c
LOCAL_CFLAGS := -DBAR=2
LOCAL_STATIC_LIBRARIES := foo
include $(BUILD_SHARED_LIBRARY)

Here, the compilation system passes-dfoo=1 and-dbar=2 to the compiler when the compiler compiles bar.c. The compilation system will also pre-local_cflags the values of the module you are referencing to the local_cflags of your current module, so that you can easily rewrite them.

In addition, the relationship between module is transitive, and if the zoo relies on Bar,bar to rely on Foo, then the zoo will inherit the markup from Foo.

Finally, the compiled system does not use the exported tags when compiling locally (for example, compiling a module that is exported by a tag). So, in the example above, the compiler foo/foo.c did not pass-dfoo=1 to the compiler. If you want to compile locally, use Local_cflags.
(Translator Note: The concept of local compilation (building locally) Here is not very clear)

Local_export_cppflags

This variable is the same as local_export_cflags, except that the variable is only applicable to C + + tags.

Local_export_c_includes

This variable is the same as local_export_cflags, but the path to the include for C. For example, this variable is useful when bar.c needs to introduce a header file for Foo.

Local_export_ldflags

This is the same as local_export_cflags, but this is used for linker identification.

Local_export_ldlibs

This is the same as Local_export_cflags, which tells the build system to pass the name of the specified system library to the compiler. You need to add-l to the name of the library you specify.

Note that the build system will import the linker ID into the LOCAL_LDLIBS value of your module. This is done because of how the UNIX linker works.

This variable is useful when Foo is a static library and contains code that relies on the system library. You can use Local_export_ldlibs to export these dependencies, 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
include $(BUILD_SHARED_LIBRARY)

In this example, the build system will add-llog to the end of the linker command when building the libbar.so. This tells the linker that because Libbar.so relies on Foo, it also relies on the log library of the system.

Local_short_commands

Set this variable to True when your module contains a lot of source code or relies on a static library or shared library. Doing so forces the build system to use @ Syntax for archives containing intermediate object files or linking libraries.

This feature is useful on the Windows platform because the Windows platform command line contains a maximum of 8,191 characters and is too small for complex systems. It also impacts the compilation of individual source files, placing nearly all compiler flags inside list files, too.

Note Any value that is not true causes the default setting to be changed. You can also enforce all the module behavior of your project in the Application.mk file.

We do not recommend that this feature be turned on by default because it makes the build system slower.

Local_thin_archive

Set this variable to true when building a static library. Doing so generates a light, small library file that typically does not contain an object file and contains only the path to those object files.

Doing so is useful for reducing the size of the output file. One drawback to this is that this kind of library file cannot be moved to a different location (because the paths in the library files are relative paths).

Valid values are, true,false, or spaces. You can set a default value on Application.mk's app_thin_archive.

Note: This variable is ignored in non-static libraries or pre-built static libraries.

Local_filter_asm

(Not very understanding, to be translated)
Define this variable as a shell command that the build system would use to filter the assembly files extracted or generated From the files you specified for local_src_files.

Defining this variable causes the following things to occur:

The build system generates a temporary assembly file from any C or C + + source file, instead of compiling them into an obje CT file.
The build system executes the shell command in Local_filter_asm on any temporary assembly file and on any assembly file Li Sted in Local_src_files, thus generating another temporary assembly file.
The build system compiles these filtered assembly files into an object file.
For example:

LOCAL_SRC_FILES := foo.c bar.S
LOCAL_FILTER_ASM :=
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" to the filter, and "3" to the assembler. The filter must is a standalone shell command that takes the name of the input file as its first argument, and the name of The output file as the second one. For example:

myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S
myasmfilter bar.S $OBJS_DIR/bar.S

function macros provided by the NDK-PROVIDED function macros NDK

This section describes the function macros provided by the NDK for GNU make. Used $(call <function>) to evaluate, they return text information.

My-dir

This macro returns the path of the recently joined Makefile, which is generally the path of the current ANDROID.MK. My-dir is useful in the definition of Local_path that begins with your android.mk, for example:

LOCAL_PATH := $(call my-dir)

Because of the way GNU make works, the return value of this macro is the path of the makefile that the build system finally introduced when parsing the build script. For this reason, you should not continue to use My-dir after you include other files.

For example, consider the following example:

LOCAL_PATH := $(call my-dir)
..........declare one module
include $(LOCAL_PATH)/foo/Android.mk
LOCAL_PATH := $(call my-dir)
..........declare another module

The problem here is that the second My-dir call sets the value of Local_path to $PATH/foo not $PATH/foo , because it $PATH/foo is the path to the most recent include.

You can avoid this problem by adding some extra includes to the Android.mk file. 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 file
include $(LOCAL_PATH)/foo/Android.mk

If this is not feasible, then you can put the first call to My-dir value in another variable, for example:

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 the list of android.mk in the subdirectory under the My-dir path.

You can use this function to provide a deep nested relationship to the build system. By default, the NDK will only look for files in the directory containing the android.mk file.

This-makefile

Returns the path () of the current makefile file.

Parent-makefile

Returns the current path of the makefile that contains the current makefile.

Grand-parent-makefile

Returns the path of the grandparent makefile in the inclusion tree (the path of the makefile, the current one ).

Import-module

This is a android.mk file that allows you to find and include this module through the module's name. Typical applications include the following:

$(call import-module,<name>)

In this example, the build system looks for the named MODULE in the directory indicated by the NDK_MODULE_PATH environment variable <name> , and then automatically contains the corresponding android.mk file for you.

ANDROID.MK Official Description Chinese Translation