1 page.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)</li> 53 54 <li>ARMv7-A (including Thumb-2 and VFPv3-D16 instructions, with optional support for 55 NEON/VFPv3-D32 instructions)</li> 56 57 <li>x86 instructions (see CPU-ARCH-ABIS.HTML for more information)</li> 58 </ul> 59 60 <p>ARMv5TE machine code will run on all ARM-based Android devices. ARMv7-A will run only on 61 devices such as the Verizon Droid or Google Nexus One that have a compatible CPU. The main 62 difference between the two instruction sets is that ARMv7-A supports hardware FPU, Thumb-2, and 63 NEON instructions. You can target either or both of the instruction sets — ARMv5TE is the 64 default, but switching to ARMv7-A is as easy as adding a single line to the application's 65 <code>Application.mk</code> file, without needing to change anything else in the file. You can also build for 66 both architectures at the same time and have everything stored in the final <code>.apk</code>. 67 Complete information is provided in the CPU-ARCH-ABIS.HTML in the NDK package.</p> 68 69 <p>The NDK provides stable headers for libc (the C library), libm (the Math library), OpenGL ES 70 (3D graphics library), the JNI interface, and other libraries, as listed in the <a href= 71 "#tools">Development Tools</a> section.</p> 72 73 <h2 id="choosing">When to Develop in Native Code</h2> 74 75 <p>The NDK will not benefit most applications. As a developer, you need to balance its benefits 76 against its drawbacks; notably, using native code does not result in an automatic performance 77 increase, but always increases application complexity. In general, you should only use native 78 code if it is essential to your application, not just because you prefer to program in C/C++.</p> 79 80 <p>Typical good candidates for the NDK are self-contained, CPU-intensive operations that don't 81 allocate much memory, such as signal processing, physics simulation, and so on. Simply re-coding 82 a method to run in C usually does not result in a large performance increase. When examining 83 whether or not you should develop in native code, think about your requirements and see if the 84 Android framework APIs provide the functionality that you need. The NDK can, however, can be an 85 effective way to reuse a large corpus of existing C/C++ code.</p> 86 87 <p>The Android framework provides two ways to use native code:</p> 88 89 <ul> 90 <li>Write your application using the Android framework and use JNI to access the APIs provided 91 by the Android NDK. This technique allows you to take advantage of the convenience of the 92 Android framework, but still allows you to write native code when necessary. You can install 93 applications that use native code through the JNI on devices that run Android 1.5 or 94 later.</li> 95 96 <li> 97 <p>Write a native activity, which allows you to implement the lifecycle callbacks in native 98 code. The Android SDK provides the {@link android.app.NativeActivity} class, which is a convenience class that notifies your 99 native code of any activity lifecycle callbacks (<code>onCreate()</code>, <code>onPause()</code>, 100 <code>onResume()</code>, etc). You can implement the callbacks in your native code to handle 101 these events when they occur. Applications that use native activities must be run on Android 102 2.3 (API Level 9) or later.</p> 103 104 <p>You cannot access features such as Services and Content Providers natively, so if you want 105 to use them or any other framework API, you can still write JNI code to do so.</p> 106 </li> 107 </ul> 108 109 <h2 id="contents">Contents of the NDK</h2>The NDK contains the APIs, documentation, and sample 110 applications that help you write your native code. 111 112 <h3 id="tools">Development tools</h3> 113 114 <p>The NDK includes a set of cross-toolchains (compilers, linkers, etc..) that can generate 115 native ARM binaries on Linux, OS X, and Windows (with Cygwin) platforms.</p> 116 117 <p>It provides a set of system headers for stable native APIs that are guaranteed to be supported 118 in all later releases of the platform:</p> 119 120 <ul> 121 <li>libc (C library) headers</li> 122 123 <li>libm (math library) headers</li> 124 125 <li>JNI interface headers</li> 126 127 <li>libz (Zlib compression) headers</li> 128 129 <li>liblog (Android logging) header</li> 130 131 <li>OpenGL ES 1.1 and OpenGL ES 2.0 (3D graphics libraries) headers</li> 132 133 <li>libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).</li> 134 135 <li>A Minimal set of headers for C++ support</li> 136 137 <li>OpenSL ES native audio libraries</li> 138 139 <li>Android native application APIS</li> 140 </ul> 141 142 <p>The NDK also provides a build system that lets you work efficiently with your sources, without 143 having to handle the toolchain/platform/CPU/ABI details. You create very short build files to 144 describe which sources to compile and which Android application will use them — the build 145 system compiles the sources and places the shared libraries directly in your application 146 project.</p> 147 148 <p class="caution"><strong>Important:</strong> With the exception of the libraries listed above, 149 native system libraries in the Android platform are <em>not</em> stable and may change in future 150 platform versions. Your applications should <em>only</em> make use of the stable native system 151 libraries provided in this NDK.</p> 152 153 <h3 id="docs">Documentation</h3> 154 155 <p>The NDK package includes a set of documentation that describes the capabilities of the NDK and 156 how to use it to create shared libraries for your Android applications. In this release, the 157 documentation is provided only in the downloadable NDK package. You can find the documentation in 158 the <code><ndk>/docs/</code> directory. Included are these files:</p> 159 160 <ul> 161 <li> 162 INSTALL.HTML — describes how to install the NDK and configure it for your host 163 system</li> 164 165 <li>OVERVIEW.HTML — provides an overview of the NDK capabilities and usage</li> 166 167 <li>ANDROID-MK.HTML — describes the use of the Android.mk file, which defines the native 168 sources you want to compile</li> 169 170 <li>APPLICATION-MK.HTML — describes the use of the Application.mk file, which describes 171 the native sources required by your Android application</li> 172 <li>CPLUSPLUS-SUPPORT.HTML — describes the C++ support provided in the Android NDK</li> 173 <li>CPU-ARCH-ABIS.HTML — a description of supported CPU architectures and how to target 174 them.</li> 175 176 <li>CPU-FEATURES.HTML — a description of the <code>cpufeatures</code> static library that 177 lets your application code detect the target device's CPU family and the optional features at 178 runtime.</li> 179 180 <li>CPU-ARM-NEON.HTML — a description of how to build with optional ARM NEON / VFPv3-D32 181 instructions.</li> 182 183 <li>CHANGES.HTML — a complete list of changes to the NDK across all releases.</li> 184 185 <li>DEVELOPMENT.HTML — describes how to modify the NDK and generate release packages for it</li> 186 187 <li>HOWTO.HTML — information about common tasks associated with NDK development</li> 188 189 <li>IMPORT-MODULE.HTML — describes how to share and reuse modules</li> 190 191 <li>LICENSES.HTML — information about the various open source licenses that govern the Android NDK</li> 192 193 <li>NATIVE-ACTIVITY.HTML — describes how to implement native activities</li> 194 195 <li>NDK-BUILD.HTML — describes the usage of the ndk-build script</li> 196 197 <li>NDK-GDB.HTML — describes how to use the native code debugger</li> 198 199 <li>PREBUILTS.HTML — information about how shared and static prebuilt libraries work </li> 200 201 <li>STANDALONE-TOOLCHAIN.HTML — describes how to use Android NDK toolchain as a standalone 202 compiler (still in beta).</li> 203 204 <li>SYSTEM-ISSUES.HTML — known issues in the Android system images that you should be 205 aware of, if you are developing using the NDK.</li> 206 207 <li>STABLE-APIS.HTML — a complete list of the stable APIs exposed by headers in the 208 NDK.</li> 209 210 </ul> 211 212 <p>Additionally, the package includes detailed information about the "bionic" C library provided 213 with the Android platform that you should be aware of, if you are developing using the NDK. You 214 can find the documentation in the <code><ndk>/docs/system/libc/</code> directory:</p> 215 216 <ul> 217 <li>OVERVIEW.HTML — provides an overview of the "bionic" C library and the features it 218 offers.</li> 219 </ul> 220 221 <h3 id="samples">Sample applications</h3> 222 223 <p>The NDK includes sample applications that illustrate how to use native code in your Android 224 applications:</p> 225 226 <ul> 227 <li><code>hello-jni</code> — a simple application that loads a string from a native 228 method implemented in a shared library and then displays it in the application UI.</li> 229 230 <li><code>two-libs</code> — a simple application that loads a shared library dynamically 231 and calls a native method provided by the library. In this case, the method is implemented in a 232 static library imported by the shared library.</li> 233 234 <li><code>san-angeles</code> — a simple application that renders 3D graphics through the 235 native OpenGL ES APIs, while managing activity lifecycle with a {@link 236 android.opengl.GLSurfaceView} object.</li> 237 238 <li><code>hello-gl2</code> — a simple application that renders a triangle using OpenGL ES 239 2.0 vertex and fragment shaders.</li> 240 241 <li><code>hello-neon</code> — a simple application that shows how to use the 242 <code>cpufeatures</code> library to check CPU capabilities at runtime, then use NEON intrinsics 243 if supported by the CPU. Specifically, the application implements two versions of a tiny 244 benchmark for a FIR filter loop, a C version and a NEON-optimized version for devices that 245 support it.</li> 246 247 <li><code>bitmap-plasma</code> — a simple application that demonstrates how to access the 248 pixel buffers of Android {@link android.graphics.Bitmap} objects from native code, and uses 249 this to generate an old-school "plasma" effect.</li> 250 251 <li><code>native-activity</code> — a simple application that demonstrates how to use the 252 native-app-glue static library to create a native activity</li> 253 254 <li><code>native-plasma</code> — a version of bitmap-plasma implemented with a native 255 activity.</li> 256 </ul> 257 258 <p>For each sample, the NDK includes the corresponding C source code and the necessary Android.mk 259 and Application.mk files. There are located under <code><ndk>/samples/<name>/</code> 260 and their source code can be found under <code><ndk>/samples/<name>/jni/</code>.</p> 261 262 <p>You can build the shared libraries for the sample apps by going into 263 <code><ndk>/samples/<name>/</code> then calling the <code>ndk-build</code> command. 264 The generated shared libraries will be located under 265 <code><ndk>/samples/<name>/libs/armeabi/</code> for (ARMv5TE machine code) and/or 266 <code><ndk>/samples/<name>/libs/armeabi-v7a/</code> for (ARMv7 machine code).</p> 267 268 <p>Next, build the sample Android applications that use the shared libraries:</p> 269 270 <ul> 271 <li>If you are developing in Eclipse with ADT, use the New Project Wizard to create a new 272 Android project for each sample, using the "Import from Existing Source" option and importing 273 the source from <code><ndk>/apps/<app_name>/project/</code>. Then, set up an AVD, 274 if necessary, and build/run the application in the emulator.</li> 275 276 <li>If you are developing with Ant, use the <code>android</code> tool to create the build file 277 for each of the sample projects at <code><ndk>/apps/<app_name>/project/</code>. 278 Then set up an AVD, if necessary, build your project in the usual way, and run it in the 279 emulator.</li> 280 281 </ul> 282 283 <p>For more information about developing with the Android SDK tools and what 284 you need to do to create, build, and run your applications, see 285 the <a href="{@docRoot}guide/developing/index.html">Overview</a> 286 section for developing on Android.</p> 287 288 <h4 id="hello-jni">Exploring the hello-jni Sample</h4> 289 290 <p>The hello-jni sample is a simple demonstration on how to use JNI from an Android application. 291 The HelloJni activity receives a string from a simple C function and displays it in a 292 TextView.</p> 293 294 <p>The main components of the sample include:</p> 295 296 <ul> 297 <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> 298 file, a <code>src/</code> and <code>res</code> directories, and a main activity)</li> 299 300 <li>A <code>jni/</code> directory that includes the implemented source file for the native code 301 as well as the Android.mk file</li> 302 303 <li>A <code>tests/</code> directory that contains unit test code.</li> 304 </ul> 305 306 <ol> 307 <li>Create a new project in Eclipse from the existing sample source or use the 308 <code>android</code> tool to update the project so it generates a build.xml file that you can 309 use to build the sample. 310 311 <ul> 312 <li>In Eclipse: 313 314 <ol type="a"> 315 <li>Click <strong>File > New Android Project...</strong></li> 316 317 <li>Select the <strong>Create project from existing source</strong> radio button.</li> 318 319 <li>Select any API level above Android 1.5.</li> 320 321 <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select 322 the <code><ndk-root>/samples/hello-jni</code> directory.</li> 323 324 <li>Click <strong>Finish</strong>.</li> 325 </ol> 326 </li> 327 328 <li>On the command line: 329 330 <ol type="a"> 331 <li>Change to the <code><ndk-root>/samples/hello-jni</code> directory.</li> 332 333 <li>Run the following command to generate a build.xml file: 334 <pre class="no-pretty-print">android update project -p . -s</pre> 335 </li> 336 </ol> 337 </li> 338 </ul> 339 </li> 340 341 <li>Compile the native code using the <code>ndk-build</code> command. 342 <pre class="no-pretty-print"> 343 cd <ndk-root>/samples/hello-jni 344 <ndk_root>/ndk-build 345 </pre> 346 </li> 347 348 <li>Build and install the application as you would a normal Android application. If you are 349 using Eclipse, run the application to build and install it on a device. If you are using Ant, 350 run the following commands from the project directory: 351 <pre class="no-pretty-print"> 352 ant debug 353 adb install bin/HelloJni-debug.apk 354 </pre> 355 </li> 356 </ol> 357 358 <p>When you run the application on the device, the string <code>Hello JNI</code> should appear on 359 your device. You can explore the rest of the samples that are located in the 360 <code><ndk-root>/samples</code> directory for more examples on how to use the JNI.</p> 361 362 <h4 id="native-activity">Exploring the native-activity Sample Application</h4> 363 364 <p>The native-activity sample provided with the Android NDK demonstrates how to use the 365 android_native_app_glue static library. This static library makes creating a native activity 366 easier by providing you with an implementation that handles your callbacks in another thread, so 367 you do not have to worry about them blocking your main UI thread. The main parts of the sample 368 are described below:</p> 369 370 <ul> 371 <li>The familiar basic structure of an Android application (an <code>AndroidManifest.xml</code> 372 file, a <code>src/</code> and <code>res</code> directories). The AndroidManifest.xml declares 373 that the application is native and specifies the .so file of the native activity. See {@link 374 android.app.NativeActivity} for the source or see the 375 <code><ndk_root>/platforms/samples/native-activity/AndroidManifest.xml</code> file.</li> 376 377 <li>A <code>jni/</code> directory contains the native activity, main.c, which uses the 378 <code>android_native_app_glue.h</code> interface to implement the activity. The Android.mk that 379 describes the native module to the build system also exists here.</li> 380 </ul> 381 382 <p>To build this sample application:</p> 383 384 <ol> 385 <li>Create a new project in Eclipse from the existing sample source or use the 386 <code>android</code> tool to update the project so it generates a build.xml file that you can 387 use to build the sample. 388 389 <ul> 390 <li>In Eclipse: 391 392 <ol type="a"> 393 <li>Click <strong>File > New Android Project...</strong></li> 394 395 <li>Select the <strong>Create project from existing source</strong> radio button.</li> 396 397 <li>Select any API level above Android 2.3.</li> 398 399 <li>In the <strong>Location</strong> field, click <strong>Browse...</strong> and select 400 the <code><ndk-root>/samples/native-activity</code> directory.</li> 401 402 <li>Click <strong>Finish</strong>.</li> 403 </ol> 404 </li> 405 406 <li>On the command line: 407 408 <ol type="a"> 409 <li>Change to the <code><ndk-root>/samples/native-activity</code> directory.</li> 410 411 <li>Run the following command to generate a build.xml file: 412 <pre class="no-pretty-print"> 413 android update project -p . -s 414 </pre> 415 </li> 416 </ol> 417 </li> 418 </ul> 419 </li> 420 421 <li>Compile the native code using the <code>ndk-build</code> command. 422 <pre class="no-pretty-print"> 423 cd <ndk-root>/platforms/samples/android-9/samples/native-activity 424 <ndk_root>/ndk-build 425 </pre> 426 </li> 427 428 <li>Build and install the application as you would a normal Android application. If you are 429 using Eclipse, run the application to build and install it on a device. If you are using Ant, 430 run the following commands in the project directory, then run the application on the device: 431 <pre class="no-pretty-print"> 432 ant debug 433 adb install bin/NativeActivity-debug.apk 434 </pre> 435 </li> 436 </ol> 437 438 439 <h2 id="reqs">System and Software Requirements</h2> 440 441 <p>The sections below describe the system and software requirements for using the Android NDK, as 442 well as platform compatibility considerations that affect appplications using libraries produced 443 with the NDK.</p> 444 445 <h4>The Android SDK</h4> 446 447 <ul> 448 <li>A complete Android SDK installation (including all dependencies) is required.</li> 449 450 <li>Android 1.5 SDK or later version is required.</li> 451 </ul> 452 453 <h4>Supported operating systems</h4> 454 455 <ul> 456 <li>Windows XP (32-bit) or Vista (32- or 64-bit)</li> 457 458 <li>Mac OS X 10.4.8 or later (x86 only)</li> 459 460 <li>Linux (32 or 64-bit; Ubuntu 8.04, or other Linux distributions using GLibc 2.7 or 461 later)</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 Google Play 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
