Android. mk File Syntax specification and usage Template

 

 

Android. mk File Syntax Specification

Update, modify, and add images based on the serialization on eoeandroid.

Translate ANDROID-MK.TXT files today (original English files in/development/ndk/docs/android-mk.txt)

Android. mk File Syntax Specification

 

Introduction:

Android. mk is used to describe your C and C ++ source code files to Android ndk. This document describes its syntax. Before reading the following content, let's assume that you have read the docs/Overview. txt file and understood their roles and purposes.

 

Overview:

An android. mk file is used to describe your source code to the compilation system. Specifically:-This file is a small part of the GNU makefile and will be parsed by the compilation system once or more build systems. Therefore, you should minimize your declared variables and do not consider that some variables will not be defined during the parsing process. -The syntax of this file allows you to organize your source code into modules. A module belongs to one of the following types:

Static Library

Shared Library

Only the shared library will be installed/copied to your application software package. Although static databases can be used to generate shared libraries.

You can define one or more modules in each android. mk file. You can also use the same source code file in several modules.

/*************************************** **************************************/

-The compilation system handles many details for you. For example, you do not need to list header files and dependent files in your android. mk file. The ndk compilation system automatically handles these problems for you. This also means that after you upgrade the ndk, you should get the new toolchain/platform support and do not need to change your android. mk file.

Note: This syntax is very similar to the open source code of the publicly released Android platform. However, the method for implementing the compilation system is different. This is designed on purpose, it makes it easier for program developers to reuse the source code of external libraries.

 

Simple Example:

---------------

Before describing the syntax details, let's look at a simple "Hello World" example, for example, the following file:

Sources/helloworld. c

Sources/helloworld/Android. mk

'Helloworld. c' is a JNI shared library that provides native methods to return the "Hello World" string.

The corresponding Android. mk file will look like the following:

---------- Cut here ------------------

Local_path: = $ (call my-DIR)

Include $ (clear_vars)

Local_module: = helloworld

Local_src_files: = helloworld. c

Include $ (build_shared_library)

---------- Cut here ------------------

Okay. Let's explain these lines of code:

Local_path: = $ (call my-DIR)

An android. mk file must first define the local_path variable. It is used to search for source files in the Development tree. In this example, the macro function 'my-dir' is provided by the compilation system and used to return the current path (that is, the directory containing the Android. mk file ).

Include $ (clear_vars)

Clear_vars is provided by the compilation system, specifying that GNU makefile can clear many local_xxx variables for you (such as local_module, local_src_files, local_static_libraries, etc ...),

Except local_path. This is necessary because all the compilation control files are in the same GNU make execution environment, and all the variables are global.

Local_module: = helloworld

The local_module variable must be defined to identify each module you describe in the Android. mk file. The name must be unique and contain no spaces. Note that the compilation system automatically generates the appropriate prefix and suffix. In other words, a shared library module named 'foo' will generate the 'libfoo. so' file.

Important Notes

If you name the library 'libhelloworld', the compiling system will not add any lib prefix or generate libhelloworld. so, this is to support Android from the source code of the Android platform. MK file, if you do need to do so.

Local_src_files: = helloworld. c

The local_src_files variable must contain the C or C ++ source code files to be compiled and packaged into the module. Note that you do not need to list header files and contained files here, because the compilation system will automatically find the dependent files for you; just list the source code files directly transmitted to the compiler. [Note: The default C ++ source code file extension is '. CPP '. it is also possible to specify a different extension. As long as you define the local_default_cpp_extension variable, do not forget the starting dot (that is, defined '. cxx', rather than 'cxx') (of course we will not change this step )]

Include $ (build_shared_library)

Build_shared_library is a variable provided by the compilation system. It points to a GNU makefile script (which should be shared_library.mk In the build/Core directory) and is responsible for collecting information from the previous call to 'include $ (clear_vars, define all the information in the local_xxx variable and decide what to compile and how to perform it correctly. And generate a static library based on its rules. Similarly, for static databases.

 

 

 

/*************************************** *************************************/

There are more complex examples in the sources/Samples Directory. You can see the Android. mk file with annotations.

Refer:

This is a list of variables that you should depend on or define in Android. mk. You can define other variables for your own use,

However, the ndk compilation system retains the following variable names:

-Name starting with local _ (for example, local_module)

-Name starting with private _, ndk _ or app _ (used internally)

-Lowercase name (for internal use, for example, 'My-dir ')

If you want to define your own variables in Android. mk for convenience, we recommend that you use the my _ prefix. A small example:

---------- Cut here ------------------

My_sources: = Foo. c

Ifneq ($ (my_config_bar ),)

My_sources + = bar. c

Endif

Local_src_files + = $ (my_sources)

---------- Cut here ------------------

-----------

These GNU make variables are defined by the compilation system before parsing your android. mk file.

Note that in some cases, ndk may analyze Android. mk several times, and the definitions of some variables may vary.

Clear_vars

Point to a compilation script. Almost all undefined local_xxx variables are listed in "module-description.

You must include this script before starting a new module. Include $ (clear_vars)

 

Build_shared_library

Point to the compile script to collect all the information you provide in the local_xxx variable, and decide how to compile the source code file you listed into a shared library. Note that you must define local_module and local_src_files at least before including the file. Example:

Include $ (build_shared_library)

Note that this will generate a file named Lib $ (local_module). So.

 

Build_static_library

A build_shared_library variable is used to compile a static library. The static library will not be copied to your project/packages and can be used to compile the Shared Library (see the local_static_libraries and local_static_whole_libraries described below)

Example:

Include $ (build_static_library)

Note that this will generate a file named Lib $ (local_module)..

 

Target_arch

The name of the target CPU platform, as specified in the android open source code. If it is 'arm', it indicates that the arm-compatible command is to be generated and is irrelevant to the CPU architecture revision.

 

Target_platform

Android. mk parsing, the target Android platform name. For details, refer to/development/ndk/docs/stable-apis.txt.

Android-3-> official Android 1.5 System Images

Android-4-> official Android 1.6 System Images

Android-5-> official Android 2.0 System Images

 

Target_arch_abi

Currently only two values, armeabi and armeabi-v7a are supported. In the current version, these two values are generally simply defined as arm, which can be better matched through redefinition within the Android platform.

Other Abi files will be described in later ndk versions. They will have different names. Note that all ARM-based Abi will define 'target _ arch 'As 'arm', but there will be different 'target _ arch_abi'

 

Target_abi

The combination of the Target Platform and ABI is actually defined as $ (target_platform)-$ (target_arch_abi) when you want to test a particular target system on a real device, it will be useful. By default, it will be 'android-3-arm '.

 

 

/*************************************** **************************************/

The following is the GNU make 'function' macro, which must be evaluated by using '$ (call <function>)'. They return regionalized information.

My-Dir

Returns the directory path of the current Android. mk file, relative to the top layer of the ndk compilation system. This is useful. It is defined at the beginning of the android. mk file:

Local_path: = $ (call my-DIR)

 

All-subdir-makefiles

Returns a list of subdirectories in the current 'my-dir' path. For example, you can view the following directory levels:

Sources/Foo/Android. mk

Sources/Foo/lib1/Android. mk

Sources/Foo/lib2/Android. mk

If sources/Foo/Android. mk contains one line:

Include $ (call all-subdir-makefiles)

Then it automatically contains sources/Foo/lib1/Android. mk and sources/Foo/lib2/Android. mk

This function provides the compilation system with a deep nested code directory hierarchy. Note that by default, ndk will only search for files in sources/*/Android. mk.

 

This-makefile

Returns the path of the current makefile (where this function is called)

 

Parent-makefile

Returns the path of the parent makefile in the call tree. That is, the makefile path that contains the current makefile.

 

Grand-parent-makefile

Guess...

 

 

/*************************************** **************************************/

Module description variable:

The following variables are used to describe your module to the compilation system. You should define it between 'include $ (clear_vars) 'and 'include $ (build_xxxxx. As described above, $ (clear_vars is a script that clears all these variables unless explicitly stated in the description.

 

Local_path

This variable is used to show the path of the current file. You must define it at the beginning of Android. mk, which can be used as follows:

 

Local_path: = $ (call my-DIR)

This variable will not be cleared by $ (clear_vars), so each android. mk only needs to be defined once (even if several modules are defined in a file ).

 

Local_module

This is the name of your module. It must be unique and cannot contain spaces. You must define it before it contains any $ (build_xxxx) script. The module name determines the name of the file to be generated. For example, if the name of a shared library module is <Foo>, the file to be generated is lib <Foo>. So. However, in your ndk generated file (or android. mk or application. mk), you should only involve (reference) other modules with normal names.

 

Local_src_files

This is the list of source code files to be compiled. You only need to list the files to be passed to the compiler, because the compilation system automatically calculates dependencies for you.

Note that the source code file names are relative to local_path. You can use the path section, for example:

Local_src_files: = Foo. c/

Toto/bar. c

Note: Unix-style slashes (/) must be used in the generated files. The windows-style backslash will not be correctly processed.

 

Local_cpp_extension

This is an optional variable used to specify the extension of the C ++ code file. The default value is '. cpp', but you can change it, for example:

Local_cpp_extension: =. cxx

 

Local_c_includes

Optional path configuration, starting from the root directory,

All sources (C, C ++ and assembly). For example:

Local_c_includes: = sources/foo

Or even:

Local_c_includes: = $ (local_path)/../foo

It must be before any flag containing local_cflags/local_cppflags.

 

Local_cflags

Optional compiler options, used when compiling C code files.

This may be useful, specifying an additional include path (relative to the top-level directory of the ndk), macro definition, or compilation options.

Important information: do not go to Android. in MK, you only need to change the optimization/debugging level in application. if you specify the appropriate information in MK, the problem will be automatically handled for you. During debugging, The ndk will automatically generate useful data files.

 

Local_cxxflags

Same as local_cflags for C ++ source files

 

Local_cppflags

Same as local_cflags, but applicable to both C and C ++ source files.

 

Local_static_libraries

It should be linked to the static library list of this module (generated using build_static_library), which is only meaningful to the shared library module.

 

Local_shared_libraries

The list of shared library modules that this module depends on when running. When linking, You need to embed the relevant information when generating the file. Note: This will not append the listed modules to the compilation graph, that is, you still need to add them to the modules required by the program in application. mk.

 

Local_ldlibs

Additional Linker Options to be used to compile your module. This is useful for passing the name of the specified database using the "-l" prefix. For example, the following will tell the module generated by the linker to link to/system/lib/libz. So at the time of loading.

Local_ldlibs: =-LZ

Look at the docs/STABLE-APIS.TXT to get a list of open system libraries that you can link to using the ndk release.

 

Local_allow_undefined_symbols

By default, when attempting to compile a shared library, any undefined reference will cause an "undefined symbol" error. This will be of great help for capturing errors in your source code files.

However, if you do not need to start this check for some reason, set this variable to 'true '. Note that the corresponding shared library may fail to be loaded at runtime. (Do not set this parameter to true)

 

Local_arm_mode

By default, the arm target binary is generated in the form of thumb (16 bits). You can set this variable to arm if you want your module to be in the form of a 32-bit command.

'Arm '(32-bit instructions) mode. E. g .:

Local_arm_mode: = arm

Note that you can also tell the system to compile a specific type during compilation, such

Local_src_files: = Foo. c bar. C. Arm

This tells the system to always compile bar. c In arm mode,

 

 

Android. mk Template

Multiple executable programs, dynamic libraries, and static libraries can be generated in an android. mk file.

1. Compile the Application Template:

# Test exe

Local_path: = $ (call my-DIR)

# Include $ (clear_vars)

Local_src_files: = Main. c

Local_module: = test_exe

# Local_c_includes: =

# Local_static_libraries: =

# Local_shared_libraries: =

Include $ (build_executable)

(Cainiao-level explanation: = is the meaning of the value assignment, $ is to reference the value of a variable.) Add the source file path to local_src_files and add the header file path to local_c_pair des, local_static_libraries is added to the static library to be linked (*. a) Name. Add the dynamic library (*. so) name. local_module indicates the final name of the module, and build_executable indicates compiling in an executable program.

2. Compile the static library template:

# Test static lib

Local_path: = $ (call my-DIR)

Include $ (clear_vars)

Local_src_files: =/

Helloworld. c

Local_module: = libtest_static

# Local_c_includes: =

# Local_static_libraries: =

# Local_shared_libraries: =

Include $ (build_static_library)

In general, it is similar to the above. build_static_library indicates compiling a static library.

3. Compile the dynamic library template:

# Test shared lib

Local_path: = $ (call my-DIR)

Include $ (clear_vars)

Local_src_files: =/

Helloworld. c

Local_module: = libtest_shared

Target_prelink_modules: = false

# Local_c_includes: =

# Local_static_libraries: =

# Local_shared_libraries: =

Include $ (build_shared_library)

In general, it is similar to the above. build_shared_library indicates compiling a shared library.

 

The above three generation results are as follows, and the generic changes according to the specific target:

Out/target/product/generic/obj/executable

Out/target/product/generic/obj/static_library

Out/target/product/generic/obj/shared_library

The target folders of each module are:

Executable program: xxx_intermediates

Static Library: xxx_static_intermediates

Dynamic library: xxx_shared_intermediates

In addition, in the Android. mk file, you can specify the final target installation path, which is specified using local_module_path and local_unstripped_path. Use the following macro to select different file system paths:

Target_root_out: indicates the root file system.

Target_out: indicates the system file system.

Target_out_data: indicates the data file system.

Usage example:

Local_module_path: = $ (target_root_out)

Http://blog.chinaunix.net/u3/99423/showart_2206760.html