From 1dced50963312c5d340cbd129d0017d9cbb45f0b Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Mon, 11 Jan 2010 09:33:00 -0800 Subject: [PATCH] SDK doc change: Add doc update for NDKr3. Bug: 2160782 Change-Id: I20bd2b84bdab27b03c3544d8eecab2404eeb2c1c --- docs/html/sdk/ndk/r3/index.jd | 394 ++++++++++++++++++++++++++++++++++ docs/html/sdk/sdk_toc.cs | 3 +- 2 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 docs/html/sdk/ndk/r3/index.jd diff --git a/docs/html/sdk/ndk/r3/index.jd b/docs/html/sdk/ndk/r3/index.jd new file mode 100644 index 0000000000000..13dae7f342783 --- /dev/null +++ b/docs/html/sdk/ndk/r3/index.jd @@ -0,0 +1,394 @@ +ndk=true +ndk.rel.id=3 +ndk.date=January 2010 + +ndk.win_download=android-ndk-r3-windows.zip +ndk.win_bytes=36470676 +ndk.win_checksum=623311259d601e1fd3daccf8b3e24e04 + +ndk.mac_download=android-ndk-r3-darwin-x86.zip +ndk.mac_bytes=38255513 +ndk.mac_checksum=3b2f41ea46549724c938416a98731166 + +ndk.linux_download=android-ndk-r3-linux-x86.zip +ndk.linux_bytes=37400526 +ndk.linux_checksum=08f3754f541e2b9563d371482656617a + +page.title=Android NDK, Release 3 +@jd:body + +

What is the Android NDK?

+ +

The Android NDK provides tools that allow Android application developers +to embed components that make use of native code in their Android applications. +

+ +

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.

+ +

The NDK provides:

+ + + +

This release of the NDK supports two ARM instruction sets:

+ + +

ARMv5TE machine code will run on all ARM-based Android devices. ARMv7-A will +run only on devices such as the Verizon Droid or Google Nexus One that have a +compatible CPU. The main difference between the two instruction sets is that +ARMv7-A supports hardware FPU and Thumb-2 instructions. You can target either or +both of the instruction sets — ARMv5TE is the default, but switching to +ARMv7-A is as easy as adding a single line to the application's Application.mk +file, without needing to change anything else in the file. You can also build +for both architectures at the same time and have everything stored in the final +.apk. Complete information is provided in the CPU-ARCH-ABIS.TXT in the NDK +package.

+ +

The NDK provides stable headers for libc (the C library), libm (the Math +library), OpenGL ES (3D graphics library), the JNI interface, and other +libraries, as listed in the section below.

+ +

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.

+ +

Please note that the NDK does not enable you to develop native-only +applications. Android's primary runtime remains the Dalvik virtual machine.

+ +

Contents of the NDK

+ +

Development tools

+ +

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.

+ +

It provides a set of system headers for stable native APIs that are +guaranteed to be supported in all later releases of the platform:

+ + + +

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.

+ +

Important: With the exception of the +libraries listed above, native system libraries in the Android platform are +not stable and may change in future platform versions. +Your applications should only make use of the stable native system +libraries provided in this NDK.

+ +

Documentation

+ +

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 +<ndk>/docs/ directory. Included are these files:

+ + + +

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 +<ndk>/docs/system/libc/ directory:

+ + + +

Sample applications

+ +

The NDK includes four sample Android applications that illustrate how to use +native code in your Android applications:

+ + + +

For more information, see Using the Sample +Applications.

+ +

System and Software Requirements

+ +

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.

+ +

The Android SDK

+ + +

Supported operating systems

+ + +

Required development tools

+ + +

Android platform compatibility

+ + +

Installing the NDK

+ +

Installing the NDK on your development computer is straightforward and +involves extracting the NDK from its download package and running a host-setup +script.

+ +

Before you get started make sure that you have downloaded the latest Android SDK 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 System +and Software Requirements for the NDK, if you haven't already.

+ +

To install the NDK, follow these steps:

+ +
    +
  1. From the table at the top of this page, select the NDK package that is +appropriate for your development computer and download the package.
    2. +
  2. Uncompress the NDK download package using tools available on your computer. +When uncompressed, the NDK files are contained in a directory called +android-ndk-<version>. 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 <ndk>.
    3. +
  3. 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: + +

    <ndk>/build/host-setup.sh

    + +

    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.

    +
    4. +
+ +

Once you have run the host-setup script, you are ready start working with the +NDK.

+ +

Getting Started with the NDK

+ +

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 +<ndk>/docs/ directory. In particular, please read the +OVERVIEW.TXT document completely, so that you understand the intent of the NDK +and how to use it.

+ +

If you used a previous version of the NDK, take a moment to review the +list of NDK changes in the CHANGES.TXT document.

+ +

Here's the general outline of how you work with the NDK tools:

+ +
    +
  1. Place your native sources under +<project>/jni/...
    2. +
  2. Create <project>/jni/Android.mk to +describe your native sources to the NDK build system
    3. +
  3. Create <ndk>/apps/<my_app>/Application.mk 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 +<project>/jni/ folder and it specifies the path to the +application project that will receive the shared library built from the +sources.
    4. +
  4. Build your native code by running this make command from the top-level NDK +directory: + +

    $ make APP=<my_app>

    + +

    The build tools copy the stripped, shared libraries needed by your +application to the proper location in the application's project directory.

    +
    5. + +
  5. 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.

    6. + +
+ +

For complete information on all of the steps listed above, please see the +documentation included with the NDK package.

+ + +

Using the Sample Applications

+ +

The NDK includes four sample applications that illustrate how to use native +code in your Android applications:

+ + + +

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 +<ndk>/apps/<app_name>/project/ and the C source for +each application is provided in +<ndk>/apps/<app_name>/project/jni/.

+ +

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:

+ + +

Next, build the sample Android applications that use the shared +libraries:

+ + + +

Discussion Forum and Mailing List

+ +

If you have questions about the NDK or would like to read or contribute to +discussions about it, please visit the android-ndk group and +mailing list.

+ + diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 556f78164241b..8ef1176ac2475 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -126,7 +126,8 @@ Windows, r3 new!