關于Android import-module 和NDK_MODULE_PATH

===========================

1、將NDK代碼模塊化

2、導出1個預編譯庫

===========================

1、將NDK代碼模塊化

Android module paths (sharing code made easy):

Android模塊路徑（方便同享代碼）：

==============================================

Starting from r5, the Android NDK comes with a cool feature that allows you to share and reuse other peoples modules more easily.

從r5開始，Android NDK引入1個很酷的特性，允許你更容易地同享和重用他人的模塊。

I. Overview:

1、概述：

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

The main idea behind this feature are:

這個特性背后的主要思想：

- You can install NDK modules outside of your main project source tree.

- 你可以在你的主工程源碼樹之外安裝NDK模塊

- You can easily import them into your project with a one-line command.

- 你可以用1個單行命令簡單地“導入”它們到你的工程。

In practice, heres how this works:

實際上，這里介紹它是如何工作的：

1. Your NDK_MODULE_PATH environment variable will contain a list of search paths on your system to lookup for modules.

1. 你的NDK_MODULE_PATH環(huán)境變量將包括1個在你的系統(tǒng)上查找模塊的搜索路徑列表。

It is up to you to set the variable, and to copy other modules to the directories you listed in it.

由你來決定設置變量和復制你在其中列出的目錄下的其他模塊。

2. To import a module, place a line like the following to, preferably at the *end* of, your Android.mk:

2. 要想導入1個模塊，放置以下所示的1行指令，最好放在你的Android.mk文件結束處：

$(call import-module,)

This will look for/Android.mk under any of the directories listed in your NDK_MODULE_PATH.

這將查找在你的NDK_MODULE_PATH中列出的任意目錄下的/Android.mk

(The reason why it must be at the end is to avoid messing with the results of the my-dir function. See its description in docs/ANDROID-MK.html for details).

（它必須放在結束處的理由是為了不my-dir函數(shù)結果的干擾。詳細請參考docs/ANDROID-MK.html中的描寫）。

3. Declare that your projects modules depend on the imported one by listing them in either your LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES. For example:

3. 通過在你的LOCAL_STATIC_LIBRARIES或LOCAL_SHARED_LIBRARIES中列出它們，聲明你的工程模塊依賴于這個導入模塊。例如：

LOCAL_STATIC_LIBRARIES +=

4. Rebuild!

4. 重新構建！

Remember that NDK r5 also added the ability for a module to "export" declarations to other modules that depend on it (for example, see the definition of LOCAL_EXPORT_CFLAGS in docs/ANDROID-MK.html).

記住NDK r5還添加模塊的能力以“導出”聲明到其它依賴于它的模塊（例如，參考docs/ANDROID-MK.html中LOCAL_EXPORT_CFLAGS的定義）

A well-written module will correctly export all the things its dependees need, et voila.

1個書寫良好的模塊將正確地導出它的被依賴者所需要的所有東西，就是這模樣（注：et voila是法語）。

Now for the full details:

現(xiàn)在是完全的細節(jié)：

I. NDK_MODULE_PATH:

1、NDK_MODULE_PATH：

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

The NDK_MODULE_PATH variable must contain a list of directories.

NDK_MODULE_PATH變量必須包括1個目錄列表。

* Due to GNU Make limitations, NDK_MODULE_PATH must not contain any space. The NDK will complain if this is not the case.

* 由于GNU Make的限制，NDK_MODULE_PATH不準包括任何空格。NDK將解釋它是不是背背要求。

* Use : as the path separator.

* 使用分號作為路徑分隔符。

* On Windows, use / as the directory separator.

* 在Windows上，使用正斜杠作為目錄分隔符（注：應當是指把Windows風格的反斜杠改成正斜杠）。

The directories of NDK_MODULE_PATH will be searched in order. The first//Android.mk file that is found during the lookup will be included automatically.

NDK_MODULE_PATH的目錄將被順次搜索。第1個在查找種被找到的//Android.mk文件將自動被包括。

As a convenience, $NDK/sources is appended to your NDK_MODULE_PATH definition by the NDK build system. This allows you to easily import the helper libraries that come with it (see docs/CPU-FEATURES.html for a practical example).

作為約定，$NDK/sources被NDK構建系統(tǒng)尾加到你的NDK_MODULE_PATH定義中。這允許你簡單地導入由它生成的輔助庫（見docs/CPU-FEATURES.html中的1個實際例子）

II. Writing an import module:

2、書寫1個導入模塊：

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

Writing an import module is trivial and very similar to what you do when writing project modules:

書寫1個導入模塊是細小而且非常類似于你在書寫工程模塊時所做的東西：

1. Create a sub-directory from one of your NDK_MODULE_PATH directories.

1. 在你的NDK_MODULE_PATH目錄中的1個目錄下創(chuàng)建子目錄。

For example, if NDK_MODULE_PATH is defined to /home/user/ndk-modules, then create the directory /home/user/ndk-modules/my-module/

例如，如果NDK_MODULE_PATH被定義為/home/user/ndk-modules，那末創(chuàng)建目錄/home/user/ndk-modules/my-module/

2. Place an Android.mk and eventual source code there.

2. 在那里放置1個Android.mk和終究源碼。

Just like you would for a project module, where these files normally go to $PROJECT_PATH/Android.mk. In the example above, this would go to /home/user/ndk-modules/my-module/Android.mk

就像你對1個工程模塊那樣，這些文件通常去到$PROJECT_PATH/Android.mk中。在上面的例子中，它將集中到/home/user/ndk-modules/my-module/Android.mk

NOTE: Any Application.mk file here will be ignored.

注意：這里任何Application.mk文件將被疏忽。

3. Any module that depends on your new module, would import by calling the import-module function. For example:

3. 依賴于你的新模塊的任何模塊，將通過調用import-module函數(shù)進行導入。例如：

$(call import-module,my-first-module)

Import modules *can* import other modules, but circular dependencies are not permitted and will be detected. Dependencies are transitive and the build system will compute all the things that need to be built for you.

導入模塊可以導入其他模塊，但不允許循環(huán)依賴，它會被檢測到。依賴是及物的，構建系統(tǒng)將為你計算所有需要被構建的所有東西。

The NDK build system will not place object files or executables in your import module directory (they will all be placed under the projects build directory, e.g. $PROJECT_PATH/obj/).

NDK構建系統(tǒng)將不會在你的導入模塊目錄中放置對象文件或可履行文件（它們將全部放在工程的構建目錄下，例如$PROJECT_PATH/obj/）

You can however distribute prebuilt binaries in your import module with the new PREBUILT_STATIC_LIBRARIES or PREBUILT_SHARED_LIBRARIES feature (see docs/ANDROID-MK.html).

但是你可以通過新的PREBUILT_STATIC_LIBRARIES或PREBUILT_SHARED_LIBRARIES特性，在你的導入模塊中分發(fā)預構建2進制文件（見docs/ANDROID-MK.html）。

This makes it easy to package and redistribute your import module directory to third-parties.

這將使打包和重新分發(fā)你的導入模塊目錄到第3方變得簡單。

III. Naming an import module:

3、命名1個導入模塊：

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

It is important to understand a few things related to the naming of your import module:

重要是要理解關于你的導入模塊命名的1些事情：

- What import-module does is really search for a file named Android.mk using the list provided by NDK_MODULE_PATH, then include while performing very little bit of house-keeping.

- import-module所做的實際上是使用NDK_MODULE_PATH提供的列表搜索名為Android.mk的文件，然后當履行非常小量的內部工作時包括它。

Your imported Android.mk can define any number of modules, with any name. As a consequence, there is no direct relationship betweenin the following line:

你的導入Android.mk可以通過名稱定義任意數(shù)量的模塊。因此，在下面指令行中之間不會有直接的關聯(lián)：

$(call import-module,/)

And the names of the modules defined under//Android.mk.

和定義在//Android.mk下的模塊名稱。

IN CASE OF DOUBT, KEEP IT SIMPLE!

如果還是不明白，就讓它保持簡單！

If you only plan to provide one import module, just name it like the base import directory.

如果你只是計劃提供1個導入模塊，只要像導入基目錄那樣命名它就能夠了。

On the other hand, you may want to provide a static and a shared version of your module: use distinct names under the same top-level Android.mk. Consider the following build script:

另外一方面，你可能像提供你的模塊的靜態(tài)和動態(tài)版本：在相同的頂級Android.mk下使用不同的名稱。斟酌以下構建腳本：

$NDK_MODULE_PATH/foo/bar/Android.mk:

LOCAL_PATH := $(call my-dir)

# Static version of the library is named bar_static

# 庫的靜態(tài)版本被命名為bar_static

include $(CLEAR_VARS)

LOCAL_MODULE := bar_static

LOCAL_SRC_FILES := bar.c

# Ensure our dependees can include too

# 確保我們的被依賴者還可以包括

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)

include $(BUILD_STATIC_LIBRARY)

# Shared version of the library is named bar_shared

# 庫的動態(tài)版被命名為bar_shared

LOCAL_MODULE := bar_shared

LOCAL_SRC_FILES := bar.c

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)

include $(BUILD_SHARED_LIBRARY)

Another module would refer to it by doing the following:

另外一個模塊將通過以下方法援用它：

1. Import foo/bar, as in:

1. 導入foo/bar，像這樣：

$(call import-module,foo/bar)

2. To use the static library:

2. 要使用靜態(tài)庫：

...

LOCAL_STATIC_LIBRARIES := bar_static

3. Or to use the shared library:

3. 或要使用動態(tài)庫：

...

LOCAL_SHARED_LIBRARIES := bar_shared

- The module namespace is flat, so try to give your modules names that are likely to not collide with other. Note that your can use LOCAL_MODULE_FILENAME to give the name of your modules binary file, independently from its LOCAL_MODULE (see docs/ANDROID-MK.html for definition and usage). For example:

- 模塊的命名空間是平的，所以嘗試給你的模塊1個不可能和其它模塊名稱沖突的名字。注意你可使用LOCAL_MODULE_FILENAME設置你的模塊的2進制文件的名稱，獨立于LOCAL_MODULE（見docs/ANDROID-MK.html取得其定義和用法）。例如：

include $(CLEAR_VARS)

LOCAL_MODULE := super_foo

LOCAL_MODULE_FILENAME := foo   # will give libfoo.so # 將給定為libfoo.so

LOCAL_SRC_FILES := foo-src.c

LOCAL_CFLAGS := -DVOLUME=11

include $(BUILD_SHARED_LIBRARY)

include $(CLEAR_VARS)

LOCAL_MODULE := normal_foo

LOCAL_MODULE_FILENAME := foo   # will also give libfoo.so # 還將給定為libfoo.so

LOCAL_SRC_FILES := foo-src.c

include $(BUILD_SHARED_LIBRARY)

Defines two modules named "super_foo" and "normal_foo" which both produce a shared library named libfoo.so

定義兩個模塊，名為super_foo和normal_foo，它們都將產生1個名為libfoo.so的動態(tài)庫。

As a consequence, only one of them can be used by your project or a conflict will happen at build time. This allows you to select either the normal or optimized version in your NDK build scripts, while keeping the same simple loading instruction in your Java sources as:

因此，只有它們其中1個可以被你的工程使用或在構建期產生沖突。這允許你用你的NDK構建腳本選擇正常或優(yōu)化版本，保持在你的Java源代碼中這模樣的相同而且簡單的加載指令：

static {

System.loadLibrary("foo");

}

IV. Tips & Recommendations:

4、提示和建議：

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

* You dont need to import a module before you can reference it!

* 你不需要在你可以援用它前導入模塊！

* Use import-module at the *end* of your Android.mk to avoid messing with the result of my-dir. See the description of this function in docs/ANDROID-MK.html to understand why.

* 在你的Android.mk結束處使用import-module以免my-dir結果的干擾。參考docs/ANDROID-MK.html中這個函數(shù)的描寫以理解為何。

* It is *strongly* suggested to use a subdirectory for your import tags, that describes its origin, as in:

* 強烈建議對你的導入標簽使用子目錄，以描寫它的來源，像這模樣：

$(call import-module,gtk/glib)

or something like:

或類似這樣：

$(call import-module,com.example/awesomelib)

IMPORTANT: THE android IMPORT DIRECTORY, AND ANY OF ITS SUB-DIRECTORIES IS *RESERVED* FOR NDK USAGE. FEEL FREE TO ORGANIZE YOUR OTHER IMPORT MODULES AS YOU WANT OTHERWISE.

重要：“android”導入目錄，和它的任意子目錄由于NDK的使用而保存。但是歡迎你依照自己的意愿組織其它導入模塊。

2、導出1個預編譯庫

NDK Prebuilt library support:

NDK 預構建庫支持：

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

Android NDK r5 introduced support for prebuilt libraries (shared and static), i.e. the ability to include and use, in your applications, prebuilt version of libraries.

Android NDK r5引入預構建庫（動態(tài)和靜態(tài)）的支持，即在你的利用程序中包括和使用庫的預構建版本。

This feature can be useful for two things:

這個特性可能在兩方面有用：

1/ You want to distribute your own libraries to third-party NDK developers without distributing your sources.

1、你想發(fā)布你自己的庫給第3方NDK開發(fā)者而不分發(fā)你的源代碼。

2/ You want to use a prebuilt version of your own libraries to speed up your build.

2、你想使用你自己的庫的預構建版本以加速你的構建。

This document explains how this support works.

這個文檔解釋這類支持是如何工作的。

I. Declaring a prebuilt library module:

1、聲明1個預構建庫模塊：

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

Each prebuilt library must be declared as a *single* independent module to the build system. Here is a trivial example where we assume that the file "libfoo.so" is located in the same directory than the Android.mk below:

每一個預構建庫必須向構建系統(tǒng)聲明為1個單1獨立模塊。這里有個小示例，我們假定文件libfoo.so位于以下Android.mk相同的目錄中。

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE := foo-prebuilt

LOCAL_SRC_FILES := libfoo.so

include $(PREBUILT_SHARED_LIBRARY)

Notice that, to declare such a module, you really only need the following:

注意，要聲明這個模塊，你實際上只需要以下東西：

1. Give the module a name (here foo-prebuilt). This does not need to correspond to the name of the prebuilt library itself.

1. 給模塊1個名稱（這里是foo-prebuilt）。不需要對應預構建庫本身的名稱。

2. Assign to LOCAL_SRC_FILES the path to the prebuilt library you are providing. As usual, the path is relative to your LOCAL_PATH.

2. 把你提供的預構建庫的路徑賦給LOCAL_SRC_FILES。通常路徑相對你的LOCAL_PATH

IMPORTANT: You *must* ensure that the prebuilt library corresponds to the target ABI you are using. More on this later.

重要：你必須確保預構建庫對應你正在使用的目標ABI（注：利用程序2進制接口，即操作系統(tǒng)開放給利用程序的接口）。更多相干信息見后。

3. Include PREBUILT_SHARED_LIBRARY, instead of BUILD_SHARED_LIBRARY, if you are providing a shared, library. For static ones, use PREBUILT_STATIC_LIBRARY.

3. 包括PREBUILT_SHARED_LIBRARY，而非BUILD_SHARED_LIBRARY，如果你提供的是1個動態(tài)庫。對靜態(tài)庫，請使用PREBUILT_STATIC_LIBRARY

A prebuilt module does not build anything. However, a copy of your prebuilt shared library will be copied into $PROJECT/obj/local, and another will be copied and stripped into $PROJECT/libs/.

1個預構建模塊不編譯任何東西。但是，你的預構建動態(tài)庫的副本將被復制到$PROJECT/obj/local，而另外一個副本將被復制并裁剪進$PROJECT/libs/。

II. Referencing the prebuilt library in other modules:

2、援用其它模塊的預構建庫：

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

Simply list your prebuilt modules name in the LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES declaration in the Android.mk of any module that depends on them.

在依賴于你的構建模塊的所有模塊的Android.mk的LOCAL_STATIC_LIBRARIES或LOCAL_SHARED_LIBRARIES的聲明中簡單列出這些預構建模塊的名稱。

For example, a naive example of a module using libfoo.so would be:

例如，1個使用libfoo.so的模塊的單純例子將是：

include $(CLEAR_VARS)

LOCAL_MODULE := foo-user

LOCAL_SRC_FILES := foo-user.c

LOCAL_SHARED_LIBRARY := foo-prebuilt

include $(BUILD_SHARED_LIBRARY)

III. Exporting headers for prebuilt libraries:

3、導出預構建庫的頭文件：

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

The example above was called naive because, in practice, the code in foo-user.c is going to depend on specific declarations that are normally found in a header file distributed with the prebuilt library (e.g. "foo.h").

上面的例子被稱為“單純”是由于，實際上，foo-user.c的代碼將依賴于特定的聲明，那些聲明通常在預構建庫分發(fā)的頭文件中找到（例如，foo.h）

In other words, foo-user.c is going to have a line like:

換句話說，foo-user.c將有類似的1行：

#include

And you need to provide the header and its include path to the compiler when building the foo-user module.

而你需要在構建foo-user模塊時提供頭文件和它的編譯器包括目錄。

A simple way to deal with that is to use exports in the prebuilt module definition. For example, assuming that a file "foo.h" is located under the include directory relative to the prebuilt module, we can write:

1個簡單處理方法是在預構建模塊定義中使用導出。例如，假定1個foo.h文件位于相對預構建模塊的include目錄下，我們可以這樣寫：

include $(CLEAR_VARS)

LOCAL_MODULE := foo-prebuilt

LOCAL_SRC_FILES := libfoo.so

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include

include $(PREBUILT_SHARED_LIBRARY)

The LOCAL_EXPORT_C_INCLUDES definition here ensures that any module that depends on the prebuilt one will have its LOCAL_C_INCLUDES automatically prepended with the path to the prebuilts include directory, and will thus be able to find headers inside that.

這里LOCAL_EXPORT_C_INCLUDES的定義確保任何依賴于預構建模塊的模塊將自動具有帶預構建庫包括目錄為前置值的LOCAL_C_INCLUDES，而它將能夠找到包括其中的頭文件。

IV. Debugging prebuilt binaries:

4、調試預構建2進制文件：

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

We recommend you to provide prebuilt shared libraries that contain debug symbols. The version that is installed into $PROJECT/libs// is always stripped by the NDK build system, but the debug version will be used for debugging purposes with ndk-gdb.

我們建議你提供包括調試符號的預構建同享庫。安裝進$PROJECT/libs//的版本常常是被NDK構建系統(tǒng)裁剪過（注：ndk提供的工具鏈中包括了strip工具，它應當是用來優(yōu)化生成文件的大小），但調試版本將可以供ndk-gdb使用以到達調試目的。

V. ABI Selection of prebuilt binaries:

5、預構建2進制文件的ABI選擇：

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

As said previously, it is crucial to provide a prebuilt shared library that is compatible with the targetted ABI during the build. To do that, check for the value of TARGET_ARCH_ABI, its value will be:

正如前面所說，關鍵問題是在構建期間提供1個兼容于目標ABI的預構建動態(tài)庫（注：開源是好事啊）。為了做到那點，檢查TARGET_ARCH_ABI的值，它的值將是：

armeabi     => when targetting ARMv5TE or higher CPUs

armeabi     => 目標為ARMv5TE或更高的CPU

armeabi-v7a => when targetting ARMv7 or higher CPUs

armeabi-v7a => 目標為ARMv7或更高的CPU

x86         => when targetting x86 CPUs

x86         => 目標為x86 CPU。

Note that armeabi-v7a systems can run armeabi binaries just fine.

注意armeabi-v7a系統(tǒng)可以很好地運行armeabi的2進制文件。

Heres an example where we provide two versions of a prebuilt library and select which one to copy based on the target ABI:

這里有1個例子，我們提供兩個版本的預構建庫并且基于目標ABI選擇哪個版本去復制。

include $(CLEAR_VARS)

LOCAL_MODULE := foo-prebuilt

LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libfoo.so

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include

include $(PREBUILT_SHARED_LIBRARY)

Here. we assume that the prebuilt libraries to copy are under the following directory hierarchy:

這里。我們假定要復制的預構建庫位于以下目錄層次：

Android.mk            --> the file above

Android.mk            --> 上面的文件

armeabi/libfoo.so     --> the armeabi prebuilt shared library

armeabi/libfoo.so     --> armeabi預構建動態(tài)庫

armeabi-v7a/libfoo.so --> the armeabi-v7a prebuilt shared library

armeabi-v7a/libfoo.so --> armeabi-v7a預構建動態(tài)庫

include/foo.h         --> the exported header file

include/foo.h         --> 導出的頭文件

NOTE: Remember that you dont need to provide an armeabi-v7a prebuilt library, since an armeabi one can easily run on the corresponding devices.

注意：記住你不需要提供1個armeabi-v7a預構建庫，由于armeabi版本可以更容易地運行在相應的裝備上。