NDK官方开发指南翻译序列之 Application.mk

Application.mk file syntax specification

Introduction:

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

本文档描述Application.mk文件的语法，这个编译文件描述Android应用须要的本地modules。为了便于理解下面的内容，假设你已经阅读了OVERVIEW相关内容，了解了它们的做用以及用法。

在阅读如下文档以前，请先阅读OVERVIEW和Android.mk相关内容。

Overview：

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

Application.mk是用来描述你应用程序须要的本地‘modules’（如静态/共享库）。

Application.mk一般放在$PROJECT/jni/Application.mk下，$PROJECT指向你应用程序的工程目录。

另外，也能够放在$NDK/apps的子目录下，例如：

   $NDK/apps/<myapp>/Application.mk

<myapp>是用来向NDK编译系统描述你应用程序的一个简短名称（这个名字不会编译到动态库和最终的程序包中）。

Application.mk是一个很是轻量级的GNUMakefile脚本，必须定义一些变量：

APP_PROJECT_PATH

这个变量必须给出你应用程序的工程根目录的绝对路径。这个用来拷贝/安装生成JNI动态库的stripped版本到一个APK生成工具知道的指定位置。

注意$PROJECT/jni/Application.mk是可选的，可是对于$NDK/apps/<myapp>/Application.mk倒是强制要求的。

APP_MODULES

这个变量是可选的。若是没有定义，NDK将会采用默认的方式，编译在Android.mk声明的全部modules，同时包含了全部子目录下的Android.mk文件。

若是APP_MODULES定义了，它必须是用空格分开的module名称的列表，这些module的名称就是在Android.mk文件中LOCAL_MODULE定义的。注意NDK将会自动计算module的依赖关系。

注意：在NDK r4中变量的默认行为发生了变化。以前的是：

-在Application.mk中这个变量是强制要求的

-必须显示的列出全部须要的modules。

APP_OPTIM

这个可选的变量可定义在‘release’或者‘debug’中。当编译应用程序的modules的时候，这个用来改变优化级别。

默认是‘release’模式，并生成高级别的二进制文件。‘debug’模式会生成没有优化的二进制文件，这样更容易调试。

注意若是你的应用程序是可调试的（如在manifest的<application>设置android:dubuggable为‘true’），这样默认的就是‘debug’而不是‘release’。这个能够经过设置APP_OPTIM为‘release’来覆盖它。

注意能够同时设置为‘release’和‘debug’，可是在debuggingsessions过程当中‘release’编译倾向提供比较少的信息：一些变量进行了优化，不能被检查，代码进行了从新排序使得单步调试代码变得困难，栈的跟踪将变得不可靠，等等。。。

APP_CFLAGS

当编译任何modules中的c或c++源文件的时候，会传递一个C编译标志的集合。这个能够用来改变应用程序须要的module的编译行为，而不须要修改Android.mk文件自己。

重要警告：++++++++++++++++++++++++++++++++++++++++++

+

+  全部路径必须相对于NDK顶级目录。例如，若是你有下面的设置：

+

+     sources/foo/Android.mk

+     sources/bar/Android.mk

+

+  在编译的时候，为了在foo/Android.mk中指定你想要添加的‘bar’源文件的路径，你应该使用：

+

+     APP_CFLAGS += -Isources/bar

+  或者：

+

+    APP_CFLAGS += -I$(LOCAL_PATH)/../bar

+  使用‘-I../bar’不能工做，由于他等价于‘-I$NDK_ROOT../bar’。

+

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

注意：在android-ndk-1.5_r1中，只能使用在c源文件上，c++不行。这个已经修正来知足整个Android编译系统的要求。

APP_CXXFLAGS

    APP_CPPFLAGS的别名，在之后的NDK发布版本中它可能会消失。

APP_CPPFLAGS

只有在编译C++源代码的时候，传递的C++编译标志的集合。

注意：在android-ndk-1.5_r1中，这个能够同时用在c和c++源代码上。这个已经修正来知足整个Android编译系统的要求。你如今可使用APP_CFLAGS标志应用在c和c++源代码上。

APP_BUILD_SCRIPT

默认状况下，NDK编译系统会查找$(APP_PROJECT_PATH)/jni目录下的Android.mk文件，例如:

       $(APP_PROJECT_PATH)/jni/Android.mk

若是你想改变这个默认行为，你能够定义APP_BUILD_SCRIPT指向一个编译脚本。一个不是绝对路径的path老是解释为相对于NDK的顶级目录。

APP_ABI

默认状况下，NDK编译系统将会生成‘armeabi’ABI的机器码。这对应使用浮点运算操做的基于ARMv5TE的CPU。你可使用APP_ABI选择一个不一样的ABI。

例如，为了支持基于ARMv7设备的硬件FPU指令，使用：

APP_ABI := armeabi-v7a

或者支持IA-32指令集，使用：

       APP_ABI := x86

或者支持MIPS指令集，使用：

       APP_ABI := mpis

或者同时支持全部指令集，使用：

       APP_ABI := armeabi armeabi-v7a x86 mpis

或更好，从NDK r7，你可使用‘all’，表示这个版本的NDK支

持的全部ABIs:

       APP_ABI := all

想要了解全部支持的ABIs和关于它们的使用和限制的细节，请阅读CPU-ARCH-ABIs相关内容。

APP_PLATFORM

目标android平台的名称。例如，‘android-3’对应Android 1.5 系统镜像。想要了解完整的平台名称和对应的Android系统镜像，请查看STABLE-APIS相关内容。

APP_STL

默认状况下，NDK编译系统提供最小的C++运行时库（/system/lib/libstdc++.so）的头文件，这个最小的运行时库是由android系统提供。

可是，NDK自带的C++实现，让你可以使用或连接到你的运用程序中。定义APP_STL为下面的一个，例如：

APP_STL := stlport_static       --> static STLport library        

APP_STL := stlport_shared      --> shared STLport library        

APP_STL := system             --> default C++ runtime library

想要了解这个主题的信息，请阅读CPLUSPLUS-SUPPORT相关内容。

APP_GNUSTL_FORC_CPP_FEATURES

在NDK以前的版本中，一个简单的事实是：运行时使用GNU libstdc++（例如，经过设置APP_STL为‘gunstl_static’或‘gunstl_shared’）会强制在全部生成的机器代码中支持异常和RTTI。这可能在特定的状况下会有问题，可是很是罕见，如，会为工程生成没必要要的很大的代码，而这些代码对于这些功能来是不须要的。

这个bug在NDK r7已经修复了，可是意味着，若是你的代码须要使用异常或RTTI，它必须显示的指出，要么在APP_CPPFLAGS，要么在你的LOCAL_CPPFLAGS / LOCAL_CPP_FEATURES定义中。

在NDK r7以及之后的版本中，为了使得对projects的接口更加简单，一种可选的方法是定义APP_GNUSTL_CPP_FEATURES来包含一个或多个下面的这些值：

    exceptions    -> to enforce exceptions support for allmodules.        

    rtti           ->to enforce rtti support for all modules.

例如，要在NDK r7中获得一样的行为：

       APP_GNUSTL_FORCE_CPP_FEATURES:= exceptions rtti

重要：在这里提供这个变量是做为一个便利的工具，使得它转向新版本的NDK更加简单。咱们鼓励全部的开发者恰当的修改module的定义，而不要依赖于它。

APP_SHORT_COMMANDS

对于整个工程来讲，这个和LOCAL_SHORT_COMMANDS是同样的。请查看Android.mk文档中的内容。

NDK_TOOLCHAIN_VERSION

定义这个变量为4.4.3或4.6来选择GCC编译器的版本。4.6是默认值。

APP_PIE

从Jelly Bean (4.1)开始，Android的动态连接器支持position-independent executables (PIE)，用-fPIE进行编译，这个标志会使得经过随机代码的位置来查找内存损坏的bug更加困难。

默认，ndk-build将自动设置这个值为‘true’，若是你的工程targets是Android-16或更高。你能够手工的设置它为‘true’或‘false’。

重要：PIE executables不能运行在Android4.1以前的版本上。

注意这个只能运用在可执行程序上。当编译动态或静态库的时候是不起做用的。

一个很是简单的Application.mk文件以下：

-------------- 分割线 -------------------------

APP_PROJECT_PATH := <pathto project>

-------------- 分割线-------------------------