NDK_OVERVIEW翻譯

 

Android NDK Overview

Introduction:

The Android NDK is a set of tools that allows Android application developers
to embed native machine code compiled from C and/or C++ source files into
their application packages.

NDK爲程序員提供了一套工具集，幫助程序員將從C/C++源碼編譯出的庫內嵌到安卓應用包中。
IMPORTANT:
  The Android NDK can only be used to target Android system images
  running Cupcake (a.k.a 1.5) or later versions of the platform.

NDK只能被用於1.5版本的安卓系統中。
  1.0 and 1.1 system images are specifically *not* supported due to
  subtle ABI and toolchain changes that happened for the 1.5 release.

因爲從1.5開始，ABI和toolchain有了輕微的改變，所以不能用於1.0和1.1版本的平臺。
I. Android NDK Goals:
---------------------

The Android VM allows your application's source code to call methods
implemented in native code through the JNI. In a nutshell, this means that:

安卓虛擬機容許應用源碼經過jni調用本地代碼的方法。這意味着：
  - Your application's source code will declare one or more methods
    with the 'native' keyword to indicate that they are implemented through
    native code. E.g.:

- 應用源碼需經過native關鍵字來聲明一個或者多個本地方法。好比
      native byte[]  loadFile(String  filePath);

  - You must provide a native shared library that contains the
    implementation of these methods, which will be packaged into your
    application's .apk. This library must be named according to standard
    Unix conventions as lib<something>.so, and shall contain a standard JNI
    entry point (more on this later). For example:

- 程序員必須提供一個共享庫，庫中包含着本地方法的實現，這個庫會最終打包到應用的apk包中。庫名必須遵照unix的傳統命名規範，如libname.so，並且庫還要
包含一個標準的jni入口。好比：
      libFileLoader.so

  - Your application must explicitly load the library. For example, to load
    it at application start-up, simply add the following to its source code:

- 應用顯示加載庫。例如，在應用啓動時加載庫，只需按照如下的方法便可：
      static {
        System.loadLibrary("FileLoader");
      }

    Note that you should not use the 'lib' prefix and '.so' suffix here.

記住，代碼中顯示加載庫時，不能寫上lib前綴以及so後綴。

The Android NDK is a complement to the Android SDK that helps you to:
NDK是SDK的補充，NDK能夠幫助程序員：

  - Generate JNI-compatible shared libraries that can run on the Android
    1.5 platform (and later) running on ARM CPUs.

- 產生於jni兼容的共享庫，這個庫可以運行在1.5以後的版本平臺上。固然，平臺是要運行在ARM CPU上。
  - Copy the generated shared libraries to a proper location of your
    application project path, so they will be automatically added to your
    final (and signed) .apks

- 將產生的共享庫複製到應用項目合適的路徑，這樣這些庫將會會自動地添加到apk中。
  - In later revisions of the NDK, we intend to provide tools that help
    debug your native code through a remote gdb connection and as much
    source/symbol information as possible.

- 在NDK後續版本中，谷歌官方將會提供工具，來幫助程序員經過遠程gdb來調試本地代碼。
Moreover, the Android NDK provides:

更多的，NDK還提供了：
  - A set of cross-toolchains (compilers, linkers, etc..) that can
    generate native ARM binaries on Linux, OS X and Windows (with Cygwin)

- 一套跨平臺的工具集cross-toolchains，包括編譯器，連接器等，這些工具將會在Linux，OS X以及cygwin上產生可以在ARM架構上運行的程序。
  - A set of system headers corresponding to the list of stable native APIs
    supported by the Android platform. This corresponds to definitions that
    are guaranteed to be supported in all later releases of the platform.

- 一套系統頭文件，這些頭文件對應着安卓平臺支持的本地API。這些頭文件在後續的安卓平臺版本中都會被支持。
    They are documented in the file docs/STABLE-APIS.html

這些系統頭文件更多信息能夠查閱docs/STABLE-APIS.html
    IMPORTANT:
    Keep in mind that most of the native system libraries in Android system
    images are not frozen and might changed drastically, or even deleted,
    in later updates and releases of the platform.

記住，本地系統庫將會在後續平臺版本中被修改。即，系統頭文件會被後續安卓平臺支持，可是實現庫會改變。
  - A build system that allow developers to only write very short build files
    to describe which sources need to be compiled, and how. The build system
    deals with all the hairy toolchain/platform/CPU/ABI specifics. Moreover,
    later updates of the NDK can add support for more toolchains, platforms,
    system interfaces without requiring changes in the developer's build
    files (more on this later).

- 一個編譯系統，容許程序員只需寫出很短的編譯文件，其中指明哪些源碼須要編譯以及如何編譯便可。編譯系統會自動完成不少事情。並且，後續的NDK版本會加入更多的工具集，平臺
等，而不須要程序員去修改編譯文件。

II. Android NDK Non-Goals:
--------------------------

The NDK is *not* a good way to write generic native code that runs on Android
devices. In particular, your applications should still be written in the Java
programming language, handle Android system events appropriately to avoid the
"Application Not Responding" dialog or deal with the Android application
life-cycle.

NDK可不是寫本地代碼，而後它運行在設備上的好方法。也就是，應用仍是儘可能使用java語言編寫，應用也要合理的處理系統事件，避免出現ANR，應用還要合理的處理安卓應用生命週期。
Note however that is is possible to write a sophisticated application in
native code with a small "application wrapper" used to start/stop it
appropriately.

記住，用本地代碼編寫複雜的應用，而後再用application wrapper包裝？

A good understanding of JNI is highly recommended, since many operations
in this environment require specific actions from the developers, that are
not necessarily common in typical native code. These include:

建議先了解下jni，有一些事情須要注意，包括：
  - Not being able to directly access the content of VM objects through
    direct native pointers. E.g. you cannot safely get a pointer to a
    String object's 16-bit char array to iterate over it in a loop.

- 不要經過本地指針去直接訪問虛擬機對象的內容。好比，你獲取了一個指針，用它指向一個字符串數組對象，再遍歷它，這是不安全的。
  - Requiring explicit reference management when the native code wants to
    keep handles to VM objects between JNI calls.

- 當本地代碼須要在jni調用中保持對虛擬機對象的引用，須要顯示的引用管理。

The NDK only provides system headers for a very limited set of native
APIs and libraries supported by the Android platform. While a typical
Android system image includes many native shared libraries, these should
be considered an implementation detail that might change drastically between
updates and releases of the platform.

NDK提供的系統頭文件，是針對於安卓平臺頗有限的本地API和庫。當一個典型的安卓系統包括不少的共享庫，應當注意，在後續平臺的更新中，這些庫的實現也會可能改變。
If an Android system library is not explicitly supported by the NDK
headers, then applications should not depend on it being available, or
they risk breaking after the next over-the-air system update on various
devices.

Selected system libraries will gradually be added to the set of stable NDK
APIs.

未翻譯。

III. NDK development in practice:
---------------------------------

Here's a very rough overview of how you can develop native code with the
Android NDK:

這部分展現瞭如何經過NDK開發本地代碼。
  1/ Place your native sources under $PROJECT/jni/...

  2/ Write $PROJECT/jni/Android.mk to describe your sources
     to the NDK build system

  3/ Optional: write $PROJECT/jni/Application.mk to describe your
     project in more details to the build system. You don't need
     one to get started though, but this allows you to target
     more than one CPU or override compiler/linker flags
     (see docs/APPLICATION-MK.html for all details).

  4/ Build your native code by running "$NDK/ndk-build" from your
     project directory, or any of its sub-directories.

The last step will copy, in case of success, the stripped shared libraries
your application needs to your application's root project directory. You
will then need to generate your final .apk through the usual means.
未翻譯
Now, for a few more details:


III.1/ Configuring the NDK:
- - - - - - - - - - - - - -

Previous releases required that you run the 'build/host-setup.sh'
script to configure your NDK. This step has been removed completely
in release 4 (a.k.a. NDK r4).

以前的版本須要程序員運行'build/host-setup.sh'腳本，在版本4中已經被徹底刪除了。
III.2/ Placing C and C++ sources:
- - - - - - - - - - - - - - - - -

Place your native sources under the following directory:

    $PROJECT/jni/

Where $PROJECT corresponds to the path of your Android application
project.

You are pretty free to organize the content of 'jni' as you want,
the directory names and structure here will not influence the final
generated application packages, so you don't have to use pseudo-unique
names like com.<mycompany>.<myproject> as is the case for application
package names.

Note that C and C++ sources are supported. The default C++ file extensions
supported by the NDK is '.cpp', but other extensions can be handled as well
(see docs/ANDROID-MK.html for details).

NDK支持的C++的後綴名是cpp，可是其餘的後綴名也能支持。
It is possible to store your sources in a different location by adjusting
your Android.mk file (see below).

C/C++源碼也能夠放在其餘的地方，不過要在android.mk中註明。

III.3/ Writing an Android.mk build script:
- - - - - - - - - - - - - - - - - - - - - -

An Android.mk file is a small build script that you write to describe your
sources to the NDK build system. Its syntax is described in details in
the file docs/ANDROID-MK.html.

一個Android.mk是一個編譯腳本，在這裏程序員能夠編寫編譯選項。語法能夠參考相關文檔。
In a nutshell, the NDK groups your sources into "modules", where each module
can be one of the following:

在shell中，NDK將源碼組成一個模塊，每個模塊能夠是如下兩種中的一種：
  - a static library
  - a shared library

You can define several modules in a single Android.mk, or you can write
several Android.mk files, each one defining a single module.

能夠再Android.mk中定義幾個模塊，或者編寫幾個Android.mk，每個定義一個單獨的模塊。
Note that a single Android.mk might be parsed several times by the build
system so don't assume that certain variables are not defined in them.
By default, the NDK will look for the following build script:

記住，一個單獨的Android.mk可能會被編譯系統解析N次。默認狀況下，編譯系統會查找如下編譯腳本：
   $PROJECT/jni/Android.mk

If you want to define Android.mk files in sub-directories, you should
include them explicitly in your top-level Android.mk. There is even
a helper function to do that, i.e. use:

若是想要在子目錄中定義Android.mk，那麼在頂級目錄的Android.mk中須要顯示的聲明他們。這個還能夠經過一個幫助功能來作到，好比：
   include $(call all-subdir-makefiles)

This will include all Android.mk files in sub-directories of the current
build file's path.

這個就包括了當前編譯路徑的全部子路徑的全部Android.mk文件。

III.4/ Writing an Application.mk build file (optional):
- - - - - - - - - - - - - - - - - - - - - - - - - - - -

While an Android.mk file describes your modules to the build system, the
Application.mk file describes your application itself. See the
docs/APPLICATION-MK.html document to understand what this file allows you
to do. This includes, among others:

   - The exact list of modules required by your application.

   - The CPU architecture(s) to generate machine code for.

  - Optional information, like whether you want a release or debug
    build, specific C or C++ compiler flags and others that should
    apply to all modules being built.

This file is optional: by default the NDK will provide one that simply
builds *all* the modules listed from your Android.mk (and all the makefiles
it includes) and target the default CPU ABI (armeabi).

There are two ways to use an Application.mk:

  - Place it under $PROJECT/jni/Application.mk, and it will be picked
    up automatically by the 'ndk-build' script (more on this later)

  - Place it under $NDK/apps/<name>/Application.mk, where $NDK
    points to your NDK installation path. After that, launch
    "make APP=<name>" from the NDK directory.

    This was the way this file was used before Android NDK r4.
    It is still supported for compatibility reasons, but we strongly
    encourage you to use the first method instead, since it is much
    simpler and doesn't need modifying / changing directories of the
    NDK installation tree.

Again, see docs/APPLICATION-MK.html for a complete description of its
content.

未翻譯
III.5/ Invoke the NDK build system:
- - - - - - - - - - - - - - - - - -

The preferred way to build machine code with the NDK is to use the
'ndk-build' script introduced with Android NDK r4. You can also use
a second, legacy, method that depends on creating a '$NDK/apps' subdirectory.

一種編譯本地代碼的建議方法是調用'ndk-build腳本。
In both cases, a successful build will copy the final stripped binary modules
(i.e. shared libraries) required by your application to your application's
project path (Note that unstripped versions are kept for debugging
purposes, there is no need to copy unstripped binaries to a device).

編譯成功後，會將生成的庫放到項目中合適的位置。
  1: Using the 'ndk-build' command:
  ---------------------------------

  The 'ndk-build' script, located at the top of the NDK installation path
  can be invoked directly from your application project directory (i.e. the
  one where your AndroidManifest.xml is located) or any of its sub-directories.
  For example:
'ndk-build'能夠在項目路徑中調用，也能夠在項目路徑的子路徑中調用。

    cd $PROJECT
    $NDK/ndk-build

  This will launch the NDK build scripts, which will automatically probe your
  development system and application project file to determine what to build.

'ndk-build'腳本會自動探測開發系統和應用項目文件，已決定什麼東西須要編譯。
  For example:

    ndk-build
    ndk-build  clean    --> clean generated binaries
    ndk-build  -B V=1   --> force complete rebuild, showing commands

  By default, it expects an optional file under $PROJECT/jni/Application.mk,
  and a required $PROJECT/jni/Android.mk.
默認地，'ndk-build'會期待在jni目錄下有一個可選的Application.mk以及一個必須的Android.mk文件。
  On success, this will copy the generated binary modules (i.e. shared
  libraries) to the appropriate location in your project tree. You can later
  rebuild the full Android application package either through the usual
  'ant' command, or the ADT Eclipse plug-in.

  See docs/NDK-BUILD.html for a more complete description of what this script
  does and which options it can take.


III.6/ Specifying custom output directories:
- - - - - - - - - - - - - - - - - - - - - - -

By default, ndk-build places all intermediate generated files under
$PROJECT/obj. You can however select a different location by defining
the NDK_OUT environment variable to point to a different directory.

When defined, this variable has two effects:

  1/ It ensures that all files that normally go under $PROJECT/obj are
     stored in $NDK_OUT instead

  2/ It tells ndk-gdb to look into $NDK_OUT, instead of $PROJECT/obj for
     any symbolized (i.e. unstripped) versions of the generated binaries.


IV. Rebuild your application package:
- - - - - - - - - - - - - - - - - - -

After generating the binaries with the NDK, you need to rebuild your
Android application package files (.apk) using the normal means, i.e.
either using the 'ant' command or the ADT Eclipse plug-in.

See the Android SDK documentation for more details. The new .apk will
embed your shared libraries, and they will be extracted automatically
at installation time by the system when you install the package on a
target device.


V. Debugging support:
- - - - - - - - - - -

The NDK provides a helper script, named 'ndk-gdb' to very easily launch
a native debugging session of your applications.

Native debugging can *ONLY* be performed on production devices running
Android 2.2 or higher, and does not require root or privileged access, as
long as your application is debuggable.

For more information, read docs/NDK-GDB.html. In a nutshell, native debugging
follows this simple scheme:

   1. Ensure your application is debuggable (e.g. set android:debuggable
      to "true" in your AndroidManifest.xml)

   2. Build your application with 'ndk-build', then install it on your
      device/emulator.

   3. Launch your application.

   4. Run 'ndk-gdb' from your application project directory.

You will get a gdb prompt. See the GDB User Manual for a list of useful
commands.