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 the following instruction sets:</p> 50 51 <ul> 52 <li>ARMv5TE, including Thumb-1 instructions (see {@code docs/CPU-ARCH-ABIS.html} for more 53information)</li> 54 55 <li>ARMv7-A, including Thumb-2 and VFPv3-D16 instructions, with optional support for 56 NEON/VFPv3-D32 instructions (see {@code docs/CPU-ARM-NEON.html} for more information)</li> 57 58 <li>x86 instructions (see {@code docs/CPU-X86.html} for more information)</li> 59 60 <li>MIPS instructions (see {@code docs/CPU-MIPS.html} for more information)</li> 61 </ul> 62 63 <p>ARMv5TE machine code will run on all ARM-based Android devices. ARMv7-A will run only on 64 devices such as the Verizon Droid or Google Nexus One that have a compatible CPU. The main 65 difference between the two instruction sets is that ARMv7-A supports hardware FPU, Thumb-2, and 66 NEON instructions. You can target either or both of the instruction sets — ARMv5TE is the 67 default, but switching to ARMv7-A is as easy as adding a single line to the application's 68 <code>Application.mk</code> file, without needing to change anything else in the file. You can also build for 69 both architectures at the same time and have everything stored in the final <code>.apk</code>. 70 Complete information is provided in the CPU-ARCH-ABIS.HTML in the NDK package.</p> 71 72 <p>The NDK provides stable headers for libc (the C library), libm (the Math library), OpenGL ES 73 (3D graphics library), the JNI interface, and other libraries, as listed in the <a href= 74 "#tools">Development Tools</a> section.</p> 75 76 <h2 id="choosing">When to Develop in Native Code</h2> 77 78 <p>The NDK will not benefit most applications. As a developer, you need to balance its benefits 79 against its drawbacks; notably, using native code does not result in an automatic performance 80 increase, but always increases application complexity. In general, you should only use native 81 code if it is essential to your application, not just because you prefer to program in C/C++.</p> 82 83 <p>Typical good candidates for the NDK are self-contained, CPU-intensive operations that don't 84 allocate much memory, such as signal processing, physics simulation, and so on. Simply re-coding 85 a method to run in C usually does not result in a large performance increase. When examining 86 whether or not you should develop in native code, think about your requirements and see if the 87 Android framework APIs provide the functionality that you need. The NDK can, however, can be an 88 effective way to reuse a large corpus of existing C/C++ code.</p> 89 90 <p>The Android framework provides two ways to use native code:</p> 91 92 <ul> 93 <li>Write your application using the Android framework and use JNI to access the APIs provided 94 by the Android NDK. This technique allows you to take advantage of the convenience of the 95 Android framework, but still allows you to write native code when necessary. If you use this 96 approach, your application must target specific, minimum Android platform levels, see <a 97 href="#platform-compat">Android platform compatibility</a> for more information.</li> 98 99 <li> 100 <p>Write a native activity, which allows you to implement the lifecycle callbacks in native 101 code. The Android SDK provides the {@link android.app.NativeActivity} class, which is a 102 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 (partial listing):</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>CHANGES.HTML — a complete list of changes to the NDK across all releases.</li> 185 186 <li>DEVELOPMENT.HTML — describes how to modify the NDK and generate release packages for it</li> 187 188 <li>HOWTO.HTML — information about common tasks associated with NDK development</li> 189 190 <li>IMPORT-MODULE.HTML — describes how to share and reuse modules</li> 191 192 <li>LICENSES.HTML — information about the various open source licenses that govern the Android NDK</li> 193 194 <li>NATIVE-ACTIVITY.HTML — describes how to implement native activities</li> 195 196 <li>NDK-BUILD.HTML — describes the usage of the ndk-build script</li> 197 198 <li>NDK-GDB.HTML — describes how to use the native code debugger</li> 199 200 <li>PREBUILTS.HTML — information about how shared and static prebuilt libraries work </li> 201 202 <li>STANDALONE-TOOLCHAIN.HTML — describes how to use Android NDK toolchain as a standalone 203 compiler (still in beta).</li> 204 205 <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be 206 aware of, if you are developing using the NDK.</li> 207 208 <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the 209 NDK.</li> 210 211 </ul> 212 213 <p>Additionally, the package includes detailed information about the "bionic" C library provided 214 with the Android platform that you should be aware of, if you are developing using the NDK. You 215 can find the documentation in the <code><ndk>/docs/system/libc/</code> directory:</p> 216 217 <ul> 218 <li>OVERVIEW.HTML — provides an overview of the "bionic" C library and the features it 219 offers.</li> 220 </ul> 221 222 <h3 id="samples">Sample applications</h3> 223 224<p>The NDK includes sample applications that illustrate how to use native code in your Android 225 applications:</p> 226 227 <ul> 228 <li><code>hello-jni</code> — a simple application that loads a string from a native 229 method implemented in a shared library and then displays it in the application UI.</li> 230 231 <li><code>two-libs</code> — a simple application that loads a shared library dynamically 232 and calls a native method provided by the library. In this case, the method is implemented in a 233 static library imported by the shared library.</li> 234 235 <li><code>san-angeles</code> — a simple application that renders 3D graphics through the 236 native OpenGL ES APIs, while managing activity lifecycle with a {@link 237 android.opengl.GLSurfaceView} object.</li> 238 239 <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES 240 2.0 vertex and fragment shaders.</li> 241 242 <li><code>hello-neon</code> — a simple application that shows how to use the 243 <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics 244 if supported by the CPU. Specifically, the application implements two versions of a tiny 245 benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that 246 support it.</li> 247 248 <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the 249 pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses 250 this to generate an old-school "plasma" effect.</li> 251 252 <li><code>native-activity</code> — a simple application that demonstrates how to use the 253 native-app-glue static library to create a native activity</li> 254 255 <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native 256 activity.</li> 257 </ul> 258 259 <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk 260 and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> 261 and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> 262 263 <p>You can build the shared libraries for the sample apps by going into 264 <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. 265 The generated shared libraries will be located under 266 <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or 267 <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> 268 269 <p>Next, build the sample Android applications that use the shared libraries:</p> 270 271 <ul> 272 <li>If you are developing in Eclipse with ADT, use the New Project Wizard to create a new 273 Android project for each sample, using the "Import from Existing Source" option and importing 274 the source from <code><ndk>/samples/<name>/</code>. Then, set up an AVD, 275 if necessary, and build/run the application in the emulator.</li> 276 277 <li>If you are developing with Ant, use the <code>android</code> tool to create the build file 278 for each of the sample projects at <code><ndk>/samples/<name>/</code>. 279 Then set up an AVD, if necessary, build your project in the usual way, and run it in the 280 emulator.</li> 281 282 </ul> 283 284 <p>For more information about developing with the Android SDK tools and what 285 you need to do to create, build, and run your applications, see 286 the <a href="{@docRoot}tools/workflow/index.html">Overview</a> 287 section for developing on Android.</p> 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; Ubuntu 8.04, or other Linux distributions using GLibc 2.7 or 462later)</li> 463 </ul> 464 465 <h4>Required development tools</h4> 466 467 <ul> 468 <li>For all development platforms, GNU Make 3.81 or later is required. Earlier versions of GNU 469 Make might work but have not been tested.</li> 470 471 <li>A recent version of awk (either GNU Awk or Nawk) is also required.</li> 472 473 <li>For Windows, <a href="http://www.cygwin.com">Cygwin</a> 1.7 or higher is required. The NDK 474 will <em>not</em> work with Cygwin 1.5 installations.</li> 475 </ul> 476 477 <h4 id="platform-compat">Android platform compatibility</h4> 478 479 <ul> 480 <li>The native libraries created by the Android NDK can only be used on devices running 481 specific minimum Android platform versions. The minimum required platform version depends on 482 the CPU architecture of the devices you are targeting. The following table details which 483 Android platform versions are compatible with native code developed for specific CPU 484 architectures. 485 486 <table style="margin:1em;"> 487 <tr> 488 <th>Native Code CPU Architecture Used</th> 489 <th>Compatible Android Platform(s)</th> 490 </tr> 491 492 <tr> 493 <td>ARM, ARM-NEON</td> 494 <td>Android 1.5 (API Level 3) and higher</td> 495 </tr> 496 497 <tr> 498 <td>x86</td> 499 <td>Android 2.3 (API Level 9) and higher</td> 500 </tr> 501 502 <tr> 503 <td>MIPS</td> 504 <td>Android 2.3 (API Level 9) and higher</td> 505 </tr> 506 </table> 507 508 <p>These requirements mean you can use native libraries produced with the NDK in 509 applications that are deployable to ARM-based devices running Android 1.5 or later. If you are 510 deploying native libraries to x86 and MIPS-based devices, your application must target Android 511 2.3 or later.</p> 512 </li> 513 514 <li>To ensure compatibility, an application using a native library produced with the NDK 515 <em>must</em> declare a <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code> 516 <uses-sdk></code></a> element in its manifest file, with an 517 <code>android:minSdkVersion</code> attribute value of "3" or higher. For example: 518 519<pre style="margin:1em;"> 520<manifest> 521 <uses-sdk android:minSdkVersion="3" /> 522 ... 523</manifest> 524</pre> 525 </li> 526 527 <li>If you use this NDK to create a native library that uses the OpenGL ES APIs, the 528 application containing the library can be deployed only to devices running the minimum platform 529 versions described in the table below. To ensure compatibility, make sure that your application 530 declares the proper <code>android:minSdkVersion</code> attribute value, as shown in the 531 following table.</li> 532 533 <li style="list-style: none; display: inline"> 534 <table style="margin:1em;"> 535 <tr> 536 <th>OpenGL ES Version Used</th> 537 538 <th>Compatible Android Platform(s)</th> 539 540 <th>Required uses-sdk Attribute</th> 541 </tr> 542 543 <tr> 544 <td>OpenGL ES 1.1</td> 545 546 <td>Android 1.6 (API Level 4) and higher</td> 547 548 <td><code>android:minSdkVersion="4"</code></td> 549 </tr> 550 551 <tr> 552 <td>OpenGL ES 2.0</td> 553 554 <td>Android 2.0 (API Level 5) and higher</td> 555 556 <td><code>android:minSdkVersion="5"</code></td> 557 </tr> 558 </table> 559 560 <p>For more information about API Level and its relationship to Android platform versions, 561 see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">Android API Levels</a>.</p> 562 </li> 563 564 <li>Additionally, an application using the OpenGL ES APIs should declare a 565 <code><uses-feature></code> element in its manifest, with an 566 <code>android:glEsVersion</code> attribute that specifies the minimum OpenGl ES version 567 required by the application. This ensures that Google Play will show your application only 568 to users whose devices are capable of supporting your application. For example: 569 <pre style="margin:1em;"> 570<manifest> 571<!-- Declare that the application uses the OpenGL ES 2.0 API and is designed 572 to run only on devices that support OpenGL ES 2.0 or higher. --> 573 <uses-feature android:glEsVersion="0x00020000" /> 574 ... 575</manifest> 576</pre> 577 578 <p>For more information, see the <a href= 579 "{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> 580 documentation.</p> 581 </li> 582 583 <li>If you use this NDK to create a native library that uses the API to access Android {@link 584 android.graphics.Bitmap} pixel buffers or utilizes native activities, the application 585 containing the library can be deployed only to devices running Android 2.2 (API level 8) or 586 higher. To ensure compatibility, make sure that your application declares <code><uses-sdk 587 android:minSdkVersion="8" /></code> attribute value in its manifest.</li> 588 </ul> 589