diff options
Diffstat (limited to 'docs/html/sdk/ndk/overview.jd')
| -rw-r--r-- | docs/html/sdk/ndk/overview.jd | 277 |
1 files changed, 252 insertions, 25 deletions
diff --git a/docs/html/sdk/ndk/overview.jd b/docs/html/sdk/ndk/overview.jd index a7ec5d4..f6d148a 100644 --- a/docs/html/sdk/ndk/overview.jd +++ b/docs/html/sdk/ndk/overview.jd @@ -7,10 +7,8 @@ page.title=What is the NDK? <ol> <li><a href="#choosing">When to Develop in Native Code</a></li> - <li> <a href="#contents">Contents of the NDK</a> - <ol> <li><a href="#tools">Development tools</a></li> @@ -19,9 +17,7 @@ page.title=What is the NDK? <li><a href="#samples">Sample applications</a></li> </ol> </li> - <li><a href="#reqs">System and Software Requirements</a></li> - </ol> </div> </div> @@ -102,9 +98,8 @@ page.title=What is the NDK? later.</li> <li> - <p>Write a native activity, which allows you to potentially create an application completely in native - code, because you can implement the lifecycle callbacks natively. The Android SDK provides - the {@link android.app.NativeActivity} class, which is a convenience class that notifies your + <p>Write a native activity, which allows you to implement the lifecycle callbacks in native + code. The Android SDK provides the {@link android.app.NativeActivity} class, which is a convenience class that notifies your native code of any activity lifecycle callbacks (<code>onCreate()</code>, <code>onPause()</code>, <code>onResume()</code>, etc). You can implement the callbacks in your native code to handle these events when they occur. Applications that use native activities must be run on Android @@ -142,6 +137,10 @@ page.title=What is the NDK? <li>libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).</li> <li>A Minimal set of headers for C++ support</li> + + <li>OpenSL ES native audio libraries</li> + + <li>Android native application APIS</li> </ul> <p>The NDK also provides a build system that lets you work efficiently with your sources, without @@ -163,25 +162,18 @@ page.title=What is the NDK? the <code><ndk>/docs/</code> directory. Included are these files:</p> <ul> - <li>INSTALL.HTML — describes how to install the NDK and configure it for your host + <li> + INSTALL.HTML — describes how to install the NDK and configure it for your host system</li> <li>OVERVIEW.HTML — provides an overview of the NDK capabilities and usage</li> - + <li>ANDROID-MK.HTML — describes the use of the Android.mk file, which defines the native sources you want to compile</li> - + <li>APPLICATION-MK.HTML — describes the use of the Application.mk file, which describes - the native sources required by your Android application</li> - - <li>HOWTO.HTML — information about common tasks associated with NDK development.</li> - - <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be - aware of, if you are developing using the NDK.</li> - - <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the - NDK.</li> - + the native sources required by your Android application</li> + <li>CPLUSPLUS-SUPPORT.HTML — describes the C++ support provided in the Android NDK</li> <li>CPU-ARCH-ABIS.HTML — a description of supported CPU architectures and how to target them.</li> @@ -193,6 +185,32 @@ page.title=What is the NDK? instructions.</li> <li>CHANGES.HTML — a complete list of changes to the NDK across all releases.</li> + + <li>DEVELOPMENT.HTML — describes how to modify the NDK and generate release packages for it</li> + + <li>HOWTO.HTML — information about common tasks associated with NDK development</li> + + <li>IMPORT-MODULE.HTML — describes how to share and reuse modules</li> + + <li>LICENSES.HTML — information about the various open source licenses that govern the Android NDK</li> + + <li>NATIVE-ACTIVITY.HTML — describes how to implement native activities</li> + + <li>NDK-BUILD.HTML — describes the usage of the ndk-build script</li> + + <li>NDK-GDB.HTML — describes how to use the native code debugger</li> + + <li>PREBUILTS.HTML — information about how shared and static prebuilt libraries work </li> + + <li>STANDALONE-TOOLCHAIN.HTML — describes how to use Android NDK toolchain as a standalone + compiler (still in beta).</li> + + <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be + aware of, if you are developing using the NDK.</li> + + <li>STABLE-APIS.HTML — 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 @@ -206,9 +224,218 @@ page.title=What is the NDK? <h3 id="samples">Sample applications</h3> - <p>The NDK includes sample Android applications that illustrate how to use native code in your - Android applications. For more information, see <a href= - "{@docRoot}sdk/ndk/installing.html#samples">Sample Applications</a>.</p> +<p>The NDK includes 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> + + <li><code>san-angeles</code> — a simple application that renders 3D graphics through the + native OpenGL ES APIs, while managing activity lifecycle with a {@link + android.opengl.GLSurfaceView} object.</li> + + <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES + 2.0 vertex and fragment shaders.</li> + + <li><code>hello-neon</code> — a simple application that shows how to use the + <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics + if supported by the CPU. Specifically, the application implements two versions of a tiny + benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that + support it.</li> + + <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the + pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses + this to generate an old-school "plasma" effect.</li> + + <li><code>native-activity</code> — a simple application that demonstrates how to use the + native-app-glue static library to create a native activity</li> + + <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native + activity.</li> + </ul> + + <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk + and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> + and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> + + <p>You can build the shared libraries for the sample apps by going into + <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. + The generated shared libraries will be located under + <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or + <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> + + <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> + + <h4 id="hello-jni">Exploring the hello-jni Sample</h4> + + <p>The hello-jni sample is a simple demonstration on how to use JNI from an Android application. + The HelloJni activity receives a string from a simple C function and displays it in a + TextView.</p> + + <p>The main components of the sample include:</p> + + <ul> + <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> + file, a <code>src/</code> and <code>res</code> directories, and a main activity)</li> + + <li>A <code>jni/</code> directory that includes the implemented source file for the native code + as well as the Android.mk file</li> + + <li>A <code>tests/</code> directory that contains unit test code.</li> + </ul> + + <ol> + <li>Create a new project in Eclipse from the existing sample source or use the + <code>android</code> tool to update the project so it generates a build.xml file that you can + use to build the sample. + + <ul> + <li>In Eclipse: + + <ol type="a"> + <li>Click <strong>File > New Android Project...</strong></li> + + <li>Select the <strong>Create project from existing source</strong> radio button.</li> + + <li>Select any API level above Android 1.5.</li> + + <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select + the <code><ndk-root>/samples/hello-jni</code> directory.</li> + + <li>Click <strong>Finish</strong>.</li> + </ol> + </li> + + <li>On the command line: + + <ol type="a"> + <li>Change to the <code><ndk-root>/samples/hello-jni</code> directory.</li> + + <li>Run the following command to generate a build.xml file: + <pre class="no-pretty-print">android update project -p . -s</pre> + </li> + </ol> + </li> + </ul> + </li> + + <li>Compile the native code using the <code>ndk-build</code> command. + <pre class="no-pretty-print"> +cd <ndk-root>/samples/hello-jni +<ndk_root>/ndk-build +</pre> + </li> + + <li>Build and install the application as you would a normal Android application. If you are + using Eclipse, run the application to build and install it on a device. If you are using Ant, + run the following commands from the project directory: + <pre class="no-pretty-print"> +ant debug +adb install bin/HelloJni-debug.apk +</pre> + </li> + </ol> + + <p>When you run the application on the device, the string <code>Hello JNI</code> should appear on + your device. You can explore the rest of the samples that are located in the + <code><ndk-root>/samples</code> directory for more examples on how to use the JNI.</p> + + <h4 id="native-activity">Exploring the native-activity Sample Application</h4> + + <p>The native-activity sample provided with the Android NDK demonstrates how to use the + android_native_app_glue static library. This static library makes creating a native activity + easier by providing you with an implementation that handles your callbacks in another thread, so + you do not have to worry about them blocking your main UI thread. The main parts of the sample + are described below:</p> + + <ul> + <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> + file, a <code>src/</code> and <code>res</code> directories). The AndroidManifest.xml declares + that the application is native and specifies the .so file of the native activity. See {@link + android.app.NativeActivity} for the source or see the + <code><ndk_root>/platforms/samples/native-activity/AndroidManifest.xml</code> file.</li> + + <li>A <code>jni/</code> directory contains the native activity, main.c, which uses the + <code>android_native_app_glue.h</code> interface to implement the activity. The Android.mk that + describes the native module to the build system also exists here.</li> + </ul> + + <p>To build this sample application:</p> + + <ol> + <li>Create a new project in Eclipse from the existing sample source or use the + <code>android</code> tool to update the project so it generates a build.xml file that you can + use to build the sample. + + <ul> + <li>In Eclipse: + + <ol type="a"> + <li>Click <strong>File > New Android Project...</strong></li> + + <li>Select the <strong>Create project from existing source</strong> radio button.</li> + + <li>Select any API level above Android 2.3.</li> + + <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select + the <code><ndk-root>/samples/native-activity</code> directory.</li> + + <li>Click <strong>Finish</strong>.</li> + </ol> + </li> + + <li>On the command line: + + <ol type="a"> + <li>Change to the <code><ndk-root>/samples/native-activity</code> directory.</li> + + <li>Run the following command to generate a build.xml file: + <pre class="no-pretty-print"> +android update project -p . -s +</pre> + </li> + </ol> + </li> + </ul> + </li> + + <li>Compile the native code using the <code>ndk-build</code> command. + <pre class="no-pretty-print"> +cd <ndk-root>/platforms/samples/android-9/samples/native-activity +<ndk_root>/ndk-build +</pre> + </li> + + <li>Build and install the application as you would a normal Android application. If you are + using Eclipse, run the application to build and install it on a device. If you are using Ant, + run the following commands in the project directory, then run the application on the device: + <pre class="no-pretty-print"> +ant debug +adb install bin/NativeActivity-debug.apk +</pre> + </li> + </ol> + <h2 id="reqs">System and Software Requirements</h2> @@ -313,7 +540,7 @@ page.title=What is the NDK? to users whose devices are capable of supporting your application. For example: <pre style="margin:1em;"> <manifest> - ... + ... <!-- Declare that the application uses the OpenGL ES 2.0 API and is designed to run only on devices that support OpenGL ES 2.0 or higher. --> <uses-feature android:glEsVersion="0x00020000" /> @@ -331,4 +558,4 @@ page.title=What is the NDK? containing the library can be deployed only to devices running Android 2.2 (API level 8) or higher. To ensure compatibility, make sure that your application declares <code><uses-sdk android:minSdkVersion="8" /></code> attribute value in its manifest.</li> - </ul>
\ No newline at end of file + </ul> |