<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer's Guide: Concepts</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">NDK Programmer's Guide
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_1__concepts__concepts.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Concepts </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><ul style="list-style: none; ">
<li>
<a href="#bb">Before Beginning</a> </li>
<li>
<a href="#intro">Introduction</a> </li>
<li>
<a href="#hiw">Process</a> <ul style="list-style:none;">
<li>
<a href="#mc">Main Components</a> </li>
<ul>
<li>
<a href="#ndk">ndk-build</a> </li>
<li>
<a href="#jav">Java</a> </li>
<li>
<a href="#nshl">Native shared libraries</a> </li>
<li>
<a href="#nstl">Native static libraries</a> </li>
<li>
<a href="#jni">Java Native Interface (JNI)</a> </li>
<li>
<a href="#abi">Application Binary Interface (ABI)</a> </li>
<li>
<a href="#man">Manifest</a> </li>
<li>
<a href="#and">Android.mk</a> </li>
<li>
<a href="#app">Application.mk</a> </li>
</ul>
<a href="#fl">Flow</a> </li>
</ul>
</li>
<li>
<p class="startli"><a href="#naa">Native Activities and Applications</a></p>
<p><a class="anchor" id="bb"></a> </p>
<h2>Before Beginning</h2>
<p></p>
<p>This guide assumes that you are:</p>
<ul>
<li>Already familiar with concepts inherent in native programming, and in <a
href="http://developer.android.com">development of Android apps</a>.</li>
<li>Working in <a href="http://developer.android.com/sdk/index.html">Eclipse,
and using the Android Development Tools ("ADT")</a>, except where otherwise
noted.</li>
</ul>
<p><a class="anchor" id="intro"></a> </p>
<h2>Introduction</h2>
<p></p>
<p>This section provides a high-level explanation of how the NDK works. The
Android NDK is a set of tools allowing you to embed C or C++ (“native
code”) into your Android apps. The ability to use native code in Android apps
can be particularly useful to developers who wish to do one or more of the
following:</p>
<ul>
<li>Port their apps between platforms.</li>
<li>Use existing libraries created by other developers (or provide their own
libraries to others).</li>
<li>Increase performance in certain cases, particularly computationally
intensive ones like games.</li>
</ul>
<p><br/>
</p>
<b>Important Notes:</b> The Android NDK can only be used to target Android
system images running Android 1.5 (API Level 3) or later.
The NDK only provides system headers for a very limited set of native
APIs and libraries supported by the Android platform. While a typical
Android system image includes many native shared libraries, you should
consider them an implementation detail that might change drastically
between platform releases. If the NDK headers do not explicitly support an
Android system library, then apps should not depend on its being
available; otherwise, the next over-the-air (“OTA”) system update may
break them.
<p><a class="anchor" id="hiw"></a> </p>
<h2>Process</h2>
<p>This section introduces the main components used in building a native
application for Android, and goes on to describe the flow of building and
packaging.</p>
<p><a class="anchor" id="mc"></a> </p>
<h3>Main components</h3>
<p></p>
<p>You should have an understanding of the following components, as you build
your app:</p>
<p><a class="anchor" id="ndk"></a></p>
<ul>
<li>ndk-build: The ndk-build script launches the build scripts at the heart of
the NDK. These scripts:<ul>
<li>Automatically probe your development system and app project file to
determine what to build.</li>
<li>Generate binaries.</li>
<li>Copy the binaries to your app's project path.</li>
</ul>
</li>
</ul>
<p>For more information, see the <a
href="./md_3__key__topics__building__chapter_1-section_8_ndk-build.html">ndk-build</a> section of this guide.</p>
<p><a class="anchor" id="jav"></a></p>
<ul>
<li>Java: From your Java source, the Android build process generates
<code>.dex</code> ("Dalvik EXecutable") files, which are what the Android OS
runs in the Dalvik Virtual Machine (“DVM”). Even if your app contains no
Java source code at all, the build process still generates a <code>.dex</code>
executable file within which the native component runs.</li>
</ul>
<p>When developing Java components, use the <code>native</code> keyword to
indicate methods implemented as native code. For example, the following
function declaration tells the compiler that the implementation is in a native
library:</p>
<pre class="fragment">public native int add(int x, int y);
</pre><p><a class="anchor" id="nshl"></a></p>
<ul>
<li>Native shared libraries: The NDK builds these libraries, or
<code>.so</code> files, from your native source code.</li>
</ul>
<br>
<b>Note:</b> If two libraries implement the same method, with the same name, a
link
error occurs.
</pre><p><a class="anchor" id="nstl"></a></p>
<ul>
<li>Native static libraries: The NDK can also build static libraries, or
<code>.a</code> files, which you can link against other libraries.</li>
</ul>
<p><a class="anchor" id="jni"></a></p>
<ul>
<li>Java Native Interface ("JNI"): The JNI is the interface via which the Java
and C++ components talk to one another. This guide assumes knowledge of the
JNI; for information about it, consult the <a
href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html
">Java Native Interface Specification</a>.</li>
</ul>
<p><a class="anchor" id="abi"></a></p>
<ul>
<li>Application Binary Interface ("ABI"): The ABI defines exactly how your
app's machine code is expected to interact with the system at runtime. The NDK
builds <code>.so</code> files against these definitions. Different ABIs
correspond to different architectures: The NDK includes ABI support for ARMEABI
(default), MIPS, and x86. For more information, see <a
href="./md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">Supported ABIs</a>.</li>
</ul>
<p><a class="anchor" id="man"></a></p>
<ul>
<li>Manifest: If you are writing an app with no Java component to it, you must
declare the NativeActivity class in the <a
href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">manifest</a>. The <a href=#naa>Native Activity</a> section provides more detail
on how to do this, under “Using the native-activity.h interface.”</li>
</ul>
<br>
<b>Note:</b> The following two items only apply in cases in which you are using
the
toolchains provided with the Android NDK as standalone compilers.
<p><a class="anchor" id="and"></a></p>
<ul>
<li><code>Android.mk</code>: You must create an <code>Android.mk</code>
configuration file inside your <code>jni</code> folder. The ndk-build script
looks at this file, which defines the module and its name, the source files to
be compiled, build flags and libraries to link. For more information, see the
<a
href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a> section of this document.</li>
</ul>
<p><a class="anchor" id="app"></a></p>
<ul>
<li><code>Application.mk</code>: You may optionally create an Application.mk
file. This file enumerates and describes the modules that your app requires.
This information includes:<ul>
<li>ABIs used to compile for specific platforms.</li>
<li>Toolchains.</li>
<li>Standard libraries to include (static and dynamic STLport or default
system).</li>
</ul>
</li>
</ul>
<p>For more information, see the <a
href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Applicatio
n.mk</a> section.</p>
<p><a class="anchor" id="fl"></a> </p>
<h3>Flow</h3>
<p></p>
<p>The general flow for developing a native app for Android is as follows:</p>
<ol type="1">
<li>Design your app, deciding which parts to implement in Java, and which parts
to implement as native code.
<br>
<b>Note:</b> While it is possible to completely avoid Java, you are likely to
find
the Android Java framework useful for tasks including controlling the
display and UI.</li>
<li>Create an Android app Project in Eclipse as you would for any other Android
project.</li>
<li>If you are writing a native-only app, declare the NativeActivity class in
AndroidManifest.xml. You can do so from the Eclipse/ADT Android Manifest
Editor, or by hand-editing the file. For more information, see the <a
href=#naa>Native Activity</a> section.</li>
<li>Create an Android.mk file describing the native library, including name,
flags, linked libraries and source files to be compiled in the ‘JNI’
directory.</li>
<li>OPTIONAL: Create an <code>Application.mk</code> file configuring the target
ABIs, toolchain, release/debug mode, and STL. For any of these that you do not
specify, the following default values are used, respectively: <ul>
<li>
ABI: armeabi<br/>
</li>
<li>
Toolchain: GCC 4.8<br/>
</li>
<li>
Mode: Release<br/>
</li>
<li>
STL: system </li>
</ul>
</li>
<li>Place your native source under the project's <code>jni</code>
directory.</li>
<li>Use ndk-build to compile the native (<code>.so</code>, <code>.a</code>)
libraries.</li>
<li>Build the Java component, producing the executable <code>.dex</code>
file.</li>
<li>Package everything into an APK file, containing <code>.so</code>,
<code>.dex</code>, and other files needed for your app to run.</li>
</ol>
<p>Note that Eclipse can perform steps 7. through 9. in a single operation.</p>
<p><a class="anchor" id="naa"></a> </p>
<h2>Native Activities and Applications</h2>
<p></p>
<p>The Android SDK provides a helper class, <code>NativeActivity</code>, that
allows you to write a completely native activity. <code>NativeActivity</code>
handles the communication between the Android framework and your native code,
so you do not have to subclass it or call its methods. All you need to do is
declare your application to be native in your <code>AndroidManifest.xml</code>
file, and begin creating your native application.</p>
<p>An Android application using <code>NativeActivity</code> still runs in its
own virtual machine, sandboxed from other applications. You can therefore still
access Android framework APIs through the JNI. In certain cases,
however–such as for sensors, input events, and assets–the NDK
provides native interfaces that you can use instead of having to call across
the JNI. For more information about such support, see
<code>STABLE-APIS.HTML</code>.</p>
<p>Regardless of whether or not you are developing a native activity, we
recommend that you create your projects with the usual Android build tools.
Doing so helps ensure building and packaging of Android applications with the
correct structure.</p>
<p>The Android NDK provides you with two choices to implement your native
activity:</p>
<ul>
<li>The <code>native_activity.h</code> header defines the native version of the
NativeActivity class. It contains the callback interface and data structures
that you need to create your native activity. Because the main thread of your
application handles the callbacks, your callback implementations must not be
blocking. If they block, you might receive ANR (Application Not Responding)
errors because your main thread is unresponsive until the callback returns.</li>
<li>The android_native_app_glue.h file defines a static helper library built on
top of the <code>native_activity.h</code> interface. It spawns another thread,
which handles things such as callbacks or input events in an event loop. Moving
these events to a separate thread prevents any callbacks from blocking your
main thread.</li>
</ul>
<p>The
<code><ndk_root>/sources/android/native_app_glue/android_native_app_glue.c
</code> source is also available, allowing you to modify the implementation.</p>
<p>For more information on how to use this static library, examine the
native-activity sample application, and its documentation. Further reading is
also available in the comments in the
<code><ndk_root>/sources/android/native_app_glue/android_native_app_glue.h
</code> file.</p>
<p><a class="anchor" id="na"></a> </p>
<h3>Using the <code>native-activity.h</code> interface</h3>
<p></p>
<p>To implement a native activity with the <code>native-activity.h</code>
interface:</p>
<ol type="1">
<li>Create a <code>jni/</code> directory in your project's root directory. This
directory stores all of your native code.</li>
<li>Declare your native activity in the <code>AndroidManifest.xml</code>
file.</li>
<p>Because your application has no Java code, set <code>android:hasCode</code>
to <code>false</code>.</p>
<pre class="fragment"> <application android:label="@string/app_name"
android:hasCode="false">
</pre><p>The <code>android:name</code> attribute of the activity tag must be
set to <code>android.app.NativeActivity</code>.</p>
<pre class="fragment"> <activity
android:name="android.app.NativeActivity"
android:label="@string/app_name"
</pre>
<b>Note:</b> You can subclass <code>NativeActivity</code>. If you do, use the
name of the subclass instead of <code>NativeActivity</code>.
<p>The <code>android:value</code> attribute of the <code>meta-data</code> tag
specifies the name of the shared library containing the entry point to the
application (e.g., C/C++ <code>main</code>), omitting the <code>lib</code>
prefix and <code>.so</code> suffix from the library name.</p>
<pre class="fragment"> <meta-data
android:name="android.app.lib_name"
android:value="native-activity" />
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
</pre>
<li>Create a file for your native activity, and implement the
<code>ANativeActivity_onCreate()</code> function, which the app calls when the
native activity starts. This function, analogous to <code>main</code> in C/C++,
receives a pointer to an <code>ANativeActivity</code> structure, which contains
function pointers to the various callback implementations that you need to
write. Set the applicable callback function pointers in
<code>ANativeActivity->;callbacks</code> to the implementations of your
callbacks.</li>
<li>Set the <code>ANativeActivity->;instance</code> field to the address of
any instance of specific data that you want to use.</li>
<li>Implement anything else that you want your activity to do upon
starting.</li>
<li>Implement the rest of the callbacks that you set in
<code>ANativeActivity->;callbacks</code>. For more information on when the
callbacks are called, see the <a
href="http://developer.android.com/training/basics/activity-lifecycle/index.html
">SDK documentation for Activity Lifecycles</a>.</li>
<li>Develop the rest of your application.</li>
<li>Create an <code>Android.mk file</code> in the <code>jni/</code> directory
of your project to describe your native module to the build system. For more
information, see the <a
href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk section.</a></li>
<li>Once you have an <code>Android.mk</code> file, compile your native code
using the <code>ndk-build</code> command.</li>
<pre class="fragment">$ cd <path>/<to>/<project>
$ <ndk>/ndk-build
</pre>
<li>Build and install your Android project as usual, using Ant or Eclipse. If
your native code is in the <code>jni/</code> directory, the build script
automatically packages the <code>.so</code> file(s) built from it into the
APK.</li>
</ol>
<p class="endli">You can find further information on using
<code>native-activity.h</code> in the comments in the
<code><ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_a
ctivity.h</code> file. </p>
</li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Sun Jun 22 2014 15:25:44 for NDK
Programmer's Guide by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
</body>
</html>