1<html><body><pre>Android NDK Overview
2
3Introduction:
4
5The Android NDK is a set of tools that allows Android application developers
6to embed native machine code compiled from C and/or C++ source files into
7their application packages.
8
9IMPORTANT:
10  The Android NDK can only be used to target Android system images
11  running Cupcake (a.k.a 1.5) or later versions of the platform.
12
13  1.0 and 1.1 system images are specifically *not* supported due to
14  subtle ABI and toolchain changes that happened for the 1.5 release.
15
16
17I. Android NDK Goals:
18---------------------
19
20The Android VM allows your application's source code to call methods
21implemented in native code through the JNI. In a nutshell, this means that:
22
23  - Your application's source code will declare one or more methods
24    with the 'native' keyword to indicate that they are implemented through
25    native code. E.g.:
26
27      native byte[]  loadFile(String  filePath);
28
29  - You must provide a native shared library that contains the
30    implementation of these methods, which will be packaged into your
31    application's .apk. This library must be named according to standard
32    Unix conventions as lib&lt;something&gt;.so, and shall contain a standard JNI
33    entry point (more on this later). For example:
34
35      libFileLoader.so
36
37  - Your application must explicitly load the library. For example, to load
38    it at application start-up, simply add the following to its source code:
39
40      static {
41        System.loadLibrary("FileLoader");
42      }
43
44    Note that you should not use the 'lib' prefix and '.so' suffix here.
45
46
47The Android NDK is a complement to the Android SDK that helps you to:
48
49  - Generate JNI-compatible shared libraries that can run on the Android
50    1.5 platform (and later) running on ARM CPUs.
51
52  - Copy the generated shared libraries to a proper location of your
53    application project path, so they will be automatically added to your
54    final (and signed) .apks
55
56  - In later revisions of the NDK, we intend to provide tools that help
57    debug your native code through a remote gdb connection and as much
58    source/symbol information as possible.
59
60Moreover, the Android NDK provides:
61
62  - A set of cross-toolchains (compilers, linkers, etc..) that can
63    generate native ARM binaries on Linux, OS X and Windows (with Cygwin)
64
65  - A set of system headers corresponding to the list of stable native APIs
66    supported by the Android platform. This corresponds to definitions that
67    are guaranteed to be supported in all later releases of the platform.
68
69    They are documented in the file docs/STABLE-APIS.html
70
71    IMPORTANT:
72    Keep in mind that most of the native system libraries in Android system
73    images are not frozen and might changed drastically, or even deleted,
74    in later updates and releases of the platform.
75
76  - A build system that allow developers to only write very short build files
77    to describe which sources need to be compiled, and how. The build system
78    deals with all the hairy toolchain/platform/CPU/ABI specifics. Moreover,
79    later updates of the NDK can add support for more toolchains, platforms,
80    system interfaces without requiring changes in the developer's build
81    files (more on this later).
82
83
84II. Android NDK Non-Goals:
85--------------------------
86
87The NDK is *not* a good way to write generic native code that runs on Android
88devices. In particular, your applications should still be written in the Java
89programming language, handle Android system events appropriately to avoid the
90"Application Not Responding" dialog or deal with the Android application
91life-cycle.
92
93Note however that is is possible to write a sophisticated application in
94native code with a small "application wrapper" used to start/stop it
95appropriately.
96
97A good understanding of JNI is highly recommended, since many operations
98in this environment require specific actions from the developers, that are
99not necessarily common in typical native code. These include:
100
101  - Not being able to directly access the content of VM objects through
102    direct native pointers. E.g. you cannot safely get a pointer to a
103    String object's 16-bit char array to iterate over it in a loop.
104
105  - Requiring explicit reference management when the native code wants to
106    keep handles to VM objects between JNI calls.
107
108
109The NDK only provides system headers for a very limited set of native
110APIs and libraries supported by the Android platform. While a typical
111Android system image includes many native shared libraries, these should
112be considered an implementation detail that might change drastically between
113updates and releases of the platform.
114
115If an Android system library is not explicitly supported by the NDK
116headers, then applications should not depend on it being available, or
117they risk breaking after the next over-the-air system update on various
118devices.
119
120Selected system libraries will gradually be added to the set of stable NDK
121APIs.
122
123
124III. NDK development in practice:
125---------------------------------
126
127Here's a very rough overview of how you can develop native code with the
128Android NDK:
129
130  1/ Place your native sources under $PROJECT/jni/...
131
132  2/ Write $PROJECT/jni/Android.mk to describe your sources
133     to the NDK build system
134
135  3/ Optional: write $PROJECT/jni/Application.mk to describe your
136     project in more details to the build system. You don't need
137     one to get started though, but this allows you to target
138     more than one CPU or override compiler/linker flags
139     (see docs/APPLICATION-MK.html for all details).
140
141  4/ Build your native code by running "$NDK/ndk-build" from your
142     project directory, or any of its sub-directories.
143
144The last step will copy, in case of success, the stripped shared libraries
145your application needs to your application's root project directory. You
146will then need to generate your final .apk through the usual means.
147
148Now, for a few more details:
149
150
151III.1/ Configuring the NDK:
152- - - - - - - - - - - - - -
153
154Previous releases required that you run the 'build/host-setup.sh'
155script to configure your NDK. This step has been removed completely
156in release 4 (a.k.a. NDK r4).
157
158
159III.2/ Placing C and C++ sources:
160- - - - - - - - - - - - - - - - -
161
162Place your native sources under the following directory:
163
164    $PROJECT/jni/
165
166Where $PROJECT corresponds to the path of your Android application
167project.
168
169You are pretty free to organize the content of 'jni' as you want,
170the directory names and structure here will not influence the final
171generated application packages, so you don't have to use pseudo-unique
172names like com.&lt;mycompany&gt;.&lt;myproject&gt; as is the case for application
173package names.
174
175Note that C and C++ sources are supported. The default C++ file extensions
176supported by the NDK is '.cpp', but other extensions can be handled as well
177(see docs/ANDROID-MK.html for details).
178
179It is possible to store your sources in a different location by adjusting
180your Android.mk file (see below).
181
182
183III.3/ Writing an Android.mk build script:
184- - - - - - - - - - - - - - - - - - - - - -
185
186An Android.mk file is a small build script that you write to describe your
187sources to the NDK build system. Its syntax is described in details in
188the file docs/ANDROID-MK.html.
189
190In a nutshell, the NDK groups your sources into "modules", where each module
191can be one of the following:
192
193  - a static library
194  - a shared library
195
196You can define several modules in a single Android.mk, or you can write
197several Android.mk files, each one defining a single module.
198
199Note that a single Android.mk might be parsed several times by the build
200system so don't assume that certain variables are not defined in them.
201By default, the NDK will look for the following build script:
202
203   $PROJECT/jni/Android.mk
204
205If you want to define Android.mk files in sub-directories, you should
206include them explicitly in your top-level Android.mk. There is even
207a helper function to do that, i.e. use:
208
209   include $(call all-subdir-makefiles)
210
211This will include all Android.mk files in sub-directories of the current
212build file's path.
213
214
215III.4/ Writing an Application.mk build file (optional):
216- - - - - - - - - - - - - - - - - - - - - - - - - - - -
217
218While an Android.mk file describes your modules to the build system, the
219Application.mk file describes your application itself. See the
220docs/APPLICATION-MK.html document to understand what this file allows you
221to do. This includes, among others:
222
223   - The exact list of modules required by your application.
224
225   - The CPU architecture(s) to generate machine code for.
226
227  - Optional information, like whether you want a release or debug
228    build, specific C or C++ compiler flags and others that should
229    apply to all modules being built.
230
231This file is optional: by default the NDK will provide one that simply
232builds *all* the modules listed from your Android.mk (and all the makefiles
233it includes) and target the default CPU ABI (armeabi).
234
235There are two ways to use an Application.mk:
236
237  - Place it under $PROJECT/jni/Application.mk, and it will be picked
238    up automatically by the 'ndk-build' script (more on this later)
239
240  - Place it under $NDK/apps/&lt;name&gt;/Application.mk, where $NDK
241    points to your NDK installation path. After that, launch
242    "make APP=&lt;name&gt;" from the NDK directory.
243
244    This was the way this file was used before Android NDK r4.
245    It is still supported for compatibility reasons, but we strongly
246    encourage you to use the first method instead, since it is much
247    simpler and doesn't need modifying / changing directories of the
248    NDK installation tree.
249
250Again, see docs/APPLICATION-MK.html for a complete description of its
251content.
252
253
254III.5/ Invoke the NDK build system:
255- - - - - - - - - - - - - - - - - -
256
257The preferred way to build machine code with the NDK is to use the
258'ndk-build' script introduced with Android NDK r4. You can also use
259a second, legacy, method that depends on creating a '$NDK/apps' subdirectory.
260
261In both cases, a successful build will copy the final stripped binary modules
262(i.e. shared libraries) required by your application to your application's
263project path (Note that unstripped versions are kept for debugging
264purposes, there is no need to copy unstripped binaries to a device).
265
266
267  1: Using the 'ndk-build' command:
268  ---------------------------------
269
270  The 'ndk-build' script, located at the top of the NDK installation path
271  can be invoked directly from your application project directory (i.e. the
272  one where your AndroidManifest.xml is located) or any of its sub-directories.
273  For example:
274
275    cd $PROJECT
276    $NDK/ndk-build
277
278  This will launch the NDK build scripts, which will automatically probe your
279  development system and application project file to determine what to build.
280
281  For example:
282
283    ndk-build
284    ndk-build  clean    --&gt; clean generated binaries
285    ndk-build  -B V=1   --&gt; force complete rebuild, showing commands
286
287  By default, it expects an optional file under $PROJECT/jni/Application.mk,
288  and a required $PROJECT/jni/Android.mk.
289
290  On success, this will copy the generated binary modules (i.e. shared
291  libraries) to the appropriate location in your project tree. You can later
292  rebuild the full Android application package either through the usual
293  'ant' command, or the ADT Eclipse plug-in.
294
295  See docs/NDK-BUILD.html for a more complete description of what this script
296  does and which options it can take.
297
298
299III.6/ Specifying custom output directories:
300- - - - - - - - - - - - - - - - - - - - - - -
301
302By default, ndk-build places all intermediate generated files under
303$PROJECT/obj. You can however select a different location by defining
304the NDK_OUT environment variable to point to a different directory.
305
306When defined, this variable has two effects:
307
308  1/ It ensures that all files that normally go under $PROJECT/obj are
309     stored in $NDK_OUT instead
310
311  2/ It tells ndk-gdb to look into $NDK_OUT, instead of $PROJECT/obj for
312     any symbolized (i.e. unstripped) versions of the generated binaries.
313
314
315IV. Rebuild your application package:
316- - - - - - - - - - - - - - - - - - -
317
318After generating the binaries with the NDK, you need to rebuild your
319Android application package files (.apk) using the normal means, i.e.
320either using the 'ant' command or the ADT Eclipse plug-in.
321
322See the Android SDK documentation for more details. The new .apk will
323embed your shared libraries, and they will be extracted automatically
324at installation time by the system when you install the package on a
325target device.
326
327
328V. Debugging support:
329- - - - - - - - - - -
330
331The NDK provides a helper script, named 'ndk-gdb' to very easily launch
332a native debugging session of your applications.
333
334Native debugging can *ONLY* be performed on production devices running
335Android 2.2 or higher, and does not require root or privileged access, as
336long as your application is debuggable.
337
338For more information, read docs/NDK-GDB.html. In a nutshell, native debugging
339follows this simple scheme:
340
341   1. Ensure your application is debuggable (e.g. set android:debuggable
342      to "true" in your AndroidManifest.xml)
343
344   2. Build your application with 'ndk-build', then install it on your
345      device/emulator.
346
347   3. Launch your application.
348
349   4. Run 'ndk-gdb' from your application project directory.
350
351You will get a gdb prompt. See the GDB User Manual for a list of useful
352commands.
353</pre></body></html>
354