1page.title=What is the NDK? 2@jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 8 <ol> 9 <li><a href="#choosing">When to Develop in Native Code</a></li> 10 <li> 11 <a href="#contents">Contents of the NDK</a> 12 <ol> 13 <li><a href="#tools">Development tools</a></li> 14 15 <li><a href="#docs">Documentation</a></li> 16 17 <li><a href="#samples">Sample applications</a></li> 18 </ol> 19 </li> 20 <li><a href="#reqs">System and Software Requirements</a></li> 21 </ol> 22 </div> 23 </div> 24 25 <p>The Android NDK is a toolset that lets you embed components that make use of native code in 26 your Android applications.</p> 27 28 <p>Android applications run in the Dalvik virtual machine. The NDK allows you to implement parts 29 of your applications using native-code languages such as C and C++. This can provide benefits to 30 certain classes of applications, in the form of reuse of existing code and in some cases 31 increased speed.</p> 32 33 <p>The NDK provides:</p> 34 35 <ul> 36 <li>A set of tools and build files used to generate native code libraries from C and C++ 37 sources</li> 38 39 <li>A way to embed the corresponding native libraries into an application package file 40 (<code>.apk</code>) that can be deployed on Android devices</li> 41 42 <li>A set of native system headers and libraries that will be supported in all future versions 43 of the Android platform, starting from Android 1.5. Applications that use native activities 44 must be run on Android 2.3 or later.</li> 45 46 <li>Documentation, samples, and tutorials</li> 47 </ul> 48 49 <p>The latest release of the NDK supports these ARM instruction sets:</p> 50 51 <ul> 52 <li>ARMv5TE (including Thumb-1 instructions)</li> 53 54 <li>ARMv7-A (including Thumb-2 and VFPv3-D16 instructions, with optional support for 55 NEON/VFPv3-D32 instructions)</li> 56 </ul> 57 58 <p>Future releases of the NDK will also support:</p> 59 60 <ul> 61 <li>x86 instructions (see CPU-ARCH-ABIS.HTML for more information)</li> 62 </ul> 63 64 <p>ARMv5TE machine code will run on all ARM-based Android devices. ARMv7-A will run only on 65 devices such as the Verizon Droid or Google Nexus One that have a compatible CPU. The main 66 difference between the two instruction sets is that ARMv7-A supports hardware FPU, Thumb-2, and 67 NEON instructions. You can target either or both of the instruction sets — ARMv5TE is the 68 default, but switching to ARMv7-A is as easy as adding a single line to the application's 69 <code>Application.mk</code> file, without needing to change anything else in the file. You can also build for 70 both architectures at the same time and have everything stored in the final <code>.apk</code>. 71 Complete information is provided in the CPU-ARCH-ABIS.HTML in the NDK package.</p> 72 73 <p>The NDK provides stable headers for libc (the C library), libm (the Math library), OpenGL ES 74 (3D graphics library), the JNI interface, and other libraries, as listed in the <a href= 75 "#tools">Development Tools</a> section.</p> 76 77 <h2 id="choosing">When to Develop in Native Code</h2> 78 79 <p>The NDK will not benefit most applications. As a developer, you need to balance its benefits 80 against its drawbacks; notably, using native code does not result in an automatic performance 81 increase, but always increases application complexity. In general, you should only use native 82 code if it is essential to your application, not just because you prefer to program in C/C++.</p> 83 84 <p>Typical good candidates for the NDK are self-contained, CPU-intensive operations that don't 85 allocate much memory, such as signal processing, physics simulation, and so on. Simply re-coding 86 a method to run in C usually does not result in a large performance increase. When examining 87 whether or not you should develop in native code, think about your requirements and see if the 88 Android framework APIs provide the functionality that you need. The NDK can, however, can be an 89 effective way to reuse a large corpus of existing C/C++ code.</p> 90 91 <p>The Android framework provides two ways to use native code:</p> 92 93 <ul> 94 <li>Write your application using the Android framework and use JNI to access the APIs provided 95 by the Android NDK. This technique allows you to take advantage of the convenience of the 96 Android framework, but still allows you to write native code when necessary. You can install 97 applications that use native code through the JNI on devices that run Android 1.5 or 98 later.</li> 99 100 <li> 101 <p>Write a native activity, which allows you to implement the lifecycle callbacks in native 102 code. The Android SDK provides the {@link android.app.NativeActivity} class, which is a convenience class that notifies your 103 native code of any activity lifecycle callbacks (<code>onCreate()</code>, <code>onPause()</code>, 104 <code>onResume()</code>, etc). You can implement the callbacks in your native code to handle 105 these events when they occur. Applications that use native activities must be run on Android 106 2.3 (API Level 9) or later.</p> 107 108 <p>You cannot access features such as Services and Content Providers natively, so if you want 109 to use them or any other framework API, you can still write JNI code to do so.</p> 110 </li> 111 </ul> 112 113 <h2 id="contents">Contents of the NDK</h2>The NDK contains the APIs, documentation, and sample 114 applications that help you write your native code. 115 116 <h3 id="tools">Development tools</h3> 117 118 <p>The NDK includes a set of cross-toolchains (compilers, linkers, etc..) that can generate 119 native ARM binaries on Linux, OS X, and Windows (with Cygwin) platforms.</p> 120 121 <p>It provides a set of system headers for stable native APIs that are guaranteed to be supported 122 in all later releases of the platform:</p> 123 124 <ul> 125 <li>libc (C library) headers</li> 126 127 <li>libm (math library) headers</li> 128 129 <li>JNI interface headers</li> 130 131 <li>libz (Zlib compression) headers</li> 132 133 <li>liblog (Android logging) header</li> 134 135 <li>OpenGL ES 1.1 and OpenGL ES 2.0 (3D graphics libraries) headers</li> 136 137 <li>libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).</li> 138 139 <li>A Minimal set of headers for C++ support</li> 140 141 <li>OpenSL ES native audio libraries</li> 142 143 <li>Android native application APIS</li> 144 </ul> 145 146 <p>The NDK also provides a build system that lets you work efficiently with your sources, without 147 having to handle the toolchain/platform/CPU/ABI details. You create very short build files to 148 describe which sources to compile and which Android application will use them — the build 149 system compiles the sources and places the shared libraries directly in your application 150 project.</p> 151 152 <p class="caution"><strong>Important:</strong> With the exception of the libraries listed above, 153 native system libraries in the Android platform are <em>not</em> stable and may change in future 154 platform versions. Your applications should <em>only</em> make use of the stable native system 155 libraries provided in this NDK.</p> 156 157 <h3 id="docs">Documentation</h3> 158 159 <p>The NDK package includes a set of documentation that describes the capabilities of the NDK and 160 how to use it to create shared libraries for your Android applications. In this release, the 161 documentation is provided only in the downloadable NDK package. You can find the documentation in 162 the <code><ndk>/docs/</code> directory. Included are these files:</p> 163 164 <ul> 165 <li> 166 INSTALL.HTML — describes how to install the NDK and configure it for your host 167 system</li> 168 169 <li>OVERVIEW.HTML — provides an overview of the NDK capabilities and usage</li> 170 171 <li>ANDROID-MK.HTML — describes the use of the Android.mk file, which defines the native 172 sources you want to compile</li> 173 174 <li>APPLICATION-MK.HTML — describes the use of the Application.mk file, which describes 175 the native sources required by your Android application</li> 176 <li>CPLUSPLUS-SUPPORT.HTML — describes the C++ support provided in the Android NDK</li> 177 <li>CPU-ARCH-ABIS.HTML — a description of supported CPU architectures and how to target 178 them.</li> 179 180 <li>CPU-FEATURES.HTML — a description of the <code>cpufeatures</code> static library that 181 lets your application code detect the target device's CPU family and the optional features at 182 runtime.</li> 183 184 <li>CPU-ARM-NEON.HTML — a description of how to build with optional ARM NEON / VFPv3-D32 185 instructions.</li> 186 187 <li>CHANGES.HTML — a complete list of changes to the NDK across all releases.</li> 188 189 <li>DEVELOPMENT.HTML — describes how to modify the NDK and generate release packages for it</li> 190 191 <li>HOWTO.HTML — information about common tasks associated with NDK development</li> 192 193 <li>IMPORT-MODULE.HTML — describes how to share and reuse modules</li> 194 195 <li>LICENSES.HTML — information about the various open source licenses that govern the Android NDK</li> 196 197 <li>NATIVE-ACTIVITY.HTML — describes how to implement native activities</li> 198 199 <li>NDK-BUILD.HTML — describes the usage of the ndk-build script</li> 200 201 <li>NDK-GDB.HTML — describes how to use the native code debugger</li> 202 203 <li>PREBUILTS.HTML — information about how shared and static prebuilt libraries work </li> 204 205 <li>STANDALONE-TOOLCHAIN.HTML — describes how to use Android NDK toolchain as a standalone 206 compiler (still in beta).</li> 207 208 <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be 209 aware of, if you are developing using the NDK.</li> 210 211 <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the 212 NDK.</li> 213 214 </ul> 215 216 <p>Additionally, the package includes detailed information about the "bionic" C library provided 217 with the Android platform that you should be aware of, if you are developing using the NDK. You 218 can find the documentation in the <code><ndk>/docs/system/libc/</code> directory:</p> 219 220 <ul> 221 <li>OVERVIEW.HTML — provides an overview of the "bionic" C library and the features it 222 offers.</li> 223 </ul> 224 225 <h3 id="samples">Sample applications</h3> 226 227<p>The NDK includes sample applications that illustrate how to use native code in your Android 228 applications:</p> 229 230 <ul> 231 <li><code>hello-jni</code> — a simple application that loads a string from a native 232 method implemented in a shared library and then displays it in the application UI.</li> 233 234 <li><code>two-libs</code> — a simple application that loads a shared library dynamically 235 and calls a native method provided by the library. In this case, the method is implemented in a 236 static library imported by the shared library.</li> 237 238 <li><code>san-angeles</code> — a simple application that renders 3D graphics through the 239 native OpenGL ES APIs, while managing activity lifecycle with a {@link 240 android.opengl.GLSurfaceView} object.</li> 241 242 <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES 243 2.0 vertex and fragment shaders.</li> 244 245 <li><code>hello-neon</code> — a simple application that shows how to use the 246 <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics 247 if supported by the CPU. Specifically, the application implements two versions of a tiny 248 benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that 249 support it.</li> 250 251 <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the 252 pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses 253 this to generate an old-school "plasma" effect.</li> 254 255 <li><code>native-activity</code> — a simple application that demonstrates how to use the 256 native-app-glue static library to create a native activity</li> 257 258 <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native 259 activity.</li> 260 </ul> 261 262 <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk 263 and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> 264 and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> 265 266 <p>You can build the shared libraries for the sample apps by going into 267 <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. 268 The generated shared libraries will be located under 269 <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or 270 <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> 271 272 <p>Next, build the sample Android applications that use the shared libraries:</p> 273 274 <ul> 275 <li>If you are developing in Eclipse with ADT, use the New Project Wizard to create a new 276 Android project for each sample, using the "Import from Existing Source" option and importing 277 the source from <code><ndk>/apps/<app_name>/project/</code>. Then, set up an AVD, 278 if necessary, and build/run the application in the emulator. For more information about 279 creating a new Android project in Eclipse, see <a href= 280 "{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse</a>.</li> 281 282 <li>If you are developing with Ant, use the <code>android</code> tool to create the build file 283 for each of the sample projects at <code><ndk>/apps/<app_name>/project/</code>. 284 Then set up an AVD, if necessary, build your project in the usual way, and run it in the 285 emulator. For more information, see <a href= 286 "{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> 287 </ul> 288 289 <h4 id="hello-jni">Exploring the hello-jni Sample</h4> 290 291 <p>The hello-jni sample is a simple demonstration on how to use JNI from an Android application. 292 The HelloJni activity receives a string from a simple C function and displays it in a 293 TextView.</p> 294 295 <p>The main components of the sample include:</p> 296 297 <ul> 298 <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> 299 file, a <code>src/</code> and <code>res</code> directories, and a main activity)</li> 300 301 <li>A <code>jni/</code> directory that includes the implemented source file for the native code 302 as well as the Android.mk file</li> 303 304 <li>A <code>tests/</code> directory that contains unit test code.</li> 305 </ul> 306 307 <ol> 308 <li>Create a new project in Eclipse from the existing sample source or use the 309 <code>android</code> tool to update the project so it generates a build.xml file that you can 310 use to build the sample. 311 312 <ul> 313 <li>In Eclipse: 314 315 <ol type="a"> 316 <li>Click <strong>File > New Android Project...</strong></li> 317 318 <li>Select the <strong>Create project from existing source</strong> radio button.</li> 319 320 <li>Select any API level above Android 1.5.</li> 321 322 <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select 323 the <code><ndk-root>/samples/hello-jni</code> directory.</li> 324 325 <li>Click <strong>Finish</strong>.</li> 326 </ol> 327 </li> 328 329 <li>On the command line: 330 331 <ol type="a"> 332 <li>Change to the <code><ndk-root>/samples/hello-jni</code> directory.</li> 333 334 <li>Run the following command to generate a build.xml file: 335 <pre class="no-pretty-print">android update project -p . -s</pre> 336 </li> 337 </ol> 338 </li> 339 </ul> 340 </li> 341 342 <li>Compile the native code using the <code>ndk-build</code> command. 343 <pre class="no-pretty-print"> 344cd <ndk-root>/samples/hello-jni 345<ndk_root>/ndk-build 346</pre> 347 </li> 348 349 <li>Build and install the application as you would a normal Android application. If you are 350 using Eclipse, run the application to build and install it on a device. If you are using Ant, 351 run the following commands from the project directory: 352 <pre class="no-pretty-print"> 353ant debug 354adb install bin/HelloJni-debug.apk 355</pre> 356 </li> 357 </ol> 358 359 <p>When you run the application on the device, the string <code>Hello JNI</code> should appear on 360 your device. You can explore the rest of the samples that are located in the 361 <code><ndk-root>/samples</code> directory for more examples on how to use the JNI.</p> 362 363 <h4 id="native-activity">Exploring the native-activity Sample Application</h4> 364 365 <p>The native-activity sample provided with the Android NDK demonstrates how to use the 366 android_native_app_glue static library. This static library makes creating a native activity 367 easier by providing you with an implementation that handles your callbacks in another thread, so 368 you do not have to worry about them blocking your main UI thread. The main parts of the sample 369 are described below:</p> 370 371 <ul> 372 <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> 373 file, a <code>src/</code> and <code>res</code> directories). The AndroidManifest.xml declares 374 that the application is native and specifies the .so file of the native activity. See {@link 375 android.app.NativeActivity} for the source or see the 376 <code><ndk_root>/platforms/samples/native-activity/AndroidManifest.xml</code> file.</li> 377 378 <li>A <code>jni/</code> directory contains the native activity, main.c, which uses the 379 <code>android_native_app_glue.h</code> interface to implement the activity. The Android.mk that 380 describes the native module to the build system also exists here.</li> 381 </ul> 382 383 <p>To build this sample application:</p> 384 385 <ol> 386 <li>Create a new project in Eclipse from the existing sample source or use the 387 <code>android</code> tool to update the project so it generates a build.xml file that you can 388 use to build the sample. 389 390 <ul> 391 <li>In Eclipse: 392 393 <ol type="a"> 394 <li>Click <strong>File > New Android Project...</strong></li> 395 396 <li>Select the <strong>Create project from existing source</strong> radio button.</li> 397 398 <li>Select any API level above Android 2.3.</li> 399 400 <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select 401 the <code><ndk-root>/samples/native-activity</code> directory.</li> 402 403 <li>Click <strong>Finish</strong>.</li> 404 </ol> 405 </li> 406 407 <li>On the command line: 408 409 <ol type="a"> 410 <li>Change to the <code><ndk-root>/samples/native-activity</code> directory.</li> 411 412 <li>Run the following command to generate a build.xml file: 413 <pre class="no-pretty-print"> 414android update project -p . -s 415</pre> 416 </li> 417 </ol> 418 </li> 419 </ul> 420 </li> 421 422 <li>Compile the native code using the <code>ndk-build</code> command. 423 <pre class="no-pretty-print"> 424cd <ndk-root>/platforms/samples/android-9/samples/native-activity 425<ndk_root>/ndk-build 426</pre> 427 </li> 428 429 <li>Build and install the application as you would a normal Android application. If you are 430 using Eclipse, run the application to build and install it on a device. If you are using Ant, 431 run the following commands in the project directory, then run the application on the device: 432 <pre class="no-pretty-print"> 433ant debug 434adb install bin/NativeActivity-debug.apk 435</pre> 436 </li> 437 </ol> 438 439 440 <h2 id="reqs">System and Software Requirements</h2> 441 442 <p>The sections below describe the system and software requirements for using the Android NDK, as 443 well as platform compatibility considerations that affect appplications using libraries produced 444 with the NDK.</p> 445 446 <h4>The Android SDK</h4> 447 448 <ul> 449 <li>A complete Android SDK installation (including all dependencies) is required.</li> 450 451 <li>Android 1.5 SDK or later version is required.</li> 452 </ul> 453 454 <h4>Supported operating systems</h4> 455 456 <ul> 457 <li>Windows XP (32-bit) or Vista (32- or 64-bit)</li> 458 459 <li>Mac OS X 10.4.8 or later (x86 only)</li> 460 461 <li>Linux (32- or 64-bit, tested on Linux Ubuntu Dapper Drake)</li> 462 </ul> 463 464 <h4>Required development tools</h4> 465 466 <ul> 467 <li>For all development platforms, GNU Make 3.81 or later is required. Earlier versions of GNU 468 Make might work but have not been tested.</li> 469 470 <li>A recent version of awk (either GNU Awk or Nawk) is also required.</li> 471 472 <li>For Windows, <a href="http://www.cygwin.com">Cygwin</a> 1.7 or higher is required. The NDK 473 will <em>not</em> work with Cygwin 1.5 installations.</li> 474 </ul> 475 476 <h4>Android platform compatibility</h4> 477 478 <ul> 479 <li>The native libraries created by the Android NDK can only be used on devices running the 480 Android 1.5 platform version or later. This is due to toolchain and ABI related changes that 481 make the native libraries incompatible with 1.0 and 1.1 system images.</li> 482 483 <li>For this reason, you should use native libraries produced with the NDK in applications that 484 are deployable to devices running the Android 1.5 platform version or later.</li> 485 486 <li>To ensure compatibility, an application using a native library produced with the NDK 487 <em>must</em> declare a <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code> 488 <uses-sdk></code></a> element in its manifest file, with an 489 <code>android:minSdkVersion</code> attribute value of "3" or higher. For example: 490 <pre style="margin:1em;"> 491<manifest> 492 <uses-sdk android:minSdkVersion="3" /> 493 ... 494</manifest> 495</pre> 496 </li> 497 498 <li>If you use this NDK to create a native library that uses the OpenGL ES APIs, the 499 application containing the library can be deployed only to devices running the minimum platform 500 versions described in the table below. To ensure compatibility, make sure that your application 501 declares the proper <code>android:minSdkVersion</code> attribute value, as given in the 502 table.</li> 503 504 <li style="list-style: none; display: inline"> 505 <table style="margin:1em;"> 506 <tr> 507 <th>OpenGL ES Version Used</th> 508 509 <th>Compatible Android Platform(s)</th> 510 511 <th>Required uses-sdk Attribute</th> 512 </tr> 513 514 <tr> 515 <td>OpenGL ES 1.1</td> 516 517 <td>Android 1.6 and higher</td> 518 519 <td><code>android:minSdkVersion="4"</code></td> 520 </tr> 521 522 <tr> 523 <td>OpenGL ES 2.0</td> 524 525 <td>Android 2.0 and higher</td> 526 527 <td><code>android:minSdkVersion="5"</code></td> 528 </tr> 529 </table> 530 531 <p>For more information about API Level and its relationship to Android platform versions, 532 see <a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.</p> 533 </li> 534 535 <li>Additionally, an application using the OpenGL ES APIs should declare a 536 <code><uses-feature></code> element in its manifest, with an 537 <code>android:glEsVersion</code> attribute that specifies the minimum OpenGl ES version 538 required by the application. This ensures that Android Market will show your application only 539 to users whose devices are capable of supporting your application. For example: 540 <pre style="margin:1em;"> 541<manifest> 542<!-- Declare that the application uses the OpenGL ES 2.0 API and is designed 543 to run only on devices that support OpenGL ES 2.0 or higher. --> 544 <uses-feature android:glEsVersion="0x00020000" /> 545 ... 546</manifest> 547</pre> 548 549 <p>For more information, see the <a href= 550 "{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> 551 documentation.</p> 552 </li> 553 554 <li>If you use this NDK to create a native library that uses the API to access Android {@link 555 android.graphics.Bitmap} pixel buffers or utilizes native activities, the application 556 containing the library can be deployed only to devices running Android 2.2 (API level 8) or 557 higher. To ensure compatibility, make sure that your application declares <code><uses-sdk 558 android:minSdkVersion="8" /></code> attribute value in its manifest.</li> 559 </ul> 560