| ndk=true |
| ndk.version=1.5 |
| ndk.rel.id=1 |
| ndk.date=June 2009 |
| |
| ndk.win_download=android-ndk-1.5_r1-windows.zip |
| ndk.win_bytes=22500667 |
| ndk.win_checksum=e5c53915903d8b81f3e2ea422e2e2717 |
| |
| ndk.mac_download=android-ndk-1.5_r1-darwin-x86.zip |
| ndk.mac_bytes=17215303 |
| ndk.mac_checksum=1931f0e182798a4c98924fd87380b5b8 |
| |
| ndk.linux_download=android-ndk-1.5_r1-linux-x86.zip |
| ndk.linux_bytes=16025885 |
| ndk.linux_checksum=80a4e14704ca84c21bf1824cb25fbd8b |
| |
| page.title=Android 1.5 NDK, Release 1 |
| @jd:body |
| |
| <h2 id="overview">What is the Android NDK?</h2> |
| |
| <p>The Android NDK provides tools that allow Android application developers |
| to embed components that make use of native code in their Android applications. |
| </p> |
| |
| <p>Android applications run in the Dalvik virtual machine. The NDK allows |
| developers to implement parts of their applications using native-code languages |
| such as C and C++. This can provide benefits to certain classes of applications, |
| in the form of reuse of existing code and in some cases increased speed.</p> |
| |
| <p>The NDK provides:</p> |
| |
| <ul> |
| <li>A set of tools and build files used to generate native code libraries from C |
| and C++ sources</li> |
| <li>A way to embed the corresponding native libraries into application package |
| files (.apks) that can be deployed on Android devices</li> |
| <li>A set of native system headers and libraries that will be supported in all |
| future versions of the Android platform, starting from Android 1.5 </li> |
| <li>Documentation, samples, and tutorials</li> |
| </ul> |
| |
| <p>This release of the NDK supports the ARMv5TE machine instruction set |
| and provides stable headers for libc (the C library), libm (the Math library), |
| the JNI interface, and other libraries.</p> |
| |
| <p>The NDK will not benefit most applications. As a developer, you will need |
| to balance its benefits against its drawbacks; notably, using native code does |
| not result in an automatic performance increase, but does always increase |
| application complexity. Typical good candidates for the NDK are self-contained, |
| CPU-intensive operations that don't allocate much memory, such as signal processing, |
| physics simulation, and so on. Simply re-coding a method to run in C usually does |
| not result in a large performance increase. The NDK can, however, can be |
| an effective way to reuse a large corpus of existing C/C++ code.</p> |
| |
| <p>Please note that the NDK <em>does not</em> enable you to develop native-only |
| applications. Android's primary runtime remains the Dalvik virtual machine.</p> |
| |
| <h2 id="contents">Contents of the NDK</h2> |
| |
| <h4>Development tools</h4> |
| |
| <p>The NDK includes a set of cross-toolchains (compilers, linkers, etc..) that |
| can generate native ARM binaries on Linux, OS X, and Windows (with Cygwin) |
| platforms.</p> |
| |
| <p>It provides a set of system headers for stable native APIs that are |
| guaranteed to be supported in all later releases of the platform:</p> |
| |
| <ul> |
| <li>libc (C library) headers</li> |
| <li>libm (math library) headers</li> |
| <li>JNI interface headers</li> |
| <li>libz (Zlib compression) headers</li> |
| <li>liblog (Android logging) header</li> |
| <li>A Minimal set of headers for C++ support</li> |
| </ul> |
| |
| <p>The NDK also provides a build system that lets you work efficiently with your |
| sources, without having to handle the toolchain/platform/CPU/ABI details. You |
| create very short build files to describe which sources to compile and which |
| Android application will use them — the build system compiles the sources |
| and places the shared libraries directly in your application project. </p> |
| |
| <p class="caution"><strong>Important:</strong> With the exception of the |
| libraries listed above, native system libraries in the Android 1.5 platform are |
| <em>not</em> stable and may change in future platform versions. |
| Your applications should <em>only</em> make use of the stable native system |
| libraries provided in this NDK. </p> |
| |
| <h4>Documentation</h4> |
| |
| <p>The NDK package includes a set of documentation that describes the |
| capabilities of the NDK and how to use it to create shared libraries for your |
| Android applications. In this release, the documentation is provided only in the |
| downloadable NDK package. You can find the documentation in the |
| <code><ndk>/docs/</code> directory. Included are these files:</p> |
| |
| <ul> |
| <li>INSTALL.TXT — describes how to install the NDK and configure it for |
| your host system</li> |
| <li>OVERVIEW.TXT — provides an overview of the NDK capabilities and |
| usage</li> |
| <li>ANDROID-MK.TXT — describes the use of the Android.mk file, which |
| defines the native sources you want to compile</li> |
| <li>APPLICATION-MK.TXT — describes the use of the Application.mk file, |
| which describes the native sources required by your Android application</li> |
| <li>HOWTO.TXT — information about common tasks associated with NDK |
| development.</li> |
| <li>SYSTEM-ISSUES.TXT — known issues in the Android system images |
| that you should be aware of, if you are developing using the NDK. </li> |
| <li>STABLE-APIS.TXT — a complete list of the stable APIs exposed |
| by headers in the NDK.</li> |
| </ul> |
| |
| <p>Additionally, the package includes detailed information about the "bionic" |
| C library provided with the Android platform that you should be aware of, if you |
| are developing using the NDK. You can find the documentation in the |
| <code><ndk>/docs/system/libc/</code> directory:</p> |
| |
| <ul> |
| <li>OVERVIEW.TXT — provides an overview of the "bionic" C library and the |
| features it offers.</li> |
| </ul> |
| |
| <h4>Sample applications</h4> |
| |
| <p>The NDK includes two sample Android applications that illustrate how to use |
| native code in your Android applications:</p> |
| |
| <ul> |
| <li><code>hello-jni</code> — A simple application that loads a string from |
| a native method implemented in a shared library and then displays it in the |
| application UI. </li> |
| <li><code>two-libs</code> — A simple application that loads a shared |
| library dynamically and calls a native method provided by the library. In this |
| case, the method is implemented in a static library that is imported by the |
| shared library. </li> |
| </ul> |
| |
| <p>For more information, see <a href="#samples">Using the Sample |
| Applications</a>.</p> |
| |
| <h2 id="requirements">System and Software Requirements</h2> |
| |
| <p>The sections below describe the system and software requirements for using |
| the Android NDK, as well as platform compatibility considerations that affect |
| appplications using libraries produced with the NDK. </p> |
| |
| <h4>The Android SDK</h4> |
| <ul> |
| <li>A complete Android SDK installation (including all dependencies) is |
| required.</li> |
| <li>Android 1.5 SDK or later version is required.</li> |
| </ul> |
| |
| <h4>Supported operating systems</h4> |
| <ul> |
| <li>Windows XP (32-bit) or Vista (32- or 64-bit)</li> |
| <li>Mac OS X 10.4.8 or later (x86 only)</li> |
| <li>Linux (32- or 64-bit, tested on Linux Ubuntu Dapper Drake)</li> |
| </ul> |
| |
| <h4>Required development tools</h4> |
| <ul> |
| <li>For all development platforms, GNU Make 3.81 or later is required. Earlier |
| versions of GNU Make might work but have not been tested.</li> |
| <li>For Windows, a recent release of <a |
| href="http://www.cygwin.com">Cygwin</a>, including both the gmake and gcc |
| packages, is required. </li> |
| </ul> |
| |
| <h4>Android platform compatibility</h4> |
| <ul> |
| <li>The native libraries created by the Android NDK can only be used on |
| devices running the Android 1.5 platform version or later. This is due to |
| toolchain and ABI related changes that make the native libraries incompatible |
| with 1.0 and 1.1 system images.</li> |
| <li>For this reason, you should use native libraries produced with the NDK in |
| applications that are deployable to devices running the Android 1.5 platform |
| version or later. To ensure compatibility, an application using a native library |
| produced with the NDK must declare a <code><uses-library></code> element |
| in its manifest file, with the attribute |
| <code>android:minSdkVersion="3"</code>.</li> |
| </ul> |
| |
| <h2 id="installing">Installing the NDK</h2> |
| |
| <p>Installing the NDK on your development computer is straightforward and |
| involves extracting the NDK from its download package and running a host-setup |
| script. </p> |
| |
| <p>Before you get started make sure that you have downloaded the latest <a |
| href="{@docRoot}sdk/index.html">Android SDK</a> and upgraded your applications |
| and environment as needed. The NDK will not work with older versions of the |
| Android SDK. Also, take a moment to review the <a href="#requirements">System |
| and Software Requirements</a> for the NDK, if you haven't already. </p> |
| |
| <p>To install the NDK, follow these steps:</p> |
| |
| <ol> |
| <li>From the table at the top of this page, select the NDK package that is |
| appropriate for your development computer and download the package.</li> |
| <li>Uncompress the NDK download package using tools available on your computer. |
| When uncompressed, the NDK files are contained in a directory called |
| <code>android-ndk-<version></code>. You can rename the NDK directory if |
| necessary and you can move it to any location on your computer. This |
| documentation refers to the NDK directory as <code><ndk></code>. </li> |
| <li>Open a terminal, change to the NDK directory, and run the host-setup script. |
| The script sets up your environment and generates a host configuration file used |
| later, when building your shared libraries. The path to the host-setup script |
| is: |
| |
| <p><code><ndk>/build/host-setup.sh</code></p> |
| |
| <p>If the script completes successfully, it prints a "Host setup complete." |
| message. If it fails, it prints instructions that you can follow to correct any |
| problems. </p> |
| </li> |
| </ol> |
| |
| <p>Once you have run the host-setup script, you are ready start working with the |
| NDK. </p> |
| |
| <h2 id="gettingstarted">Getting Started with the NDK</h2> |
| |
| <p>Once you've installed the NDK successfully, take a few minutes to read the |
| documentation included in the NDK. You can find the documentation in the |
| <code><ndk>/docs/</code> directory. In particular, please read the |
| OVERVIEW.TXT document completely, so that you understand the intent of the NDK |
| and how to use it.</p> |
| |
| <p>Here's the general outline of how you work with the NDK tools:</p> |
| |
| <ol> |
| <li>Place your native sources under |
| <code><ndk>/sources/<my_src>/...</code>. If you want, you can place |
| a symlink to your sources, rather than the sources themselves. The sources you |
| reference here are not strictly associated with a specific shared library or |
| Android application. Instead, they are accessible to any build configuration and |
| can be used to produce any number of shared libraries that can be used by any |
| Android application.</li> |
| <li>Create <code><ndk>/sources/<my_src>/Android.mk</code> to |
| describe your native sources to the NDK build system</li> |
| <li>Create <code><ndk>/apps/<my_app>/Application.mk</code> to |
| describe your Android application and native sources it needs to the NDK build |
| system. This file sets up the link between an Android SDK application project |
| and any number of shared libraries defined in the |
| <code><ndk>/sources/</code> folder and it specifies the path to the |
| application project that will receive the shared library built from the |
| sources.</li> |
| <li>Build your native code by running this make command from the top-level NDK |
| directory: |
| |
| <p><code>$ make APP=<my_app></code></p> |
| |
| <p>The build tools copy the stripped, shared libraries needed by your |
| application to the proper location in the application's project directory.</p> |
| </li> |
| |
| <li>Finally, compile your application using the SDK tools in the usual way. The |
| SDK build tools will package the shared libraries in the application's |
| deployable .apk file. </p></li> |
| |
| </ol> |
| |
| <p>For complete information on all of the steps listed above, please see the |
| documentation included with the NDK package. </p> |
| |
| |
| <h2 id="samples">Using the Sample Applications</h2> |
| |
| <p>The NDK includes two sample applications that illustrate how to use native |
| code in your Android applications:</p> |
| |
| <ul> |
| <li><code>hello-jni</code> — A simple application that loads a string from |
| a native method implemented in a shared library and then displays it in the |
| application UI. </li> |
| <li><code>two-libs</code> — A simple application that loads a shared |
| library dynamically and calls a native method provided by the library. In this |
| case, the method is implemented in a static library imported by the shared |
| library. </li> |
| </ul> |
| |
| <p>For each sample, the NDK includes an Android application project, as well as |
| the corresponding C source code and the necessary Android.mk and Application.mk |
| files. The application projects are provided in |
| <code><ndk>/apps/<app_name>/project/</code> and the C source for |
| each application is provided in |
| <code><ndk>/sources/samples/<library>/</code>.</p> |
| |
| <p>Once you have installed the NDK, you can build the shared libraries from the |
| NDK by using these commands from the root of the NDK directory:</p> |
| <ul> |
| <li><code>$ make APP=hello-jni</code> — compiles |
| <code><ndk>/sources/samples/hello-jni/hello-jni.c</code> and outputs a |
| shared library to |
| <code><ndk>/apps/hello-jni/project/libs/armeabi/libhello-jni.so</code>. |
| </li> |
| <li><code>$ make APP=two-libs</code> — compiles |
| <code><ndk>/sources/samples/two-libs/second.c</code> and |
| <code>first.c</code> and outputs a shared library to |
| <code><ndk>/apps/two-libs/project/libs/armeabi/libtwolib-second.so</code>. |
| </li> |
| </ul> |
| |
| <p>Next, build the sample Android applications that use the shared |
| libraries:</p> |
| |
| <ul> |
| <li>If you are developing in Eclipse with ADT, use the New Project Wizard to |
| create a new Android project for each sample, using the "Import from Existing |
| Source" option and importing the source from |
| <code><ndk>/apps/<app_name>/project/</code>. Then, set up an AVD, if |
| necessary, and build/run the application in the emulator. For more information |
| about creating a new Android project in Eclipse, see <a |
| href="{@docRoot}guide/developing/eclipse-adt.html">Developing in |
| Eclipse</a>.</li> |
| <li>If you are developing with Ant, use the <code>android</code> tool to create |
| the build file for each of the sample projects at |
| <code><ndk>/apps/<app_name>/project/</code>. Then set up an AVD, if |
| necessary, build your project in the usual way, and run it in the emulator. |
| For more information, see <a |
| href="{@docRoot}guide/developing/other-ide.html">Developing in Other |
| IDEs</a>.</li> |
| </ul> |
| |
| <h2>Discussion Forum and Mailing List</h2> |
| |
| <p>If you have questions about the NDK or would like to read or contribute to |
| discussions about it, please visit the <a |
| href="http://groups.google.com/group/android-ndk">android-ndk</a> group and |
| mailing list.</p> |
| |
| |