1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 6 <meta http-equiv="X-UA-Compatible" content="IE=9"/> 7 <meta name="generator" content="Doxygen 1.8.5"/> 8 <title>NDK Programmer's Guide: Concepts</title> 9 <link href="tabs.css" rel="stylesheet" type="text/css"/> 10 <script type="text/javascript" src="jquery.js"></script> 11 <script type="text/javascript" src="dynsections.js"></script> 12 <link href="navtree.css" rel="stylesheet" type="text/css"/> 13 <script type="text/javascript" src="resize.js"></script> 14 <script type="text/javascript" src="navtree.js"></script> 15 <script type="text/javascript"> 16 $(document).ready(initResizable); 17 $(window).load(resizeHeight); 18 </script> 19 <link href="doxygen.css" rel="stylesheet" type="text/css" /> 20 </head> 21 <body> 22 <div id="top"><!-- do not remove this div, it is closed by doxygen! --> 23 <div id="titlearea"> 24 <table cellspacing="0" cellpadding="0"> 25 <tbody> 26 <tr style="height: 56px;"> 27 <td style="padding-left: 0.5em;"> 28 <div id="projectname">NDK Programmer's Guide 29 </div> 30 </td> 31 </tr> 32 </tbody> 33 </table> 34 </div> 35 <!-- end header part --> 36 <!-- Generated by Doxygen 1.8.5 --> 37 </div><!-- top --> 38 <div id="side-nav" class="ui-resizable side-nav-resizable"> 39 <div id="nav-tree"> 40 <div id="nav-tree-contents"> 41 <div id="nav-sync" class="sync"></div> 42 </div> 43 </div> 44 <div id="splitbar" style="-moz-user-select:none;" 45 class="ui-resizable-handle"> 46 </div> 47 </div> 48 <script type="text/javascript"> 49 $(document).ready(function(){initNavTree('md_1__concepts__concepts.html','');}); 50 </script> 51 <div id="doc-content"> 52 <div class="header"> 53 <div class="headertitle"> 54 <div class="title">Concepts </div> </div> 55 </div><!--header--> 56 <div class="contents"> 57 <div class="textblock"><ul style="list-style: none; "> 58 <li> 59 <a href="#bb">Before Beginning</a> </li> 60 <li> 61 <a href="#intro">Introduction</a> </li> 62 <li> 63 <a href="#hiw">Process</a> <ul style="list-style:none;"> 64 <li> 65 <a href="#mc">Main Components</a> </li> 66 <ul> 67 <li> 68 <a href="#ndk">ndk-build</a> </li> 69 <li> 70 <a href="#jav">Java</a> </li> 71 <li> 72 <a href="#nshl">Native shared libraries</a> </li> 73 <li> 74 <a href="#nstl">Native static libraries</a> </li> 75 <li> 76 <a href="#jni">Java Native Interface (JNI)</a> </li> 77 <li> 78 <a href="#abi">Application Binary Interface (ABI)</a> </li> 79 <li> 80 <a href="#man">Manifest</a> </li> 81 <li> 82 <a href="#and">Android.mk</a> </li> 83 <li> 84 <a href="#app">Application.mk</a> </li> 85 </ul> 86 <a href="#fl">Flow</a> </li> 87 </ul> 88 </li> 89 <li> 90 <p class="startli"><a href="#naa">Native Activities and Applications</a></p> 91 <p><a class="anchor" id="bb"></a> </p> 92 <h2>Before Beginning</h2> 93 <p></p> 94 <p>This guide assumes that you are:</p> 95 <ul> 96 <li>Already familiar with concepts inherent in native programming, and in <a 97 href="http://developer.android.com">development of Android apps</a>.</li> 98 <li>Working in <a href="http://developer.android.com/sdk/index.html">Eclipse, 99 and using the Android Development Tools ("ADT")</a>, except where otherwise 100 noted.</li> 101 </ul> 102 <p><a class="anchor" id="intro"></a> </p> 103 <h2>Introduction</h2> 104 <p></p> 105 <p>This section provides a high-level explanation of how the NDK works. The 106 Android NDK is a set of tools allowing you to embed C or C++ (native 107 code) into your Android apps. The ability to use native code in Android apps 108 can be particularly useful to developers who wish to do one or more of the 109 following:</p> 110 <ul> 111 <li>Port their apps between platforms.</li> 112 <li>Use existing libraries created by other developers (or provide their own 113 libraries to others).</li> 114 <li>Increase performance in certain cases, particularly computationally 115 intensive ones like games.</li> 116 </ul> 117 <p><br/> 118 </p> 119 <b>Important Notes:</b> The Android NDK can only be used to target Android 120 system images running Android 1.5 (API Level 3) or later. 121 122 The NDK only provides system headers for a very limited set of native 123 APIs and libraries supported by the Android platform. While a typical 124 Android system image includes many native shared libraries, you should 125 consider them an implementation detail that might change drastically 126 between platform releases. If the NDK headers do not explicitly support an 127 Android system library, then apps should not depend on its being 128 available; otherwise, the next over-the-air (OTA) system update may 129 break them. 130 131 <p><a class="anchor" id="hiw"></a> </p> 132 <h2>Process</h2> 133 <p>This section introduces the main components used in building a native 134 application for Android, and goes on to describe the flow of building and 135 packaging.</p> 136 <p><a class="anchor" id="mc"></a> </p> 137 <h3>Main components</h3> 138 <p></p> 139 <p>You should have an understanding of the following components, as you build 140 your app:</p> 141 <p><a class="anchor" id="ndk"></a></p> 142 <ul> 143 <li>ndk-build: The ndk-build script launches the build scripts at the heart of 144 the NDK. These scripts:<ul> 145 <li>Automatically probe your development system and app project file to 146 determine what to build.</li> 147 <li>Generate binaries.</li> 148 <li>Copy the binaries to your app's project path.</li> 149 </ul> 150 </li> 151 </ul> 152 <p>For more information, see the <a 153 href="./md_3__key__topics__building__chapter_1-section_8_ndk-build.html">ndk-build</a> section of this guide.</p> 154 <p><a class="anchor" id="jav"></a></p> 155 <ul> 156 <li>Java: From your Java source, the Android build process generates 157 <code>.dex</code> ("Dalvik EXecutable") files, which are what the Android OS 158 runs in the Dalvik Virtual Machine (DVM). Even if your app contains no 159 Java source code at all, the build process still generates a <code>.dex</code> 160 executable file within which the native component runs.</li> 161 </ul> 162 <p>When developing Java components, use the <code>native</code> keyword to 163 indicate methods implemented as native code. For example, the following 164 function declaration tells the compiler that the implementation is in a native 165 library:</p> 166 <pre class="fragment">public native int add(int x, int y); 167 </pre><p><a class="anchor" id="nshl"></a></p> 168 <ul> 169 <li>Native shared libraries: The NDK builds these libraries, or 170 <code>.so</code> files, from your native source code.</li> 171 </ul> 172 <br> 173 <b>Note:</b> If two libraries implement the same method, with the same name, a 174 link 175 error occurs. 176 </pre><p><a class="anchor" id="nstl"></a></p> 177 <ul> 178 <li>Native static libraries: The NDK can also build static libraries, or 179 <code>.a</code> files, which you can link against other libraries.</li> 180 </ul> 181 <p><a class="anchor" id="jni"></a></p> 182 <ul> 183 <li>Java Native Interface ("JNI"): The JNI is the interface via which the Java 184 and C++ components talk to one another. This guide assumes knowledge of the 185 JNI; for information about it, consult the <a 186 href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html 187 ">Java Native Interface Specification</a>.</li> 188 </ul> 189 <p><a class="anchor" id="abi"></a></p> 190 <ul> 191 <li>Application Binary Interface ("ABI"): The ABI defines exactly how your 192 app's machine code is expected to interact with the system at runtime. The NDK 193 builds <code>.so</code> files against these definitions. Different ABIs 194 correspond to different architectures: The NDK includes ABI support for ARMEABI 195 (default), MIPS, and x86. For more information, see <a 196 href="./md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">Supported ABIs</a>.</li> 197 </ul> 198 <p><a class="anchor" id="man"></a></p> 199 <ul> 200 <li>Manifest: If you are writing an app with no Java component to it, you must 201 declare the NativeActivity class in the <a 202 href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">manifest</a>. The <a href=#naa>Native Activity</a> section provides more detail 203 on how to do this, under Using the native-activity.h interface.</li> 204 </ul> 205 <br> 206 <b>Note:</b> The following two items only apply in cases in which you are using 207 the 208 toolchains provided with the Android NDK as standalone compilers. 209 <p><a class="anchor" id="and"></a></p> 210 <ul> 211 <li><code>Android.mk</code>: You must create an <code>Android.mk</code> 212 configuration file inside your <code>jni</code> folder. The ndk-build script 213 looks at this file, which defines the module and its name, the source files to 214 be compiled, build flags and libraries to link. For more information, see the 215 <a 216 href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> section of this document.</li> 217 </ul> 218 <p><a class="anchor" id="app"></a></p> 219 <ul> 220 <li><code>Application.mk</code>: You may optionally create an Application.mk 221 file. This file enumerates and describes the modules that your app requires. 222 This information includes:<ul> 223 <li>ABIs used to compile for specific platforms.</li> 224 <li>Toolchains.</li> 225 <li>Standard libraries to include (static and dynamic STLport or default 226 system).</li> 227 </ul> 228 </li> 229 </ul> 230 <p>For more information, see the <a 231 href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Applicatio 232 n.mk</a> section.</p> 233 <p><a class="anchor" id="fl"></a> </p> 234 <h3>Flow</h3> 235 <p></p> 236 <p>The general flow for developing a native app for Android is as follows:</p> 237 <ol type="1"> 238 <li>Design your app, deciding which parts to implement in Java, and which parts 239 to implement as native code. 240 241 <br> 242 <b>Note:</b> While it is possible to completely avoid Java, you are likely to 243 find 244 the Android Java framework useful for tasks including controlling the 245 display and UI.</li> 246 <li>Create an Android app Project in Eclipse as you would for any other Android 247 project.</li> 248 <li>If you are writing a native-only app, declare the NativeActivity class in 249 AndroidManifest.xml. You can do so from the Eclipse/ADT Android Manifest 250 Editor, or by hand-editing the file. For more information, see the <a 251 href=#naa>Native Activity</a> section.</li> 252 <li>Create an Android.mk file describing the native library, including name, 253 flags, linked libraries and source files to be compiled in the JNI 254 directory.</li> 255 <li>OPTIONAL: Create an <code>Application.mk</code> file configuring the target 256 ABIs, toolchain, release/debug mode, and STL. For any of these that you do not 257 specify, the following default values are used, respectively: <ul> 258 <li> 259 ABI: armeabi<br/> 260 </li> 261 <li> 262 Toolchain: GCC 4.8<br/> 263 </li> 264 <li> 265 Mode: Release<br/> 266 </li> 267 <li> 268 STL: system </li> 269 </ul> 270 </li> 271 <li>Place your native source under the project's <code>jni</code> 272 directory.</li> 273 <li>Use ndk-build to compile the native (<code>.so</code>, <code>.a</code>) 274 libraries.</li> 275 <li>Build the Java component, producing the executable <code>.dex</code> 276 file.</li> 277 <li>Package everything into an APK file, containing <code>.so</code>, 278 <code>.dex</code>, and other files needed for your app to run.</li> 279 </ol> 280 <p>Note that Eclipse can perform steps 7. through 9. in a single operation.</p> 281 <p><a class="anchor" id="naa"></a> </p> 282 <h2>Native Activities and Applications</h2> 283 <p></p> 284 <p>The Android SDK provides a helper class, <code>NativeActivity</code>, that 285 allows you to write a completely native activity. <code>NativeActivity</code> 286 handles the communication between the Android framework and your native code, 287 so you do not have to subclass it or call its methods. All you need to do is 288 declare your application to be native in your <code>AndroidManifest.xml</code> 289 file, and begin creating your native application.</p> 290 <p>An Android application using <code>NativeActivity</code> still runs in its 291 own virtual machine, sandboxed from other applications. You can therefore still 292 access Android framework APIs through the JNI. In certain cases, 293 however–such as for sensors, input events, and assets–the NDK 294 provides native interfaces that you can use instead of having to call across 295 the JNI. For more information about such support, see 296 <code>STABLE-APIS.HTML</code>.</p> 297 <p>Regardless of whether or not you are developing a native activity, we 298 recommend that you create your projects with the usual Android build tools. 299 Doing so helps ensure building and packaging of Android applications with the 300 correct structure.</p> 301 <p>The Android NDK provides you with two choices to implement your native 302 activity:</p> 303 <ul> 304 <li>The <code>native_activity.h</code> header defines the native version of the 305 NativeActivity class. It contains the callback interface and data structures 306 that you need to create your native activity. Because the main thread of your 307 application handles the callbacks, your callback implementations must not be 308 blocking. If they block, you might receive ANR (Application Not Responding) 309 errors because your main thread is unresponsive until the callback returns.</li> 310 <li>The android_native_app_glue.h file defines a static helper library built on 311 top of the <code>native_activity.h</code> interface. It spawns another thread, 312 which handles things such as callbacks or input events in an event loop. Moving 313 these events to a separate thread prevents any callbacks from blocking your 314 main thread.</li> 315 </ul> 316 <p>The 317 <code><ndk_root>/sources/android/native_app_glue/android_native_app_glue.c 318 </code> source is also available, allowing you to modify the implementation.</p> 319 <p>For more information on how to use this static library, examine the 320 native-activity sample application, and its documentation. Further reading is 321 also available in the comments in the 322 <code><ndk_root>/sources/android/native_app_glue/android_native_app_glue.h 323 </code> file.</p> 324 <p><a class="anchor" id="na"></a> </p> 325 <h3>Using the <code>native-activity.h</code> interface</h3> 326 <p></p> 327 <p>To implement a native activity with the <code>native-activity.h</code> 328 interface:</p> 329 <ol type="1"> 330 <li>Create a <code>jni/</code> directory in your project's root directory. This 331 directory stores all of your native code.</li> 332 <li>Declare your native activity in the <code>AndroidManifest.xml</code> 333 file.</li> 334 335 <p>Because your application has no Java code, set <code>android:hasCode</code> 336 to <code>false</code>.</p> 337 <pre class="fragment"> <application android:label="@string/app_name" 338 android:hasCode="false"> 339 </pre><p>The <code>android:name</code> attribute of the activity tag must be 340 set to <code>android.app.NativeActivity</code>.</p> 341 <pre class="fragment"> <activity 342 android:name="android.app.NativeActivity" 343 android:label="@string/app_name" 344 345 </pre> 346 <b>Note:</b> You can subclass <code>NativeActivity</code>. If you do, use the 347 name of the subclass instead of <code>NativeActivity</code>. 348 <p>The <code>android:value</code> attribute of the <code>meta-data</code> tag 349 specifies the name of the shared library containing the entry point to the 350 application (e.g., C/C++ <code>main</code>), omitting the <code>lib</code> 351 prefix and <code>.so</code> suffix from the library name.</p> 352 <pre class="fragment"> <meta-data 353 android:name="android.app.lib_name" 354 android:value="native-activity" /> 355 <intent-filter> 356 <action android:name="android.intent.action.MAIN" /> 357 <category android:name="android.intent.category.LAUNCHER" /> 358 </intent-filter> 359 </activity> 360 </application> 361 </manifest> 362 </pre> 363 <li>Create a file for your native activity, and implement the 364 <code>ANativeActivity_onCreate()</code> function, which the app calls when the 365 native activity starts. This function, analogous to <code>main</code> in C/C++, 366 receives a pointer to an <code>ANativeActivity</code> structure, which contains 367 function pointers to the various callback implementations that you need to 368 write. Set the applicable callback function pointers in 369 <code>ANativeActivity->;callbacks</code> to the implementations of your 370 callbacks.</li> 371 <li>Set the <code>ANativeActivity->;instance</code> field to the address of 372 any instance of specific data that you want to use.</li> 373 <li>Implement anything else that you want your activity to do upon 374 starting.</li> 375 <li>Implement the rest of the callbacks that you set in 376 <code>ANativeActivity->;callbacks</code>. For more information on when the 377 callbacks are called, see the <a 378 href="http://developer.android.com/training/basics/activity-lifecycle/index.html 379 ">SDK documentation for Activity Lifecycles</a>.</li> 380 <li>Develop the rest of your application.</li> 381 <li>Create an <code>Android.mk file</code> in the <code>jni/</code> directory 382 of your project to describe your native module to the build system. For more 383 information, see the <a 384 href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk section.</a></li> 385 <li>Once you have an <code>Android.mk</code> file, compile your native code 386 using the <code>ndk-build</code> command.</li> 387 388 <pre class="fragment">$ cd <path>/<to>/<project> 389 $ <ndk>/ndk-build 390 </pre> 391 <li>Build and install your Android project as usual, using Ant or Eclipse. If 392 your native code is in the <code>jni/</code> directory, the build script 393 automatically packages the <code>.so</code> file(s) built from it into the 394 APK.</li> 395 </ol> 396 <p class="endli">You can find further information on using 397 <code>native-activity.h</code> in the comments in the 398 <code><ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_a 399 ctivity.h</code> file. </p> 400 </li> 401 </ul> 402 </div></div><!-- contents --> 403 </div><!-- doc-content --> 404 <!-- start footer part --> 405 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> 406 <ul> 407 <li class="footer">Generated on Sun Jun 22 2014 15:25:44 for NDK 408 Programmer's Guide by 409 <a href="http://www.doxygen.org/index.html"> 410 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li> 411 </ul> 412 </div> 413 </body> 414 </html> 415
