diff options
Diffstat (limited to 'docs/html/ndk/guides/concepts.jd')
| -rw-r--r-- | docs/html/ndk/guides/concepts.jd | 309 |
1 files changed, 309 insertions, 0 deletions
diff --git a/docs/html/ndk/guides/concepts.jd b/docs/html/ndk/guides/concepts.jd new file mode 100644 index 0000000..0601f21 --- /dev/null +++ b/docs/html/ndk/guides/concepts.jd @@ -0,0 +1,309 @@ +page.title=Concepts +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#bb">Before Beginning</a></li> + <li><a href="#intro">Introduction</a></li> + <li><a href="#hiw">How It Works</a></li> + <li><a href="#naa">Native Activities and Applications</a></li> + </ol> + </li> + </ol> + </div> + </div> + +<h2 id="bb">Before Beginning</h2> + +<p>This guide assumes that you are:</p> +<ul> +<li>Already familiar with concepts inherent in native programming and in +<a href="{@docRoot}">Android development</a>.</li> +<li>Working in <a href="{@docRoot}sdk/index.html">Eclipse, and using the Android +Development Tools (ADT)</a>, except where otherwise noted.</li> +</ul> +<h2 id="intro">Introduction</h2> + +<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>Reuse existing libraries, or provide their own libraries for reuse. +</li> +<li>Increase performance in certain cases, particularly computationally intensive ones like games. +</li> +</ul> +<h2 id="hiw">How it Works</h2> + +<p>This section introduces the main components used in building a native application for Android, +and goes on to describe the process of building and packaging.</p> +<h3 id="mc">Main components</h3> + +<p>You should have an understanding of the following components as you build your app:</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> +<p>For more information, see +<a href="{@docRoot}ndk/guides/ndk-build.html">ndk-build</a>.</p> +</li> +</ul> + +<ul> +<li>Java: From your Java source, the Android build process generates {@code .dex} +(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} executable file within which the native component runs. + +<p>When developing Java components, use the {@code native} 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> +public native int add(int x, int y); +</pre> +</li> +</ul> + +<ul> +<li>Native shared libraries: The NDK builds these libraries, or {@code .so} files, from your native +source code. + +<p class="note"><strong>Note:</strong> If two libraries implement respective methods with the same +signature, a link error occurs. In C, "signature" means method name only. In C++, "signature" means +not only method name, but also its argument names and types.</p> +</li> +</ul> + +<ul> +<li>Native static libraries: The NDK can also build static libraries, or {@code .a} files, which you +can link against other libraries.</li> +</ul> + +<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> + +<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} 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="{@docRoot}ndk/guides/abis.html">ABI Management</a>.</li> +</ul> + +<ul> +<li>Manifest: If you are writing an app with no Java component to it, you must declare the +{@link android.app.NativeActivity} class in the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a>. +<a href="#naa">Native Activities and Applications</a> provides more detail on how to do this, under +“Using the {@code native_activity.h} interface.” +</li> +</ul> + +<p>The following two items are only required for building using the +<a href="{@docRoot}ndk/guides/ndk-build.html">{@code ndk-build}</a> script, +and for debugging using the <a href="{@docRoot}ndk/guides/ndk-gdb.html"> +{@code ndk-gdb}</a> script. + +<ul> +<li><a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>: +You must create an <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> configuration file inside your {@code jni} folder. The {@code 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.</li> +</ul> + +<ul> +<li><a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>: 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> + + +<h3 id="fl">Flow</h3> + +<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. + +<p class="note"><strong>Note:</strong> 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.</p> +</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 {@link android.app.NativeActivity} class in +{@code 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 Activities and +Applications</a>. +</li> +<li>Create an {@code Android.mk} file describing the native library, including name, flags, linked +libraries, and source files to be compiled in the ‘JNI’ directory.</li> +<li>Optionally, you can create an {@code Application.mk} 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 + </li> +<li> +Toolchain: GCC 4.8 + </li> +<li> +Mode: Release + </li> +<li> +STL: system +</ul> +</li> +<li>Place your native source under the project's {@code jni} directory.</li> +<li>Use ndk-build to compile the native ({@code .so}, {@code .a}) libraries.</li> +<li>Build the Java component, producing the executable {@code .dex} file.</li> +<li>Package everything into an APK file, containing {@code .so}, {@code .dex}, and other files +needed for your app to run. +</ol> + +<p>Note that Eclipse can perform steps 7. through 9. in a single operation.</p> + +<h2 id="naa">Native Activities and Applications</h2> + +<p>The Android SDK provides a helper class, {@link android.app.NativeActivity}, that allows you to +write a completely native activity. {@link android.app.NativeActivity} 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} file, and begin creating your native application.</p> + +<p>An Android application using {@link android.app.NativeActivity} 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 +<a href="{@docRoot}ndk/guides/stable_apis.html">Android NDK Native APIs</a>.</p> + +<p>Regardless of whether or not you are developing a native activity, we recommend that you create +your projects with the traditional 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 <a href="{@docRoot}ndk/reference/native__activity_8h.html">{@code native_activity.h}</a> +header defines the native version of the +{@link android.app.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 {@code android_native_app_glue.h} file defines a static helper library built on top of the +<a href="{@docRoot}ndk/reference/native__activity_8h.html">{@code native_activity.h}</a> 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} 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} file.</p> + +<h3 id="na">Using the native_activity.h interface</h3> + +<p>To implement a native activity with the +<a href="{@docRoot}ndk/reference/native__activity_8h.html">{@code native_activity.h}</a> +interface:</p> + +<ol type="1"> +<li>Create a {@code jni/} 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} file.</li> + +<p>Because your application has no Java code, set {@code android:hasCode} to {@code false}.</p> + +<pre> +<application android:label="@string/app_name" android:hasCode="false"> +</pre> + +<p>You must set the {@code android:name} attribute of the activity tag to +{@link android.app.NativeActivity}.</p> + +<pre> +<activity android:name="android.app.NativeActivity" + android:label="@string/app_name"> +</pre> +<p class="note"><strong>Note:</strong> You can subclass {@link android.app.NativeActivity}. If you +do, use the name of the subclass instead of {@link android.app.NativeActivity}.</p> +<p>The {@code android:value} attribute of the {@code meta-data} tag specifies the name of the shared +library containing the entry point to the application (such as C/C++ {@code main}), omitting the +{@code lib} prefix and {@code .so} suffix from the library name.</p> + +<pre> + <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 function named in the +<a href="{@docRoot}ndk/reference/group___native_activity.html#ga02791d0d490839055169f39fdc905c5e"> +{@code ANativeActivity_onCreate}</a> variable. +The app calls this function when the native activity starts. This function, analogous +to {@code main} in C/C++, receives a pointer to an +<a href="{@docRoot}ndk/reference/struct_a_native_activity.html">{@code ANativeActivity}</a> +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} to the +implementations of your callbacks.</li> + +<li>Set the {@code ANativeActivity->instance} 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}. For +more information on when the callbacks are called, see +<a href="{@docRoot}training/basics/activity-lifecycle/index.html">Managing the Activity +Lifecycle</a>. +</li> +<li>Develop the rest of your application.</li> +<li>Create an {@code Android.mk file} in the {@code jni/} directory of your project to describe your +native module to the build system. For more information, see +<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</li> +<li>Once you have an <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> +file, compile your native code using the {@code ndk-build} command.</li> + +<pre class="no-pretty-print"> +$ 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/} directory, the build script automatically packages the {@code .so} file(s) built +from it into the APK.</li> +</ol> + +</li> +</ul> |