1<html><body><pre>Android NDK Overview 2 3Introduction: 4 5The Android NDK is a set of tools that allows Android application developers 6to embed native machine code compiled from C and/or C++ source files into 7their application packages. 8 9IMPORTANT: 10 The Android NDK can only be used to target Android system images 11 running Cupcake (a.k.a 1.5) or later versions of the platform. 12 13 1.0 and 1.1 system images are specifically *not* supported due to 14 subtle ABI and toolchain changes that happened for the 1.5 release. 15 16 17I. Android NDK Goals: 18--------------------- 19 20The Android VM allows your application's source code to call methods 21implemented in native code through the JNI. In a nutshell, this means that: 22 23 - Your application's source code will declare one or more methods 24 with the 'native' keyword to indicate that they are implemented through 25 native code. E.g.: 26 27 native byte[] loadFile(String filePath); 28 29 - You must provide a native shared library that contains the 30 implementation of these methods, which will be packaged into your 31 application's .apk. This library must be named according to standard 32 Unix conventions as lib<something>.so, and shall contain a standard JNI 33 entry point (more on this later). For example: 34 35 libFileLoader.so 36 37 - Your application must explicitly load the library. For example, to load 38 it at application start-up, simply add the following to its source code: 39 40 static { 41 System.loadLibrary("FileLoader"); 42 } 43 44 Note that you should not use the 'lib' prefix and '.so' suffix here. 45 46 47The Android NDK is a complement to the Android SDK that helps you to: 48 49 - Generate JNI-compatible shared libraries that can run on the Android 50 1.5 platform (and later) running on ARM CPUs. 51 52 - Copy the generated shared libraries to a proper location of your 53 application project path, so they will be automatically added to your 54 final (and signed) .apks 55 56 - In later revisions of the NDK, we intend to provide tools that help 57 debug your native code through a remote gdb connection and as much 58 source/symbol information as possible. 59 60Moreover, the Android NDK provides: 61 62 - A set of cross-toolchains (compilers, linkers, etc..) that can 63 generate native ARM binaries on Linux, OS X and Windows (with Cygwin) 64 65 - A set of system headers corresponding to the list of stable native APIs 66 supported by the Android platform. This corresponds to definitions that 67 are guaranteed to be supported in all later releases of the platform. 68 69 They are documented in the file docs/STABLE-APIS.html 70 71 IMPORTANT: 72 Keep in mind that most of the native system libraries in Android system 73 images are not frozen and might changed drastically, or even deleted, 74 in later updates and releases of the platform. 75 76 - A build system that allow developers to only write very short build files 77 to describe which sources need to be compiled, and how. The build system 78 deals with all the hairy toolchain/platform/CPU/ABI specifics. Moreover, 79 later updates of the NDK can add support for more toolchains, platforms, 80 system interfaces without requiring changes in the developer's build 81 files (more on this later). 82 83 84II. Android NDK Non-Goals: 85-------------------------- 86 87The NDK is *not* a good way to write generic native code that runs on Android 88devices. In particular, your applications should still be written in the Java 89programming language, handle Android system events appropriately to avoid the 90"Application Not Responding" dialog or deal with the Android application 91life-cycle. 92 93Note however that is is possible to write a sophisticated application in 94native code with a small "application wrapper" used to start/stop it 95appropriately. 96 97A good understanding of JNI is highly recommended, since many operations 98in this environment require specific actions from the developers, that are 99not necessarily common in typical native code. These include: 100 101 - Not being able to directly access the content of VM objects through 102 direct native pointers. E.g. you cannot safely get a pointer to a 103 String object's 16-bit char array to iterate over it in a loop. 104 105 - Requiring explicit reference management when the native code wants to 106 keep handles to VM objects between JNI calls. 107 108 109The NDK only provides system headers for a very limited set of native 110APIs and libraries supported by the Android platform. While a typical 111Android system image includes many native shared libraries, these should 112be considered an implementation detail that might change drastically between 113updates and releases of the platform. 114 115If an Android system library is not explicitly supported by the NDK 116headers, then applications should not depend on it being available, or 117they risk breaking after the next over-the-air system update on various 118devices. 119 120Selected system libraries will gradually be added to the set of stable NDK 121APIs. 122 123 124III. NDK development in practice: 125--------------------------------- 126 127Here's a very rough overview of how you can develop native code with the 128Android NDK: 129 130 1/ Place your native sources under $PROJECT/jni/... 131 132 2/ Write $PROJECT/jni/Android.mk to describe your sources 133 to the NDK build system 134 135 3/ Optional: write $PROJECT/jni/Application.mk to describe your 136 project in more details to the build system. You don't need 137 one to get started though, but this allows you to target 138 more than one CPU or override compiler/linker flags 139 (see docs/APPLICATION-MK.html for all details). 140 141 4/ Build your native code by running "$NDK/ndk-build" from your 142 project directory, or any of its sub-directories. 143 144The last step will copy, in case of success, the stripped shared libraries 145your application needs to your application's root project directory. You 146will then need to generate your final .apk through the usual means. 147 148Now, for a few more details: 149 150 151III.1/ Configuring the NDK: 152- - - - - - - - - - - - - - 153 154Previous releases required that you run the 'build/host-setup.sh' 155script to configure your NDK. This step has been removed completely 156in release 4 (a.k.a. NDK r4). 157 158 159III.2/ Placing C and C++ sources: 160- - - - - - - - - - - - - - - - - 161 162Place your native sources under the following directory: 163 164 $PROJECT/jni/ 165 166Where $PROJECT corresponds to the path of your Android application 167project. 168 169You are pretty free to organize the content of 'jni' as you want, 170the directory names and structure here will not influence the final 171generated application packages, so you don't have to use pseudo-unique 172names like com.<mycompany>.<myproject> as is the case for application 173package names. 174 175Note that C and C++ sources are supported. The default C++ file extensions 176supported by the NDK is '.cpp', but other extensions can be handled as well 177(see docs/ANDROID-MK.html for details). 178 179It is possible to store your sources in a different location by adjusting 180your Android.mk file (see below). 181 182 183III.3/ Writing an Android.mk build script: 184- - - - - - - - - - - - - - - - - - - - - - 185 186An Android.mk file is a small build script that you write to describe your 187sources to the NDK build system. Its syntax is described in details in 188the file docs/ANDROID-MK.html. 189 190In a nutshell, the NDK groups your sources into "modules", where each module 191can be one of the following: 192 193 - a static library 194 - a shared library 195 196You can define several modules in a single Android.mk, or you can write 197several Android.mk files, each one defining a single module. 198 199Note that a single Android.mk might be parsed several times by the build 200system so don't assume that certain variables are not defined in them. 201By default, the NDK will look for the following build script: 202 203 $PROJECT/jni/Android.mk 204 205If you want to define Android.mk files in sub-directories, you should 206include them explicitly in your top-level Android.mk. There is even 207a helper function to do that, i.e. use: 208 209 include $(call all-subdir-makefiles) 210 211This will include all Android.mk files in sub-directories of the current 212build file's path. 213 214 215III.4/ Writing an Application.mk build file (optional): 216- - - - - - - - - - - - - - - - - - - - - - - - - - - - 217 218While an Android.mk file describes your modules to the build system, the 219Application.mk file describes your application itself. See the 220docs/APPLICATION-MK.html document to understand what this file allows you 221to do. This includes, among others: 222 223 - The exact list of modules required by your application. 224 225 - The CPU architecture(s) to generate machine code for. 226 227 - Optional information, like whether you want a release or debug 228 build, specific C or C++ compiler flags and others that should 229 apply to all modules being built. 230 231This file is optional: by default the NDK will provide one that simply 232builds *all* the modules listed from your Android.mk (and all the makefiles 233it includes) and target the default CPU ABI (armeabi). 234 235There are two ways to use an Application.mk: 236 237 - Place it under $PROJECT/jni/Application.mk, and it will be picked 238 up automatically by the 'ndk-build' script (more on this later) 239 240 - Place it under $NDK/apps/<name>/Application.mk, where $NDK 241 points to your NDK installation path. After that, launch 242 "make APP=<name>" from the NDK directory. 243 244 This was the way this file was used before Android NDK r4. 245 It is still supported for compatibility reasons, but we strongly 246 encourage you to use the first method instead, since it is much 247 simpler and doesn't need modifying / changing directories of the 248 NDK installation tree. 249 250Again, see docs/APPLICATION-MK.html for a complete description of its 251content. 252 253 254III.5/ Invoke the NDK build system: 255- - - - - - - - - - - - - - - - - - 256 257The preferred way to build machine code with the NDK is to use the 258'ndk-build' script introduced with Android NDK r4. You can also use 259a second, legacy, method that depends on creating a '$NDK/apps' subdirectory. 260 261In both cases, a successful build will copy the final stripped binary modules 262(i.e. shared libraries) required by your application to your application's 263project path (Note that unstripped versions are kept for debugging 264purposes, there is no need to copy unstripped binaries to a device). 265 266 267 1: Using the 'ndk-build' command: 268 --------------------------------- 269 270 The 'ndk-build' script, located at the top of the NDK installation path 271 can be invoked directly from your application project directory (i.e. the 272 one where your AndroidManifest.xml is located) or any of its sub-directories. 273 For example: 274 275 cd $PROJECT 276 $NDK/ndk-build 277 278 This will launch the NDK build scripts, which will automatically probe your 279 development system and application project file to determine what to build. 280 281 For example: 282 283 ndk-build 284 ndk-build clean --> clean generated binaries 285 ndk-build -B V=1 --> force complete rebuild, showing commands 286 287 By default, it expects an optional file under $PROJECT/jni/Application.mk, 288 and a required $PROJECT/jni/Android.mk. 289 290 On success, this will copy the generated binary modules (i.e. shared 291 libraries) to the appropriate location in your project tree. You can later 292 rebuild the full Android application package either through the usual 293 'ant' command, or the ADT Eclipse plug-in. 294 295 See docs/NDK-BUILD.html for a more complete description of what this script 296 does and which options it can take. 297 298 299 2: Using the $NDK/apps/<name>/Application.mk: 300 --------------------------------------------- 301 302 This build method was the only one before Android NDK r4 and is only 303 supported for compatibility reason. We strongly recommend you to migrate 304 to using the 'ndk-build' command as soon as possible, since we may remove 305 legacy support in a later NDK release. 306 307 It requires the following: 308 309 1. Creating a sub-directory named $NDK/apps/<name>/ under 310 your NDK installation directory (not your project path). 311 312 Where <name> is an arbitrary name to describe your application 313 to the NDK build system (no spaces allowed). 314 315 2. Write $NDK/apps/<name>/Application.mk, which then requires 316 a definition for APP_PROJECT_PATH that points to your 317 application project directory. 318 319 3. Go to the NDK installation path on the command line then 320 invoke the top-level GNUMakefile, as in: 321 322 cd $NDK 323 make APP=<name> 324 325 The result will be equivalent to the first method, except for the fact 326 that intermediate generated files will be placed under $NDK/out/apps/<name>/ 327 328 329IV. Rebuild your application package: 330- - - - - - - - - - - - - - - - - - - 331 332After generating the binaries with the NDK, you need to rebuild your 333Android application package files (.apk) using the normal means, i.e. 334either using the 'ant' command or the ADT Eclipse plug-in. 335 336See the Android SDK documentation for more details. The new .apk will 337embed your shared libraries, and they will be extracted automatically 338at installation time by the system when you install the package on a 339target device. 340 341 342V. Debugging support: 343- - - - - - - - - - - 344 345The NDK provides a helper script, named 'ndk-gdb' to very easily launch 346a native debugging session of your applications. 347 348Native debugging can *ONLY* be performed on production devices running 349Android 2.2 or higher, and does not require root or privileged access, as 350long as your application is debuggable. 351 352For more information, read docs/NDK-GDB.html. In a nutshell, native debugging 353follows this simple scheme: 354 355 1. Ensure your application is debuggable (e.g. set android:debuggable 356 to "true" in your AndroidManifest.xml) 357 358 2. Build your application with 'ndk-build', then install it on your 359 device/emulator. 360 361 3. Launch your application. 362 363 4. Run 'ndk-gdb' from your application project directory. 364 365You will get a gdb prompt. See the GDB User Manual for a list of useful 366commands. 367</pre></body></html> 368