<html><body><pre>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.
IMPORTANT:<font color=red>（重要提示）</font>
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.
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.
<font color=red>在1.5以上版本才能使用NDK；</font>
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:
- 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.:
<font color=red>1>首先是声明一个native方法，如下</font>
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:
<font color=red>2>应用中包含一个本地共享库</font>
libFileLoader.so
- Your application must explicitly load the library. For example, to load
it at application startup, simply add the following to its source code:
<font color=red>3>加载库</font>
static {
System.loadLibrary("FileLoader");
}
<font color=red>注意：前缀lib和后缀.so是要去掉的</font>
Note that you should not use the 'lib' prefix and '.so' suffix here.
The Android NDK is a complement to the Android SDK that helps you to:
<font color=red>NDK能帮助你做如下事情：</font>
<font color=red>1.生成的JNI兼容共享库能在1.5以上版本运行</font>
- Generate JNI-compatible shared libraries that can run on the Android
1.5 platform (and later) running on ARM CPUs.
<font color=red>2.把生成的动态库拷到你的项目中，它会自动添加到你的APK中</font>
- 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
<font color=red>3.在以后的NDK版本中，我们会提供一些通过一个远程的gdb连接来
帮助你调试你本地代码的工具</font>
- 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.
Moreover, the Android NDK provides:
<font color=red>一系列的交叉集工具能够在Linux,OS X 和Window（Cygwin工具）下生成原生的ARM二进制文件</font>
- A set of cross-toolchains (compilers, linkers, etc..) that can
generate native ARM binaries on Linux, OS X and Windows (with Cygwin)
<font color=red>一系列系统头文件对应于Android平台提供的稳定原生APIs列表，这些
对应的声明保证了以后版本对这些头文件的支持</font>
- 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.
<font color=red>详细说明请看这个文件<a href="./STABLE-APIS.html">STABLE-APIS.html</a></font>
They are documented in the file docs/STABLE-APIS.html
IMPORTANT:<font color=red>注意：</font>
<font color=red>请时刻记住，大多数原生系统库在Android镜像文件中是不固定的可能会大幅改变，
甚至会被删除</font>
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.
<font color=red>编译系统允许开发者只编写非常短的脚本文件用来描述哪些资源用怎样的方式进行编译，
编译系统能够非常专业的处理所有的工具集、平台、CPU、ABI。另外，...........</font>
- 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).
II. Android NDK Non-Goals:<font color=red>NDK不能做的事情</font>
--------------------------
<font color=red>编写运行在android设备中的通用本地code使用NDK并不是一个好的方法，你的应用程序
应该使用java编程语言来处理android系统事件，以避免ANR提示或是处理android程序生命周期</font>
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.
<font color=red>尽管如此，还是能够使用本地代码编写一个复杂的应用程序的</font>
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.
<font color=red>要使用NDK，建议先好好理解下JNI ,因为该环境下的很多操作需要开发者们去专门的实现，
而这些都不是一些普通的原生代码（实现起来很麻烦），他们包括：</font>
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:
<font color=red>不能通过直接的本地指针直接访问虚拟机中的内容，例如，你不能安全地得到一个指针指向
String对象的16位char数组然后对它进行迭代循环</font>
- 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.
<font color=red>当本地code要保持JNI调用中的VM对象线程时需要很好的内存管理</font>
- Requiring explicit reference management when the native code wants to
keep handles to VM objects between JNI calls.
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.
<font color=red>如果android系统库没有明确的支持NDK头文件，那么应用软件就不应该依赖它并使用它，否则的
话，在各种设备升级中就会出现风险</font>
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.
<font color=red>选好系统库确保他们在stable NDK APIs中.</font>
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:
<font color=red>1》在工程目录下新建jni文件夹</font>
1/ Place your native sources under $PROJECT/jni/...
<font color=red>2》在jni下创建Android.mk文件</font>
2/ Write $PROJECT/jni/Android.mk to describe your sources
to the NDK build system
<font color=red>3》在JNI下创建Application.mk文件，详细说明见<a href="./APPLICATION-MK.html">APPLICATION-MK.html</a></font>
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).
<font color=red>4》运行如下命令$NDK/ndk-build 来编译你的code</font>
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:
- - - - - - - - - - - - - -
<font color=red>r4以前的版本要求运行build/host-setup.sh命令来配置NDK环境，这一步在r4版本之后就完全移除了</font>
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).
III.2/ Placing C and C++ sources:
- - - - - - - - - - - - - - - - -
Place your native sources under the following directory:
$PROJECT/jni/ <font color=red>把你的code放在$PROJECT/jni/目录下</font>
Where $PROJECT corresponds to the path of your Android application
project. <font color=red>这里的$PROJECT是你android项目所在的目录</font>
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.
<font color=red>注意，C和C++是都支持的，默认的C++文件扩展名为.cpp,其他的扩展名也能够被处理（C++文件扩展名可以不为.CPP
NDK也能识别？？？）详细说明见文件<a href="./ANDROID-MK.html">ANDROID-MK.html</a></font>
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).
<font color=red>通过调整Android.mk 文件创建不同的目录来存放你的源文件是可能的</font>
It is possible to store your sources in a different location by adjusting
your Android.mk file (see below).
III.3/ Writing an Android.mk build script:<font color=red>编译脚本：Android.mk的编写</font>
- - - - - - - - - - - - - - - - - - - - - -
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.<font color=red>Android.mk的详细语法在<a href="./ANDROID-MK.html">ANDROID-MK.html</a>中</font>
In a nutshell, the NDK groups your sources into "modules", where each module
can be one of the following:
<font color=red>总而言之，NDK把你的源码编译成一个个模块，每一个模块都为下面的某一种：</font>
- a static library
- a shared library
<font color=red>你可以在一个Android.mk文件中定义多个模块，或者你也可以写几个Android.mk文件，每个文件只定义一个模块</font>
You can define several modules in a single Android.mk, or you can write
several Android.mk files, each one defining a single module.
<font color=red>注意：一个Android.mk可能会被解析多次，所以不要以为某些变量没有定义在他们里面（不解？？？）
默认下NDK会寻找这个编译脚本$PROJECT/jni/Android.mk</font>
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:
$PROJECT/jni/Android.mk
<font color=red>如果你想在子目录下定义Android.mk文件，那你应该在顶级目录下的Android.mk文件中明确的引入他们，
以下是一个很有用的方法：在顶级目录的Android.mk文件中写入include $(call all-subdir-makefiles)</font>
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:
include $(call all-subdir-makefiles)
This will include all Android.mk files in sub-directories of the current
build file's path.
<font color=red>编写Application.mk文件（可选）</font>
III.4/ Writing an Application.mk build file (optional):
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
<font color=red>尽管Android.mk文件描述了你的模块，Application.mk文件描述了你的真个应用，看看说明文件
<a href="./APPLICATION-MK.html">APPLICATION-MK.html</a>,你就会理解这个文件允许你做什么，主要包括：</font>
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:
<font color=red>你的程序需要的所有模块列表</font>
- The exact list of modules required by your application.
<font color=red>为指定的CPU结构生成机器码</font>
- 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.
<font color=red>该文件时可选添加的，默认NDK会提供一个Application.mk，它编译Android.mk中所有的模块，适用于默认的CPU ABI(armeabi)
ABI是什么？请看这里：<a href="http://baike.baidu.com/view/1433570.htm#sub6276632" >ABI解释</a></font>
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).
<font color=red>两种方式使用Application.mk:</font>
There are two ways to use an Application.mk:
<font color=red>放置目录$PROJECT/jni/Application.mk，ndk-build命令会自动搜索该脚本</font>
- Place it under $PROJECT/jni/Application.mk, and it will be picked
up automatically by the 'ndk-build' script (more on this later)
<font color=red>放置目录$NDK/apps/<name>/Application.mk,然后在（window下为cygwin中）执行如下命令make APP=<name>
这种方式在R4版本之前使用，在现在版本中依旧能用，但是我们强烈建议使用第一种方式，因为更简单便捷</font>
- 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.
<font color=red>为获取完整的信息，再次请看这里：<a href="./APPLICATION-MK.html">APPLICATION-MK.html</a></font>
Again, see docs/APPLICATION-MK.html for a complete description of its
content.
<font color=red><h2>如何编译</h2></font>
III.5/ Invoke the NDK build system:
- - - - - - - - - - - - - - - - - -
<font color=red>直接使用ndk-build命令编译就可以了</font>
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.
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:
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.
For example:
<font color=red></font>
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.
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.
2: Using the $NDK/apps/<name>/Application.mk:
---------------------------------------------
This build method was the only one before Android NDK r4 and is only
supported for compatibility reason. We strongly recommend you to migrate
to using the 'ndk-build' command as soon as possible, since we may remove
legacy support in a later NDK release.
It requires the following:
1. Creating a sub-directory named $NDK/apps/<name>/ under
your NDK installation directory (not your project path).
Where <name> is an arbitrary name to describe your application
to the NDK build system (no spaces allowed).
2. Write $NDK/apps/<name>/Application.mk, which then requires
a definition for APP_PROJECT_PATH that points to your
application project directory.
3. Go to the NDK installation path on the command line then
invoke the top-level GNUMakefile, as in:
cd $NDK
make APP=<name>
The result will be equivalent to the first method, except for the fact
that intermediate generated files will be placed under $NDK/out/apps/<name>/
<font color=red><h2>如何重新编译</h2></font>
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.
<font color=red>使用ant命令或是ADT插件，详细请查看SDK文档，新的APK文件会嵌入到你的共享库，在
安装的时候这些库文件会自动被提取</font>
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.
<font color=red><h2>调试</h2></font>
V. Debugging support:
- - - - - - - - - - -
<font color=red>NDK提供了一个帮助脚本名为ndk-gdb能很容易的启动native调试</font>
The NDK provides a helper script, named 'ndk-gdb' to very easily launch
a native debugging session of your applications.
<font color=red>native调试只能在2.2以上版本进行，并且不需要访问root权限</font>
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.
<font color=red>更多内容，请看这里<a href="./NDK-GDB.html">NDK-GDB.html</a></font>
For more information, read docs/NDK-GDB.html. In a nutshell, native debugging
follows this simple scheme:
<font color=red>确保你的程序可调试：在androidManifest.xml中加入android:debuggable="true"</font>
1. Ensure your application is debuggable (e.g. set android:debuggable
to "true" in your AndroidManifest.xml)
<font color=red>在模拟器或真机上装上APK</font>
2. Build your application with 'ndk-build', then install it on your
device/emulator.
<font color=red>启动</font>
3. Launch your application.
<font color=red>在你的应用程序目录下运行命令：ndk-gdb</font>
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.
</pre></body></html>