312 lines
13 KiB
Plaintext
312 lines
13 KiB
Plaintext
ndk=true
|
|
ndk.version=1.5
|
|
ndk.rel.id=1
|
|
ndk.date=May 2009
|
|
|
|
ndk.win_download=android-ndk-1.5_r1-windows.zip
|
|
ndk.win_bytes=22450814
|
|
ndk.win_checksum=7b7836f705ec7e66225794edda34000f
|
|
|
|
ndk.mac_download=android-ndk-1.5_r1-darwin-x86.zip
|
|
ndk.mac_bytes=17165450
|
|
ndk.mac_checksum=214ccfd704c0307609fbabeb7bf86acc
|
|
|
|
ndk.linux_download=android-ndk-1.5_r1-linux-x86.zip
|
|
ndk.linux_bytes=15976032
|
|
ndk.linux_checksum=808fd4d6a7e45f76d546ba04ab9ef060
|
|
|
|
ndk.linux_64_download=android-ndk-1.5_r1-linux-x86_64.zip
|
|
ndk.linux_64_bytes=18112300
|
|
ndk.linux_64_checksum=f8664c187b3ae077bcfe2b44294d0758
|
|
|
|
page.title=Android 1.5 NDK, Release 1
|
|
@jd:body
|
|
|
|
<h2>What is the NDK?</h2>
|
|
|
|
<p>The Android 1.5 NDK provides tools that allow Android application developers
|
|
to embed and deploy native code within their Android applications. It
|
|
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>
|
|
</ul>
|
|
|
|
<p>This release of the NDK release supports the ARMv5TE machine instruction set
|
|
and provides stable headers for libc (the C library), libm (the Math library)
|
|
and the JNI interface.</p>
|
|
|
|
<p>Using the NDK may not be relevant for all Android applications. As a
|
|
developer, you will need to balance its benefits (faster execution) and its
|
|
drawbacks (no portability, JNI overhead, no access to system libraries, and
|
|
difficult debugging). Typical good candidates for the NDK are CPU-intensive
|
|
operations that don't allocate too much memory, such as signal processing,
|
|
physics simulation, custom bytecode/instruction interpreters, and so on.</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>
|
|
</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>
|
|
</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> 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 subtle
|
|
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>
|
|
|
|
|