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>

-------------- 分割線-------------------------