diff options
Diffstat (limited to 'docs/html/ndk/guides')
28 files changed, 4890 insertions, 0 deletions
diff --git a/docs/html/ndk/guides/abis.jd b/docs/html/ndk/guides/abis.jd new file mode 100644 index 0000000..f4819b2 --- /dev/null +++ b/docs/html/ndk/guides/abis.jd @@ -0,0 +1,494 @@ +page.title=ABI Management +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#sa">Supported ABIs</a></li> + <li><a href="#gc">Generating Code for a Specific ABI</a></li> + <li><a href="#am">ABI Management on the Android Platform</a></li> + </ol> + </div> + </div> + +<p>Different Android handsets use different CPUs, which in turn support different instruction sets. +Each combination of CPU and instruction sets has its own Application Binary Interface, or +<i>ABI</i>. The ABI defines, with great precision, how an application's machine code is supposed to +interact with the system at runtime. You must specify an ABI for each CPU architecture you want +your app to work with.</p> + +<p>A typical ABI includes the following information:</p> + +<ul> +<li>The CPU instruction set(s) that the machine code should use.</li> +<li>The endianness of memory stores and loads at runtime.</li> +<li>The format of executable binaries, such as programs and shared libraries, and +the types of content they support.</li> +<li>Various conventions for passing data between your code and the system. +These conventions include alignment constraints, as well as how the system uses the stack and +registers when it calls functions.</li> +<li>The list of function symbols available to your machine code at runtime, +generally from very specific sets of libraries.</li> +</ul> + +<p>This page enumerates the ABIs that the NDK supports, and provides information about how each ABI +works.</p> + +<h2 id="sa">Supported ABIs</h2> + +<p>Each ABI supports one or more instruction sets. Table 1 provides an at-a-glance overview of +the instruction sets each ABI supports.</p> + +<p class="table-caption" id="abi-table"> + <strong>Table 1.</strong> ABIs and supported instruction sets.</p> + +<table> +<tr> +<th>ABI</th> +<th>Supported Instruction Set(s)</th> +<th>Notes</th> +</tr> + +<tr> +<td><a href="#armeabi">{@code armeabi}</a> </td> +<td><li>ARMV5TE and later</li> +<li>Thumb-1</li></td> +<td>No hard float.</td> +</tr> + +<tr> +<td><a href="#v7a">{@code armeabi-v7a} ({@code armeabi-v7a-hard)}</a></td> +<td> +<li>armeabi</li> +<li>Thumb-2</li> +<li>VFPv3-D16</li> +<li>Other, optional</li></td> +<td>Hard float when specified as {@code armeabi-v7a-hard}. +Incompatible with ARMv5, v6 devices.</td> +</tr> + +<tr> +<td><a href="#arm64-v8a">{@code arm64-v8a}</a></td> +<td><li>AArch-64</li></td> +</tr> + +<tr> +<td> +<a href="#x86">{@code x86}</a></td> +<td><li>x86 (IA-32)</li> +<li>MMX</li> +<li>SSE/2/3</li> +<li>SSSE3</li></td> +<td>No support for MOVBE or SSE4.</td> +</tr> + +<tr> +<td><a href="#86-64">{@code x86_64}</a> </td> +<td> +<li>x86-64</li> +<li>MMX</li> +<li>SSE/2/3</li> +<li>SSSE3</li> +<li>SSE4.1, 4.2</li> +<li>POPCNT</li></td> +</tr> + +<tr> +<td><a href="#mips">{@code mips}</a></td> +<td><li>MIPS32r1 and later</li></td> +<td>Uses hard-float, and assumes a CPU:FPU clock ratio of 2:1 for maximum +compatibility. Provides neither micromips nor MIPS16.</td> +</tr> + +<tr> +<td><a href="#mips64">{@code mips64}</a></td> +<td><li>MIPS64r6</li></td><td> +</td> +</tr> +</table> + +<p>More detailed information about each ABI appears below.</p> + +<h3 id="armeabi">armeabi</h3> +<p>This ABI is for ARM-based CPUs that support at least +the ARMv5TE instruction set. Please refer to the following documentation for +more details:</p> + +<ul> +<li><a href="https://www.scss.tcd.ie/~waldroj/3d1/arm_arm.pdf">ARM Architecture +Reference Manual</a></li> +<li><a +href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042e/IHI0042E_aapcs.pdf"> +Procedure Call Standard for the ARM Architecture</a></li> +<li><a +href="http://infocenter.arm.com/help/topic/com.arm.doc.dui0101a/DUI0101A_Elf.pdf"> +ARM ELF File Format</a></li> +<li><a +href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.subset.swdev.abi/index.html">Application Binary Interface (ABI) for the ARM Architecture</a></li> +<li><a +href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0037c/IHI0037C_bpabi.pdf"> +Base Platform ABI for the ARM Architecture</a></li> +<li><a +href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0039c/IHI0039C_clibabi.pdf"> +C Library ABI for the ARM Architecture</a></li> +<li><a +href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ihi0041d/index.html"> +C++ ABI for the ARM Architecture</a></li> +<li><a +href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043d/IHI0043D_rtabi.pdf"> +Run-time ABI for the ARM Architecture</a></li> +<li><a href="http://www.sco.com/developers/gabi/2001-04-24/contents.html">ELF +System V Application Binary Interface</a></li> +<li><a href="http://mentorembedded.github.com/cxx-abi/abi.html">Generic/Itanium C++ +ABI</a></li> +</ul> + +<p>The AAPCS standard defines EABI as a family of similar +but distinct ABIs. Also, Android follows the little-endian +<a href="http://sourcery.mentor.com/sgpp/lite/arm/portal/kbattach142/arm_gnu_linux_ abi.pdf"> +ARM GNU/Linux ABI</a>.</p> + +<p>This ABI does not support hardware-assisted floating point +computations. Instead, all floating-point operations use software helper +functions from the compiler's {@code libgcc.a} static library.</p> + +<p>The armeabi ABI supports ARM’s +<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0210c/CACBCAAE.html"> +Thumb (a.k.a. Thumb-1) instruction set</a>. The NDK generates Thumb +code by default unless you specify different behavior using the +<code>LOCAL_ARM_MODE</code> variable in your +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> +file.</p> + +<h3 id="v7a">armeabi-v7a (armeabi-v7a-hard)</h3> +<p>This ABI extends armeabi to include several +<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0406c/index.html"> +CPU instruction set extensions</a>. The instruction extensions that this Android-specific +ABI supports are:</p> + +<ul> +<li>The Thumb-2 instruction set extension, which provides performance comparable to 32-bit ARM +instructions with similar compactness to Thumb-1.</li> +<li>The VFP hardware-FPU instructions. More specifically, VFPv3-D16, which +includes 16 dedicated 64-bit floating point registers, in addition to another +16 32-bit registers from the ARM core.</li> +</ul> + +<p>Other extensions that the v7-a ARM spec describes, including +<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html"> +Advanced SIMD</a> (a.k.a. NEON), VFPv3-D32, and ThumbEE, are optional +to this ABI. Since their presence is not guaranteed, the system should check at runtime +whether the extensions are available. If they are not, you must use alternative code paths. This +check is similar to the one that the system typically performs to check or use +<a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, +<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, and other specialized +instruction sets on x86 CPUs.</p> + +<p>For information about how to perform these runtime checks, refer to +<a href="{@docRoot}ndk/guides/cpu-features.html">The {@code cpufeatures} Library</a>. +Also, for information about the NDK's support for building +machine code for NEON, see +<a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON Support</a>.</p> + +<p>The {@code armeabi-v7a} ABI uses the {@code -mfloat-abi=softfp} switch to +enforce the rule that the compiler must pass all double values in core register pairs during +function calls, instead of dedicated floating-point ones. The system can perform all internal +computations using the FP registers. Doing so speeds up the computations greatly.</p> + +<p>Although the requirement to use core register pairs produces a modest performance hit, it ensures +compatibility with all existing armeabi binaries. If you need the additional +performance, you can specify your ABI as {@code armeabi-v7a-hard} instead. Doing so +allows you to use hard floats, while still linking with Android native APIs +that use {@code softfp}. For more information, refer to the comments in +{@code $NDK/tests/device/hard-float/jni/android.mk}.</p> + +<p class="note"><strong>Note:</strong> You cannot specify {@code APP_ABI} as both +{@code armeabi-v7a} and {@code armeabi-v7a-hard}. In either case, the build system places the +shared libraries in the {@code armeabi-v7a/} directory.</p> + +<h3 id="hard">armeabi-v7a-hard</h3> +<p>This variant of the {@code armeabi-v7a} ABI is unique to the NDK. The NDK build +system adds the following flags in addition to those that it uses for the +{@code armeabi-v7a} ABI:</p> + +<pre class="no-pretty-print"> +TARGET_CFLAGS += -mhard-float -D_NDK_MATH_NO_SOFTFP=1 +TARGET_LDFLAGS += -Wl,--no-warn-mismatch -lm_hard +</pre> + +<p>The compiler compiles all code with hard-float, and links it with {@code libm_hard.a}. +This math library is the same one as {@code libm.a}, except that it follows hard-float ABI +conventions. In the APK, the generated shared libraries reside in {@code /lib/armeabi-v7a/}.</p> + +<h3 id="arm64-v8a">arm64-v8a</h3> +<p>This ABI is for ARMv8-based CPUs that support AArch64. It also includes the NEON and +VFPv4 instruction sets.</p> + +<p>For more information, see the +<a href="http://www.arm.com/files/downloads/ARMv8_Architecture.pdf">ARMv8 +Technology Preview</a>, and contact ARM for further details.</p> + +<h3 id="x86">x86</h3> +<p>This ABI is for CPUs supporting the instruction set commonly +referred to as "x86" or "IA-32". Characteristics of this ABI include:</p> + +<ul> +<li>Instructions normally generated by GCC with compiler flags such as the following: + +<pre class="no-pretty-print"> +-march=i686 -mtune=intel -mssse3 -mfpmath=sse -m32 +</pre> + +<p>These flags target the the Pentium Pro instruction set, along with the +the <a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, +<a href="http://en.wikipedia.org/wiki/Streaming_SIMD_Extensions">SSE</a>, +<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, +<a href="http://en.wikipedia.org/wiki/SSE3">SSE3</a>, and +<a href="http://en.wikipedia.org/wiki/SSSE3">SSSE3</a> instruction set extensions. +The generated code is an optimization balanced across the top Intel 32-bit +CPUs.</p> +<p> For more information on compiler flags, particularly related to performance optimization, +refer to <a href="http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints">GCC +x86 performance hints</a>.</p> +</li> +<li>Use of the standard Linux x86 32-bit calling convention, as opposed to the one for SVR. For +more information, see section 6, "Register Usage", of +<a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for different +C++ compilers and operating systems</a>.</li> +</ul> + +<p>The ABI does not include any other optional IA-32 instruction set +extensions, such as:</p> +<ul> +<li>MOVBE</li> +<li>Any variant of SSE4.</li> +</ul> +<p>You can still use these extensions, as long as you use runtime feature-probing to +enable them, and provide fallbacks for devices that do not support them.</p> +<p>The NDK toolchain assumes 16-byte stack alignment before a function call. The default tools and +options enforce this rule. If you are writing assembly code, you must make sure to maintain stack +alignment, and ensure that other compilers also obey this rule.</p> + +<p>Refer to the following documents for more details:</p> +<ul> +<li> +<a href="https://gcc.gnu.org/onlinedocs/gcc-4.9.2/gcc/i386-and-x86-64-Options.html"> +GCC online documentation: Intel 386 and AMD x86-64 Options</a></li> +<li><a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling +conventions for different C++ compilers and operating systems</a></li> +<li><a +href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf" +>Intel IA-32 Intel Architecture Software Developer's Manual, Volume 2: +Instruction Set Reference</a></li> +<li><a +href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-system-programming-manual-325384.pdf">Intel +IA-32 Intel Architecture Software Developer's Manual, Volume 3: System +Programming Guide</a></li> +<li><a href="http://www.sco.com/developers/devspecs/abi386-4.pdf">System V Application Binary +Interface: Intel386 Processor Architecture Supplement</a></li> +</ul> + +<h3 id="86-64">x86_64</h3> +<p>This ABI is for CPUs supporting the instruction set commonly referred to as +"x86-64." It supports instructions that GCC typically generates with the following +compiler flags:</p> +<pre class="no-pretty-print"> +-march=x86-64 -msse4.2 -mpopcnt -m64 -mtune=intel +</pre> + +<p>These flags target the x86-64 instruction set, according to the GCC +documentation. along with the +<a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, +<a href="http://en.wikipedia.org/wiki/Streaming_SIMD_Extensions">SSE</a>, +<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, +<a href="http://en.wikipedia.org/wiki/SSE3">SSE3</a>, +<a href="http://en.wikipedia.org/wiki/SSSE3">SSSE3</a>, +<a href="http://en.wikipedia.org/wiki/SSE4#SSE4.1">SSE4.1</a>, +<a href="http://en.wikipedia.org/wiki/SSE4#SSE4.2">SSE4.2</a>, and +<a href="https://software.intel.com/en-us/node/512035">POPCNT</a> +instruction-set extensions. The generated code is an optimization balanced +across the top Intel 64-bit CPUs.</p> + +<p> For more information on compiler flags, particularly related to performance optimization, +refer to <a href="http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints">GCC +x86 Performance</a>.</p> + +<p>This ABI does not include any other optional x86-64 instruction set +extensions, such as:</p> + +<ul> +<li>MOVBE</li> +<li>SHA</li> +<li>AVX</li> +<li>AVX2</li> +</ul> + +<p>You can still use these extensions, as long as you use runtime feature probing to +enable them, and provide fallbacks for devices that do not support them.</p> +<p>Refer to the following documents for more details:</p> + +<ul> +<li><a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for +different C++ compilers and operating systems</a></li> +<li> +<a href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html?iid=tech_vt_tech+64-32_manuals"> +Intel64 and IA-32 Architectures Software Developer's Manual, Volume 2: Instruction Set +Reference</a></li> +<li> +<a href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html?iid=tech_vt_tech+64-32_manuals"> +Intel64 and IA-32 Intel Architecture Software Developer's Manual Volume 3: System Programming</a> +</li> +</ul> + +<h3 id="mips">mips</h3> +<p>This ABI is for MIPS-based CPUs that support at least the MIPS32r1 instruction set. It includes +the following features:</p> + +<ul> +<li>MIPS32 revision 1 ISA</li> +<li>Little-endian</li> +<li>O32</li> +<li>Hard-float</li> +<li>No DSP application-specific extensions</li> +</ul> + +<p>For more information, please refer to the following documentation:</p> + +<ul> +<li>Architecture for Programmers ("MIPSARCH")</li> +<li><a href="https://refspecs.linuxbase.org/elf/gabi4+/contents.html">ELF +System V Application Binary Interface</a></li> +<li><a href="http://sourcery.mentor.com/public/cxx-abi/abi.html">Itanium/Generic C++ +ABI</a></li> +</ul> + +<p>The MIPS-specific documentation is available +<a href="http://www.imgtec.com/mips/architectures/mips32.asp">here</a>, with +further information +<a href="https://sourcery.mentor.com/sgpp/lite/mips/portal/target_arch?@action=faq&target_arch=MIPS">here</a>.</p> +</li> +</ul> + +<h3 id="mips64">mips64</h3> +<p>This ABI is for MIPS64 R6. For more information, see +<a href="http://www.imgtec.com/mips/architectures/mips64.asp">MIPS64 Architecture</a>.</p> + +<h2 id="gc">Generating Code for a Specific ABI</h2> +<p>By default, the NDK generates machine code for the armeabi ABI. You can +generate ARMv7-a-compatible machine code, instead, by adding the following line +to your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file.</p> +<pre class="no-pretty-print"> +APP_ABI := armeabi-v7a +</pre> + +<p>To build machine code for two or more distinct ABIs, using spaces as delimiters. For +example:</p> + +<pre class="no-pretty-print"> +APP_ABI := armeabi armeabi-v7a +</pre> + +<p>This setting tells the NDK to build two versions of your machine code: one +for each ABI listed on this line. For more information on the values you can specify for the +{@code APP_ABI} variable, see <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>. +</p> + +<p>When you build multiple machine-code versions, the build system copies the libraries to your +application project path, and ultimately packages them into your APK, so creating +a <a href="http://en.wikipedia.org/wiki/Fat_binary"><i>fat binary</i></a>. A fat binary +is larger than one containing only the machine code for a single system; the tradeoff is +gaining wider compatibility, but at the expense of a larger APK.</p> + +<p>At installation time, the package manager unpacks only the most appropriate +machine code for the target device. For details, see <a href="#aen">Automatic +extraction of native code at install time</a>.</p> + + +<h2 id="am">ABI Management on the Android Platform</h2> +<p>This section provides details about how the Android platform manages native +code in APKs.</p> + +<h3>Native code in app packages</h3> +<p>Both the Play Store and Package Manager expect to find NDK-generated +libraries on filepaths inside the APK matching the following pattern:</p> + +<pre class="no-pretty-print"> +/lib/<abi>/lib<name>.so +</pre> + +<p>Here, {@code <abi>} is one of the ABI names listed under <a href="#sa">Supported ABIs</a>, +and {@code <name>} is the name of the library as you defined it for the {@code LOCAL_MODULE} +variable in the <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file. Since +APK files are just zip files, it is trivial to open them and confirm that the shared native +libraries are where they belong.</p> + +<p>If the system does not find the native shared libraries where it expects them, it cannot use +them. In such a case, the app itself has to copy the libraries over, and then +perform <code>dlopen()</code>.</p> + +<p>In a fat binary, each library resides under a directory whose name matches a corresponding ABI. +For example, a fat binary may contain:</p> + +<pre class="no-pretty-print"> +/lib/armeabi/libfoo.so +/lib/armeabi-v7a/libfoo.so +/lib/arm64-v8a/libfoo.so +/lib/x86/libfoo.so +/lib/x86_64/libfoo.so +/lib/mips/libfoo.so +/lib/mips64/libfoo.so +</pre> + +<p class="note"><strong>Note:</strong> ARMv7-based Android devices running 4.0.3 or earlier +install native libraries from the {@code armeabi} directory instead of the {@code armeabi-v7a} +directory if both directories exist. This is because {@code /lib/armeabi/} comes after +{@code /lib/armeabi-v7a/} in the APK. This issue is fixed from 4.0.4.</p> + +<h3>Android Platform ABI support</h3> +<p>The Android system knows at runtime which ABI(s) it supports, because build-specific system +properties indicate:</p> + +<ul> +<li>The primary ABI for the device, corresponding to the machine code used in +the system image itself.</li> +<li>An optional, secondary ABI, corresponding to another ABI that the system image also supports. +</li> +</ul> + +<p>This mechanism ensures that the system extracts the best machine code from +the package at installation time.</p> + +<p>For best performance, you should compile directly for the primary ABI. For example, a +typical ARMv5TE-based device would only define the primary ABI: {@code armeabi}. By contrast, a +typical, ARMv7-based device would define the primary ABI as {@code armeabi-v7a} and the secondary +one as {@code armeabi}, since it can run application native binaries generated for each of them.</p> + +<p>Many x86-based devices can also run {@code armeabi-v7a} and {@code armeabi} NDK binaries. For +such devices, the primary ABI would be {@code x86}, and the second one, {@code armeabi-v7a}.</p> + +<p>A typical MIPS-based device only defines a primary abi: {@code mips}.</p> + +<h3 id="aen">Automatic extraction of native code at install time</h3> + +<p>When installing an application, the package manager service scans the APK, and looks for any +shared libraries of the form:</p> + +<pre class="no-pretty-print"> +lib/<primary-abi>/lib<name>.so +</pre> + +<p>If none is found, and you have defined a secondary ABI, the service scans for shared libraries of +the form:</p> + +<pre class="no-pretty-print"> +lib/<secondary-abi>/lib<name>.so +</pre> + +<p>When it finds the libraries that it's looking for, the package manager +copies them to <code>/lib/lib<name>.so</code>, under the application's +{@code data} directory ({@code data/data/<package_name>/lib/}).</p> + +<p>If there is no shared-object file at all, the application builds and installs, but crashes at +runtime.</p> diff --git a/docs/html/ndk/guides/android_mk.jd b/docs/html/ndk/guides/android_mk.jd new file mode 100644 index 0000000..47fefc3 --- /dev/null +++ b/docs/html/ndk/guides/android_mk.jd @@ -0,0 +1,875 @@ +page.title=Android.mk +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#over">Overview</a></li> + <li><a href="#basics">Basics</a></li> + <li><a href="#var">Variables and Macros</a></li> + <li><a href="#mdv">Module-Description Variables</a></li> + </ol> + </div> + </div> + + +<p>This page describes the syntax of the {@code Android.mk} build file, +which glues your C and C++ source files to the Android NDK.</p> + +<h2 id="over">Overview</h2> +<p>The {@code Android.mk} file resides in a subdirectory of your project's {@code jni/} directory, +and describes your sources and shared libraries to the build system. It is really a tiny GNU +makefile fragment that the build system parses once or more. The {@code Android.mk} file is useful +for defining project-wide settings that <a href="{@docRoot}ndk/guides/application_mk.html">{@code +Application.mk}</a>, the build system, and your +environment variables leave undefined. It can also override project-wide settings for specific +<i>modules</i>.</p> + +<p>The syntax of the {@code Android.mk} allows you to group your sources into +<em>modules</em>. A module is either a static library, a shared library, or a standalone +executable. You can define one or more modules in each {@code Android.mk} file, and +you can use the same source file in multiple modules. The build system only places shared libraries +into your application package. In addition, static libraries can generate shared libraries.</p> + +<p>In addition to packaging libraries, the build system handles a variety of other details for you. +For example, you don't need to list header files or explicit dependencies between generated files in +your {@code Android.mk} file. The NDK build system computes these relationships automatically for +you. As a result, you should be able to benefit from new toolchain/platform support in future NDK +releases without having to touch your {@code Android.mk} file.</p> + +<p>The syntax of this file is very close to that used in the {@code Android.mk} files distributed with +the full <a href="https://source.android.com">Android Open Source Project</a>. While the +build system implementation that uses them is different, their similarity is an +intentional design decision aimed at making it easier for application +developers to reuse source code for external libraries.</p> + +<h2 id="basics">Basics</h2> +<p>Before exploring the syntax in detail, it is useful to start by understanding the basics +of what a {@code Android.mk} file contains. This section uses the {@code Android.mk} file in the +Hello-JNI sample toward that end, explaining the role that each line in the file plays.</p> + + +<p>An {@code Android.mk} file must begin by defining the {@code LOCAL_PATH} variable: + +<pre class="no-pretty-print"> +LOCAL_PATH := $(call my-dir) +</pre> + +<p>This variable indicates the location of the source files in the development tree. Here, the macro +function {@code my-dir}, provided by the build system, returns the path of the current directory +(the directory containing the {@code Android.mk} file itself).</p> + +<p>The next line declares the {@code CLEAR_VARS} variable, whose value the build system provides. + +<pre class="no-pretty-print"> +include $(CLEAR_VARS) +</pre> + +<p>The {@code CLEAR_VARS} variable points to a special GNU Makefile that clears many +{@code LOCAL_XXX} variables for you, such as {@code LOCAL_MODULE}, {@code LOCAL_SRC_FILES}, and +{@code LOCAL_STATIC_LIBRARIES}. Note that it does not clear {@code LOCAL_PATH}. This variable must +retain its value because the system parses all build control files in a single GNU Make execution +context where all variables are global. You must (re-)declare this variable before describing each +module.</p> + +<p>Next, the {@code LOCAL_MODULE} variable stores the name of the module that you wish to build. +Use this variable once per module in your application.</p> + +<pre class="no-pretty-print"> +LOCAL_MODULE := hello-jni +</pre> + +<p>Each module name must be unique and not contain any spaces. The build system, when it +generates the final shared-library file, automatically adds the proper prefix and suffix to +the name that you assign to {@code LOCAL_MODULE}. For example, the example that appears above +results in generation of a library called {@code libhello-jni.so}.</p> + +<p class="note"><strong>Note:</strong> If your module's name already starts with {@code lib}, the +build system does not prepend an additional {@code lib} prefix; it takes the module name as-is, and +adds the {@code .so} extension. So a source file originally called, for example, {@code libfoo.c} +still produces a shared-object file called {@code libfoo.so}. This behavior is to support libraries +that the Android platform sources generate from {@code Android.mk} files; the names of all such +libraries start with {@code lib}.</p> + +<p>The next line enumerates the source files, with spaces delimiting multiple files:</p> + +<pre class="no-pretty-print"> +LOCAL_SRC_FILES := hello-jni.c +</pre> + +<p>The {@code LOCAL_SRC_FILES} variable must contain a list of C and/or C++ source files to build +into a module.</p> + +<p>The last line helps the system tie everything together:</p> + +<pre class="no-pretty-print"> +include $(BUILD_SHARED_LIBRARY) +</pre> + +<p>The {@code BUILD_SHARED_LIBRARY} variable points to a GNU Makefile script that collects all the +information you defined in {@code LOCAL_XXX} variables since the most recent {@code include}. This +script determines what to build, and how to do it.</p> + +<p>There are more complex examples in the samples directories, with commented +{@code Android.mk} files that you can look at. In addition, +<a href="{@docRoot}ndk/samples/sample_na.html">Sample: native-activity</a> provides +a detailed explanation of that sample's {@code Android.mk} file. Finally, <a href="#var"> +Variables and Macros</a> provides further information on the variables from this section. + + +<h2 id="var">Variables and Macros</h2> +<p>The build system provides many possible variables for use in the the {@code Android.mk} file. +Many of these variables come with preassigned values. Others, you assign.</p> + +<p>In addition to these variables, you can also define your own arbitrary ones. If you do so, keep +in mind that the NDK build system reserves the following variable names:</p> +<ul> +<li>Names that begin with {@code LOCAL_}, such as {@code LOCAL_MODULE}.</li> +<li>Names that begin with {@code PRIVATE_}, {@code NDK_}, or {@code APP}. The build system uses +these internally.</li> +<li>Lower-case names, such as {@code my-dir}. The build system uses these internally, as well.</li> +</ul> +<p>If you need to define your own convenience variables in an {@code Android.mk} file, we +recommend prepending {@code MY_} to their names. + + +<h3 id="npv">NDK-defined variables</h3> +<p>This section discusses the GNU Make variables that the build system defines before parsing your +{@code Android.mk} file. Under certain circumstances, the NDK might parse your {@code Android.mk} +file several times, using a different definition for some of these variables each time.</p> + +<h4>CLEAR_VARS</h4> +<p>This variable points to a build script that undefines nearly all {@code LOCAL_XXX} variables +listed in the "Developer-defined variables" section below. Use this variable to include +this script before describing a new module. The syntax for using it is:</p> + +<pre class="no-pretty-print"> +include $(CLEAR_VARS) +</pre> + +<h4>BUILD_SHARED_LIBRARY</h4> +<p>This variable points to a build script that collects all the information about the module +you provided in your {@code LOCAL_XXX} variables, and determines how to build a target shared +library from the sources you listed. Note that using this script requires that you have already +assigned values to {@code LOCAL_MODULE} and {@code LOCAL_SRC_FILES}, at a minimum (for more +information about these variables, see <a href = "#mdv">Module-Description Variables</a>).</p> + +<p>The syntax for using this variable is:</p> + +<pre class="no-pretty-print"> +include $(BUILD_SHARED_LIBRARY) +</pre> + +<p>A shared-library variable causes the build system to generate a library file with a {@code .so} +extension.</p> + +<h4>BUILD_STATIC_LIBRARY</h4> +<p>A variant of {@code BUILD_SHARED_LIBRARY} that is used to build a static library. The build +system does not copy static libraries into your project/packages, but it can use them to build +shared libraries (see {@code LOCAL_STATIC_LIBRARIES} and {@code LOCAL_WHOLE_STATIC_LIBRARIES}, +below). The syntax for using this variable is:</p> + +<pre class="no-pretty-print"> +include $(BUILD_STATIC_LIBRARY) +</pre> + +<p>A static-library variable causes the build system to generate a library with a {@code .a} +extension.</p> + +<h4>PREBUILT_SHARED_LIBRARY</h4> +<p>Points to a build script used to specify a prebuilt shared library. Unlike in the case of +{@code BUILD_SHARED_LIBRARY} and {@code BUILD_STATIC_LIBRARY}, here the value of +{@code LOCAL_SRC_FILES} cannot be a source file. Instead, it must be a single path to a prebuilt +shared library, such as {@code foo/libfoo.so}. The syntax for using this variable is:</p> + +<pre class="no-pretty-print"> +include $(PREBUILT_SHARED_LIBRARY) +</pre> + +<p>You can also reference a prebuilt library in another module by using the +{@code LOCAL_PREBUILTS} variable. For more information about using prebuilts, see +<a href="{@docRoot}ndk/guides/prebuilts.html">Using Prebuilt Libraries</a>.</p> + + +<h4>PREBUILT_STATIC_LIBRARY</h4> +<p>The same as {@code PREBUILT_SHARED_LIBRARY}, but for a prebuilt static library. For more +information about using prebuilts, see <a href="{@docRoot}ndk/guides/prebuilts.html">Using Prebuilt +Libraries</a>.</p> + +<h4>TARGET_ARCH</h4> +<p>The name of the target CPU architecture as the Android Open Source Project specifies it. +For any ARM-compatible build, use {@code arm}, independent of the CPU architecture revision or +ABI (see TARGET_ARCH_ABI, below).</p> + +<p>The value of this variable is taken from the APP_ABI variable that you define in the +{@code Android.mk} file, which the system reads ahead of parsing the {@code Android.mk} file.</p> + +<h4>TARGET_PLATFORM</h4> +<p>The Android API level number for the build system to target. +For example, the Android 5.1 system images correspond to Android API level 22: {@code android-22}. +For a complete list of platform names and corresponding Android system +images, see <a href="{@docRoot}ndk/guides/stable_apis.html">Android NDK Native APIs</a>. +The following example shows the syntax for using this variable:</p> + +<pre class="no-pretty-print"> +TARGET_PLATFORM := android-22 +</pre> + +<h4 id="taa">TARGET_ARCH_ABI</h4> +<p>This variable stores the name of the CPU and architecture to target when the build system +parses this {@code Android.mk} file. You can specify one or more of the following values, using +a space as a delimiter between multiple targets. Table 1 shows the ABI setting to use for each +supported CPU and architecture. + +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> ABI settings for different CPUs and architectures.</p> +<table> + <tr> + <th scope="col">CPU and architecture</th> + <th scope="col">Setting</th> + </tr> + <tr> + <td>ARMv5TE</td> + <td>{@code armeabi}</td> + </tr> + <tr> + <td>ARMv7</td> + <td>{@code armeabi-v7a}</td> + </tr> + <tr> + <td>ARMv8 AArch64</td> + <td>{@code arm64-v8a}</td> + </tr> + <tr> + <td>i686</td> + <td>{@code x86}</td> + </tr> + <tr> + <td>x86-64</td> + <td>{@code x86_64}</td> + </tr> + <tr> + <td>mips32 (r1)</td> + <td>{@code mips}</td> + </tr> + <tr> + <td>mips64 (r6)</td> + <td>{@code mips64}</td> + </tr> + <tr> + <td>All</td> + <td>{@code all}</td> + </tr> +</table> + +<p>The following example shows how to set ARMv8 AArch64 as the target CPU-and-ABI combination:</p> + +<pre class="no-pretty-print"> +TARGET_ARCH_ABI := arm64-v8a +</pre> + +<p class="note"><strong>Note: </strong> Up to Android NDK 1.6_r1, this variable is defined as +{@code arm}.</p> + +<p>For more details about architecture ABIs and associated compatibility +issues, refer to +<a href="{@docRoot}ndk/guides/abis.html">ABI Management</a>.</p> + +<p>New target ABIs in the future will have different values.</p> + +<h4>TARGET_ABI</h4> +<p>A concatenation of target Android API level and ABI, it is especially useful when you want to test against +a specific target system image for a real device. For example, to specify a 64-bit ARM device +running on Android API level 22:</p> + +<pre class="no-pretty-print"> +TARGET_ABI := android-22-arm64-v8a +</pre> + +<p class="note"><strong>Note:</strong> Up to Android NDK 1.6_r1, the default value was +{@code android-3-arm}.</p> + +<h2 id="mdv">Module-Description Variables</h2> +<p>The variables in this section describe your module to the build system. Each module description +should follow this basic flow: +<ul> +<ol type = "1"> +<li>Initialize or undefine the variables associated with the module, using the {@code CLEAR_VARS} + variable.</li> +<li>Assign values to the variables used to describe the module. +<li>Set the NDK build system to use the appropriate build script for the module, using the + {@code BUILD_XXX} variable.</li> +</ol> +</ul> + +<h4>LOCAL_PATH</h4> +<p>This variable is used to give the path of the current file. You must define +it at the start of your {@code Android.mk} file. The following example shows how to do so:</p> + +<pre class="no-pretty-print"> +LOCAL_PATH := $(call my-dir) +</pre> + +<p>The script to which {@code CLEAR_VARS} points does not clear this variable. Therefore, you only need +to define it a single time, even if your {@code Android.mk} file describes multiple modules.</p> + +<h4>LOCAL_MODULE</h4> +<p>This variable stores the name of your module. It must be unique among all module names, +and must not contain any spaces. You must define it before including any scripts (other than +the one for {@code CLEAR_VARS}). You need not add either the {@code lib} prefix +or the {@code .so} or {@code .a} file extension; the build system makes these modifications +automatically. Throughout your {@code Android.mk} and +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> files, refer to +your module by its unmodified name. For example, the following line results in the generation of a +shared library module called {@code libfoo.so}:</p> + +<pre class="no-pretty-print"> +LOCAL_MODULE := "foo" +</pre> + +<p>If you want the generated module to have a name other than {@code lib} + the value of +{@code LOCAL_MODULE}, you can use the {@code LOCAL_MODULE_FILENAME} variable to give the +generated module a name of your own choosing, instead.</p> + +<h4>LOCAL_MODULE_FILENAME</h4> +<p>This optional variable allows you to override the names that the build system +uses by default for files that it generates. For example, if the name of your {@code LOCAL_MODULE} +is {@code foo}, you can force the system to call the file it generates {@code libnewfoo}. The +following example shows how to accomplish this:</p> + +<pre class="no-pretty-print"> +LOCAL_MODULE := foo +LOCAL_MODULE_FILENAME := libnewfoo +</pre> + +<p>For a shared library module, this example would generate a file called {@code libnewfoo.so}.</p> + +<p class="note"><strong>Note:</strong> You cannot override filepath or file extension.</p> + +<h4>LOCAL_SRC_FILES</h4> +<p>This variable contains the list of source files that the build system uses to generate the +module. Only list the files that the build system actually passes to the compiler, since the build +system automatically computes any associated depencies.</p> +<p>Note that you can use both relative (to {@code LOCAL_PATH}) and absolute file paths. + +<p>We recommend avoiding absolute file paths; relative paths make your {@code Android.mk} file more +portable.</p> + +<p class="note"><strong>Note: </strong> Always use Unix-style forward slashes (/) in build files. +The build system does not handle Windows-style backslashes (\) properly.</p> + +<h4>LOCAL_CPP_EXTENSION</h4> +<p>You can use this optional variable to indicate a file extension other than {@code .cpp} for your +C++ source files. For example, the following line changes the extension to {@code .cxx}. +(The setting must include the dot.) + +<pre class="no-pretty-print"> +LOCAL_CPP_EXTENSION := .cxx +</pre> + +<p>From NDK r7, you can use this variable to specify multiple extensions. For instance:</p> + +<pre class="no-pretty-print"> +LOCAL_CPP_EXTENSION := .cxx .cpp .cc +</pre> + +<h4>LOCAL_CPP_FEATURES</h4> + +<p>You can use this optional variable to indicate that your code relies on specific C++ features. +It enables the right compiler and linker flags during the build process. For prebuilt binaries, +this variable also declares which features the binary depends on, thus helping ensure the final +linking works correctly. We recommend that you use this variable instead of enabling +{@code -frtti} and {@code -fexceptions} directly in your {@code LOCAL_CPPFLAGS} definition.</p> + +<p>Using this variable allows the build system to use the appropriate flags for each module. Using +{@code LOCAL_CPPFLAGS} causes the compiler to use all specified flags for all modules, regardless +of actual need.</p> + +For example, to indicate that your code uses RTTI (RunTime Type Information), write: </p> + +<pre class="no-pretty-print"> +LOCAL_CPP_FEATURES := rtti +</pre> + +<p>To indicate that your code uses C++ exceptions, write:</p> + +<pre class="no-pretty-print"> +LOCAL_CPP_FEATURES := exceptions +</pre> + +<p>You can also specify multiple values for this variable. For example:</p> + +<pre class="no-pretty-print"> +LOCAL_CPP_FEATURES := rtti features +</pre> + +The order in which you describe the values does not matter. + + +<h4>LOCAL_C_INCLUDES</h4> +<p>You can use this optional variable to specify a list of paths, relative to the +NDK {@code root} directory, to add to the include search path when compiling all sources +(C, C++ and Assembly). For example: </p> + +<pre class="no-pretty-print"> +LOCAL_C_INCLUDES := sources/foo +</pre> + +<p>Or even: </p> + +<pre class="no-pretty-print"> +LOCAL_C_INCLUDES := $(LOCAL_PATH)/<subdirectory>/foo +</pre> + +<p>Define this variable before setting any corresponding inclusion flags via {@code LOCAL_CFLAGS} +or {@code LOCAL_CPPFLAGS}.</p> + +<p>The build system also uses {@code LOCAL_C_INCLUDES} paths automatically when launching native +debugging with ndk-gdb.</p> + + +<h4>LOCAL_CFLAGS</h4> + +<p>This optional variable sets compiler flags for the build system to pass when building C +<em>and</em> C++ source files. The ability to do so can be useful for specifying additional macro +definitions or compile options.</p> + +<p>Try not to change the optimization/debugging level in your {@code Android.mk} file. +The build system can handle this setting automatically for you, using the relevant information +in the <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. Doing it +this way allows the build system to generate useful data files used during debugging.</p> + +<p class="note"><strong>Note: </strong>In android-ndk-1.5_r1, the corresponding flags only applied +to C source files, not C++ ones. They now match the full Android build system behavior. +(You can now use {@code LOCAL_CPPFLAGS} to specify flags for C++ sources only.)</p> + +<p>It is possible to specify additional include paths by writing: + +<pre class="no-pretty-print"> +LOCAL_CFLAGS += -I<path>, +</pre> + +It is better, however, to use {@code LOCAL_C_INCLUDES} for this purpose, since +doing so also makes it possible to use the paths available for native debugging with ndk-gdb.</p> + + +<h4>LOCAL_CPPFLAGS</h4> +<p>An optional set of compiler flags that will be passed when building C++ +source files <em>only</em>. They will appear after the LOCAL_CFLAGS on the +compiler's command-line.</p> + + +<p class="note"><strong>Note: </strong>In android-ndk-1.5_r1, the corresponding flags applied to +both C and C++ sources. This has been corrected to match the full Android build system. +To specify flags for both C and C++ sources, use {@code LOCAL_CFLAGS}.</p> + + +<h4>LOCAL_STATIC_LIBRARIES</h4> + +<p>This variable stores the list of static libraries modules on which the current module depends.</p> + +<p>If the current module is a shared library or an executable, this variable will force +these libraries to be linked into the resulting binary.</p> + +<p>If the current module is a static library, this variable simply indicates that other +modules depending on the current one will also depend on the listed +libraries.</p> + +<h4>LOCAL_SHARED_LIBRARIES</h4> + +<p>This variable is the list of shared libraries <em>modules</em> on which this module depends at +runtime. This information is necessary at link time, and to embed the corresponding information +in the generated file.</p> + +<h4>LOCAL_WHOLE_STATIC_LIBRARIES</h4> +<p>This variable is a variant of {@code LOCAL_STATIC_LIBRARIES}, and expresses that the linker +should treat the associated library modules as <em>whole archives</em>. For more information +on whole archives, see the GNU linker's +<a href="http://ftp.gnu.org/old-gnu/Manuals/ld-2.9.1/html_node/ld_3.html">documentation</a> for the +{@code --whole-archive} flag.</p> + +<p>This variable is useful when there are circular dependencies among +several static libraries. When you use this variable to build a shared library, it will force +the build system to add all object files from your static libraries to the final binary. The same +is not true, however, when generating executables.</p> + + +<h4>LOCAL_LDLIBS</h4> + +<p>This variable contains the list of additional linker flags for use in building your shared +library or executable. It enables you to use the {@code -l} prefix to pass the name of specific +system libraries. For example, the following example tells the linker to generate a module that +links to {@code /system/lib/libz.so} at load time: </p> + +<pre class="no-pretty-print"> +LOCAL_LDLIBS := -lz +</pre> + +<p>For the list of exposed system libraries against which you can link in this NDK release, see +<a href="stable_apis.html">Android NDK Native APIs</a>.</p> + +<p class="note"><strong>Note: </strong> If you define this variable for a static library, +the build system ignores it, and {@code ndk-build} prints a warning.</p> + +<h4>LOCAL_LDFLAGS</h4> + +<p>The list of other linker flags for the build system to use when building your shared library +or executable. For example, the following example uses the {@code ld.bfd} linker on ARM/X86 GCC +4.6+, on which {@code ld.gold} is the default </p> + +<pre class="no-pretty-print"> +LOCAL_LDFLAGS += -fuse-ld=bfd +</pre> + +<p class="note"><strong>Note: </strong>If you define this variable for a static library, the build +system ignores it, and ndk-build prints a warning.</p> + +<h4>LOCAL_ALLOW_UNDEFINED_SYMBOLS</h4> + +<p>By default, when the build system encounters an undefined reference encountered while trying to +build a shared, it will throw an <em>undefined symbol</em> error. This error can help you catch +catch bugs in your source code.</p> + +<p>To disable this check, set this variable to {@code true}. Note that this setting may cause the +shared library to load at runtime.</p> + +<p class="note"><strong>Note: </strong> If you define this variable for a static library, +the build system ignores it, and ndk-build prints a warning.</p> + +<h4>LOCAL_ARM_MODE</h4 +> +<p>By default, the build system generates ARM target binaries in <em>thumb</em> mode, where each +instruction is 16 bits wide and linked with the STL libraries in the {@code thumb/} directory. +Defining this variable as {@code arm} forces the build system to generate the module's object +files in 32-bit {@code arm} mode. The following example shows how to do this:</p> + +<pre class="no-pretty-print"> +LOCAL_ARM_MODE := arm +</pre> + +<p>You can also instruct the build system to only build specific sources in {@code arm} mode by +appending {@code .arm} suffix to the the source filenames. For example, the following example +tells the build system to always compile {@code bar.c} in ARM mode, but to build +{@code foo.c} according to the value of {@code LOCAL_ARM_MODE}.</p> + +<pre class="no-pretty-print"> +LOCAL_SRC_FILES := foo.c bar.c.arm +</pre> + +<p></p> + +<p class="note"><strong>Note: </strong> You can also force the build system to generate ARM binaries +by setting {@code APP_OPTIM} in your +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file to {@code debug}. +Specifying {@code debug} forces an ARM build because the toolchain debugger does not handle Thumb +code properly.</p> + + +<h4>LOCAL_ARM_NEON</h4> +<p>This variable only matters when you are targeting the {@code armeabi-v7a} ABI. It allows the +use of ARM Advanced SIMD (NEON) GCC intrinsics in your C and C++ sources, as well as NEON +instructions in Assembly files.</p> + +<p>Note that not all ARMv7-based CPUs support the NEON instruction set extensions. For this reason, +you must perform runtime detection to be able to safely use this code at runtime. For more +information, see <a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON Support</a> and <a +href="{@docRoot}ndk/guides/cpu-features.html">The {@code cpufeatures} Library</a>.</p> + +<p>Alternatively, you can use the {@code .neon} suffix to specify that the build system only +compile specific source files with NEON support. In the following example, the build system compiles +{@code foo.c} with thumb and neon support, {@code bar.c} with thumb support, and +{@code zoo.c} with support for ARM and NEON:</p> + +<pre class="no-pretty-print"> +LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon +</pre> + + +<p>If you use both suffixes, {@code .arm} must precede {@code .neon}.</p> + +<h4>LOCAL_DISABLE_NO_EXECUTE</h4> + +<p>Android NDK r4 added support for the "NX bit" security feature. It is +enabled by default, but you can disable it by setting this variable to {@code true}. We do not +recommend doing so without a compelling reason.</p> + +<p>This feature does not modify the ABI, and is only enabled on kernels +targeting ARMv6+ CPU devices. Machine code with this feature enabled +will run unmodified on devices running earlier CPU architectures.</p> +<p>For more information, see <a href="http://en.wikipedia.org/wiki/NX_bit">Wikipedia: NX bit</a> +and <a href="http://www.gentoo.org/proj/en/hardened/gnu-stack.xml">The GNU stack kickstart</a>. + +<h4>LOCAL_DISABLE_RELRO</h4> + +<p>By default, the NDK compiles code with read-only relocations and GOT +protection. This variable instructs the runtime linker to mark certain regions of memory +as read-only after relocation, making certain security exploits (such as GOT overwrites) +more difficult. Note that these protections are only effective on Android API level 16 and higher. +On lower API levels, the code will still run, but without memory protections.</p> + +<p>This variable is turned on by default, but you can disable it by setting its value to +{@code true}. We do not recommend doing so without a compelling reason.</p> + +<p>For more information, see +<a href="http://isisblogs.poly.edu/2011/06/01/relro-relocation-read-only/">RELRO: +RELocation Read-Only</a> and <a href="http://www.akkadia.org/drepper/nonselsec.pdf">Security +enhancements in RedHat Enterprise Linux (section 6)</a>.</p> + +<h4>LOCAL_DISABLE_FORMAT_STRING_CHECKS</h4> + +<p>By default, the build system compiles code with format string protection. Doing so forces a +compiler error if a non-constant format string is used in a {@code printf}-style function.</p> +<p>This protection is on by default, but you can disable it by setting the value of +this variable to {@code true}. We do not recommend doing so without a compelling reason.</p> + + +<h4>LOCAL_EXPORT_CFLAGS</h4> + +<p>This variable records a set of C/C++ compiler flags to add to the {@code LOCAL_CFLAGS} definition +of any other module that uses this one via the {@code LOCAL_STATIC_LIBRARIES} or +{@code LOCAL_SHARED_LIBRARIES} variables.</p> + +<p>For example, consider the following pair of modules: {@code foo} and {@code bar}, which depends +on {@code foo}:</p> + +<pre class="no-pretty-print"> +include $(CLEAR_VARS) +LOCAL_MODULE := foo +LOCAL_SRC_FILES := foo/foo.c +LOCAL_EXPORT_CFLAGS := -DFOO=1 +include $(BUILD_STATIC_LIBRARY) + + +include $(CLEAR_VARS) +LOCAL_MODULE := bar +LOCAL_SRC_FILES := bar.c +LOCAL_CFLAGS := -DBAR=2 +LOCAL_STATIC_LIBRARIES := foo +include $(BUILD_SHARED_LIBRARY) +</pre> + +<p>Here, the build system passes the flags {@code -DFOO=1} and {@code -DBAR=2} to the compiler when +building {@code bar.c}. It also prepends exported flags to your your module's {@code LOCAL_CFLAGS} +so you can easily override them.</p> + +In addition, the relationship among modules is transitive: If {@code zoo} depends on +{@code bar}, which in turn depends on {@code foo}, then {@code zoo} also inherits all flags +exported from {@code foo}.</p> + +<p>Finally, the build system does not use exported flags when building locally (i.e., building the +module whose flags it is exporting). Thus, in the example above, it does not pass {@code -DFOO=1} +to the compiler when building {@code foo/foo.c}. To build locally, use {@code LOCAL_CFLAGS} +instead.</p> + +<h4>LOCAL_EXPORT_CPPFLAGS</h4> +<p>This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for C++ flags only.</p> + +<h4>LOCAL_EXPORT_C_INCLUDES</h4> +<p>This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for C include paths. It is useful +in cases where, for example, {@code bar.c} needs to include headers from module {@code foo}.</p> + +<h4>LOCAL_EXPORT_LDFLAGS</h4> +<p>This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for linker flags.</p> + +<h4>LOCAL_EXPORT_LDLIBS</h4> +<p>This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, telling the build system to pass names +of specific system libraries to the compiler. Prepend {@code -l} to the name of each library you +specify.</p> + +<p>Note that the build system appends imported linker flags to the value of your module's +{@code LOCAL_LDLIBS} variable. It does this due to the way Unix linkers work.</p> + +<p>This variable is typically useful when module {@code foo} is a static library +and has code that depends on a system library. You can then use {@code LOCAL_EXPORT_LDLIBS} to +to export the dependency. For example: </p> + +<pre class="no-pretty-print"> +include $(CLEAR_VARS) +LOCAL_MODULE := foo +LOCAL_SRC_FILES := foo/foo.c +LOCAL_EXPORT_LDLIBS := -llog +include $(BUILD_STATIC_LIBRARY) + +include $(CLEAR_VARS) +LOCAL_MODULE := bar +LOCAL_SRC_FILES := bar.c +LOCAL_STATIC_LIBRARIES := foo +include $(BUILD_SHARED_LIBRARY) +</pre> + +<p>In this example, the build system puts {@code -llog} at the end of the linker command when it +builds {@code libbar.so}. Doing so tells the linker that, because {@code libbar.so} depends +on {@code foo}, it also depends on the system logging library.</p> + +<h4>LOCAL_SHORT_COMMANDS</h4> +<p>Set this variable to {@code true} when your module has a very high +number of sources and/or dependent static or shared libraries. Doing so forces the +build system to use {@code @} syntax for archives containing intermediate object files +or linking libraries.</p> + +<p>This feature can be useful on Windows, where the command line accepts a maximum of only +of 8191 characters, which can be too small for complex projects. It also impacts the compilation of +individual source files, placing nearly all compiler flags inside list files, too.</p> + +<p>Note that any value other than {@code true} will revert to the +default behaviour. You can also define {@code APP_SHORT_COMMANDS} in your +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file to force this +behavior for all modules in your project.</p> + +<p>We do not recommend enabling this feature by default, since it makes the build slower.</p> + + +<h4>LOCAL_THIN_ARCHIVE</h4> + +<p>Set this variable to {@code true} when building static libraries. +Doing so will generate a <strong>thin archive</strong>, a library file that does not contain +object files, but instead just file paths to the actual objects that it would normally +contain.</p> +<p>This is useful to reduce the size of your build output. The drawback is that +such libraries <em>cannot</em> be moved to a different location (all paths +inside them are relative).</p> +<p>Valid values are {@code true}, {@code false} or empty. A +default value can be set in your <a href="{@docRoot}ndk/guides/application_mk.html"> +{@code Application.mk}</a> file through the {@code APP_THIN_ARCHIVE} + +variable.</p> +<p class="note"><strong>Note:</strong> This is ignored for non-static library modules, or prebuilt +static library ones.</p> + +<h4>LOCAL_FILTER_ASM</h4> +<p>Define this variable as a shell command that the build system will use to filter the +assembly files extracted or generated from the files you specified for {@code LOCAL_SRC_FILES}.</p> +<p>Defining this variable causes the following things to occur:</p> + +<ul> +<ol type = "1"> +<li>The build system generates a temporary assembly file from any C or C++ source file, instead of compiling them into an object file.</li> +<li>The build system executes the shell command in {@code LOCAL_FILTER_ASM} +on any temporary assembly file and on any assembly file +listed in {@code LOCAL_SRC_FILES}, thus generating another temporary assembly +file.</li> +<li>The build system compiles these filtered assembly files into an object file.</li> +</ol> +</ul> +<p>For example:</p> + +<pre class="no-pretty-print"> +LOCAL_SRC_FILES := foo.c bar.S +LOCAL_FILTER_ASM := + +foo.c --1--> $OBJS_DIR/foo.S.original --2--> $OBJS_DIR/foo.S --3--> $OBJS_DIR/foo.o +bar.S --2--> $OBJS_DIR/bar.S --3--> $OBJS_DIR/bar.o +</pre> + +<p>"1" corresponds to the compiler, "2" to the filter, and "3" to the assembler. The filter must +be a standalone shell command that takes the name of the input file as its first argument, and the +name of the output file as the second one. For example:</p> + +<pre class="no-pretty-print"> +myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S +myasmfilter bar.S $OBJS_DIR/bar.S +</pre> + +<h3 id="npfm">NDK-provided function macros</h2> +<p>This section explains GNU Make function macros that the NDK provides. Use +{@code $(call <function>)} to evaluate them; they return textual information.</p> + +<h4>my-dir</h4> + +<p>This macro returns the path of the last included makefile, which typically is the +current {@code Android.mk}'s directory. {@code my-dir} is useful for defining +{@code LOCAL_PATH} at the start of your {@code Android.mk} file. For example:</p> + +<pre class="no-pretty-print"> +LOCAL_PATH := $(call my-dir) +</pre> + +<p>Due to the way GNU Make works, what this macro really returns is the +path of the last makefile that the build system included when parsing the build scripts. For this +reason, you should not call {@code my-dir} after including another file.</p> + +<p>For example, consider the following example: </p> + +<pre class="no-pretty-print"> +LOCAL_PATH := $(call my-dir) + +# ... declare one module + +include $(LOCAL_PATH)/foo/`Android.mk` + +LOCAL_PATH := $(call my-dir) + +# ... declare another module +</pre> + +<p>The problem here is that the second call to {@code my-dir} defines +{@code LOCAL_PATH} as {@code $PATH/foo} instead of {@code $PATH}, because that was where its +most recent include pointed.</p> + +<p>You can avoid this problem by putting additional includes after everything +else in the {@code Android.mk} file. For example:</p> + +<pre class="no-pretty-print"> +LOCAL_PATH := $(call my-dir) + +# ... declare one module + +LOCAL_PATH := $(call my-dir) + +# ... declare another module + +# extra includes at the end of the Android.mk file +include $(LOCAL_PATH)/foo/Android.mk + +</pre> + +<p>If it is not feasible to structure the file in this way, save the value of the first +{@code my-dir} call into another variable. For example: </p> + +<pre class="no-pretty-print"> +MY_LOCAL_PATH := $(call my-dir) + +LOCAL_PATH := $(MY_LOCAL_PATH) + +# ... declare one module + +include $(LOCAL_PATH)/foo/`Android.mk` + +LOCAL_PATH := $(MY_LOCAL_PATH) + +# ... declare another module +</pre> + +<h4>all-subdir-makefiles</h4> + +<p>Returns the list of {@code Android.mk} files located in all subdirectories of +the current {@code my-dir} path. + +<p>You can use this function to provide deep-nested source directory hierarchies to the build +system. By default, the NDK only looks for files in the directory containing the +{@code Android.mk} file.</p> + +<h4>this-makefile</h4> +<p>Returns the path of the current makefile (from which the build system called the function).</p> + +<h4>parent-makefile</h4> +<p>Returns the path of the parent makefile in the inclusion tree (the path of the makefile that +included the current one).</p> + +<h4>grand-parent-makefile</h4> +<p>Returns the path of the grandparent makefile in the inclusion tree (the path of the makefile that +included the current one).</p> + +<h4>import-module</h4> +<p>A function that allows you to find and include a module's {@code Android.mk} file by the name of +the module. A typical example is as follows: </p> + +<pre class="no-pretty-print"> +$(call import-module,<name>) +</pre> + +<p>In this example, the build system looks for the module tagged {@code <name>} in the list of +directories referenced that your {@code NDK_MODULE_PATH} environment variable references, and +includes its {@code Android.mk} file automatically for you.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/application_mk.jd b/docs/html/ndk/guides/application_mk.jd new file mode 100644 index 0000000..1294687 --- /dev/null +++ b/docs/html/ndk/guides/application_mk.jd @@ -0,0 +1,219 @@ +page.title=Application.mk +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#over">Overview</a></li> + <li><a href="#var">Variables</a></li> + </ol> + </div> + </div> + +<p>This document explains the {@code Application.mk} build file, which describes the +native <em>modules</em> that your app requires. A module can be a static library, a shared library, +or an executable.</p> + +<p>We recommend that you read the <a href="{@docRoot}ndk/guides/concepts.html">Concepts</a> and +<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a> pages before this one. Doing so will +help maximize your understanding of the material on this page. </p> + +<h2 id="over">Overview</h2> +The {@code Application.mk} file is really a tiny GNU Makefile fragment that defines several +variables for compilation. It usually resides under {@code $PROJECT/jni/}, where {@code $PROJECT} +points to your application's project directory. Another alternative is to place it under a +sub-directory of the top-level {@code $NDK/apps/} directory. For example:</p> + +<pre> +$NDK/apps/<myapp>/Application.mk +</pre> + +<p>Here, {@code <myapp>} is a short name used to describe your app to the NDK build system. It +doesn't actually go into your generated shared libraries or your final packages.</p> + +<h2 id="var">Variables</h2> +<h4>APP_PROJECT_PATH</h4> +<p>This variable stores the absolute path to your app's project-root directory. The build system +uses this information to place stripped-down versions of the generated JNI shared libraries +into a specific location known to the APK-generating tools.</p> + +<p>If you place your {@code Application.mk} file under {@code $NDK/apps/<myapp>/}, you must +define this variable. If you place it under {@code $PROJECT/jni/}, it is optional. + +<h4>APP_OPTIM</h4> +<p>Define this optional variable as either {@code release} or {@code debug}. You use it to +alter the optimization level when building your application's modules.</p> + +<p>Release mode is the default, and generates highly optimized binaries. Debug mode generates +unoptimized binaries that are much easier to debug.</p> + +<p>Note that you can debug either release or debug binaries. Release binaries, however, provide less +information during debugging. For example, the build system optimizes out some variables, +preventing you from inspecting them. Also, code re-ordering can make it more difficult to step +through the code; stack traces may not be reliable.</p> + +<p>Declaring {@code android:debuggable} in your application manifest's {@code <application>} +tag will cause this variable to default to {@code debug} instead of {@code release}. Override this +default value by setting {@code APP_OPTIM} to {@code release}.</p> + + +<h4>APP_CFLAGS</h4> +<p>This variable stores a set of C compiler flags that the build system passes to the compiler +when compiling any C or C++ source code for any of the modules. You can use this variable to change +the build of a given module according to the application that needs it, instead of having to modify +the {@code Android.mk} file itself. </p> + + +<p>All paths in these flags should be relative to the top-level NDK directory. For example, if you +have the following setup:</p> + +<pre> +sources/foo/Android.mk +sources/bar/Android.mk +</pre> + +<p>To specify in {@code foo/Android.mk} that you want to add the path to the {@code bar} sources +during compilation, you should use: + +<pre> +APP_CFLAGS += -Isources/bar +</pre> + +<p>Or, alternatively:</p> + +<pre> +APP_CFLAGS += -I$(LOCAL_PATH)/../bar +</pre> + +<p>{@code -I../bar} will not work since it is equivalent to +{@code -I$NDK_ROOT/../bar}.</p> + +<p class="note"><strong>Note: </strong>This variable only works on C, not C++, sources in +android-ndk-1.5_r1. In all versions after that one, {@code APP_CFLAGS} matches the full Android +build system.</p> + +<h4>APP_CPPFLAGS</h4> +<p>This variable contains a set of C++ compiler flags that the build system passes to the compiler +when building only C++ sources.</p> + +<p class="note"><strong>Note: </strong> In android-ndk-1.5_r1, this variable works on both C and +C++ sources. In all subsequent versions of the NDK, {@code APP_CPPFLAGS} now matches the full +Android build system. For flags that apply to both C and C++ sources, use {@code APP_CFLAGS}.</p> + +<h4>APP_LDFLAGS</h4> +<p>A set of linker flags that the build system passes when linking the application. This variable +is only relevant when the build system is building shared libraries and executables. When the +build system builds static libraries, it ignores these flags.</p> + +<h4>APP_BUILD_SCRIPT</h4> +<p>By default, the NDK build system looks under {@code jni/} for a file named +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>.</p> + +<p>If you want to override this behavior, you can define {@code APP_BUILD_SCRIPT} to point to an +alternate build script. The build system always interprets a non-absolute path as relative to the +NDK's top-level directory.</p> + +<h4>APP_ABI</h4> +<p>By default, the NDK build system generates machine code for the +<a href="{@docRoot}ndk/guides/abis.html">{@code armeabi}</a> ABI. This machine code +corresponds to an ARMv5TE-based CPU with software floating point operations. You can use +{@code APP_ABI} to select a different ABI. Table 1 shows the {@code APP_ABI} +settings for different instruction sets.</p> + +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> {@code APP_ABI} settings for different instruction sets.</p> +<table> + <tr> + <th scope="col">Instruction set</th> + <th scope="col">Value</th> + </tr> + <tr> + <td>Hardware FPU instructions on ARMv7 based devices</td> + <td>{@code APP_ABI := armeabi-v7a}</td> + </tr> + <tr> + <td>ARMv8 AArch64</td> + <td>{@code APP_ABI := arm64-v8a}</td> + </tr> + <tr> + <td>IA-32</td> + <td>{@code APP_ABI := x86}</td> + </tr> + <tr> + <td>Intel64</td> + <td>{@code APP_ABI := x86_64}</td> + </tr> + <tr> + <td>MIPS32</td> + <td>{@code APP_ABI := mips}</td> + </tr> + <tr> + <td>MIPS64 (r6)</td> + <td>{@code APP_ABI := mips64}</td> + </tr> + <tr> + <td>All supported instruction sets</td> + <td>{@code APP_ABI := all}</td> + </tr> +</table> + +<p class="note"><strong>Note:</strong> {@code all} is available starting from NDKr7.</p> + +<p>You can also specify multiple values by placing them on the same line, delimited by spaces. +For example:</p> + +<pre> +APP_ABI := armeabi armeabi-v7a x86 mips +</pre> + +<p>For the list of all supported ABIs and details about their usage and limitations, refer to +<a href="{@docRoot}ndk/guides/abis.html">ABI Management</a>.</p> + +<h4>APP_PLATFORM</h4> +<p>This variable contains the name of the target Android platform. For example, {@code android-3} +specifies the Android 1.5 system images. For a complete list of platform names and corresponding +Android system images, see <a href="{@docRoot}ndk/guides/stable_apis.html">Android NDK Native APIs +</a>.</p> + +<h4>APP_STL</h4> +<p>By default, the NDK build system provides C++ headers for the minimal C++ runtime library +({@code system/lib/libstdc++.so}) provided by the Android system. In addition, it comes with +alternative C++ implementations that you can use or link to in your own applications. +Use {@code APP_STL} to select one of them. For information about the supported runtimes, and the +features they offer, see <a href="{@docRoot}ndk/guides/cpp-support.html#runtimes">NDK Runtimes and +Features</a>. + +<h4>APP_SHORT_COMMANDS</h4> +<p>The equivalent of {@code LOCAL_SHORT_COMMANDS} in {@code Application.mk} for your whole project. +For more information, see the documentation for this variable on +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>.</p> + +<h4>NDK_TOOLCHAIN_VERSION</h4> +<p>Define this variable as either {@code 4.9} or {@code 4.8} to select a version of the GCC +compiler. Version 4.9 is the default for 64-bit ABIs, and 4.8 is the default for 32-bit ABIs. +To select a version of Clang, define this variable as {@code clang3.4}, {@code clang3.5}, or +{@code clang}. Specifying {@code clang} chooses the most recent version of Clang.</p> + +<h4>APP_PIE</h4> +<p>Starting from Android 4.1 (API level 16), Android's dynamic linker supports position-independent +executables (PIE). From Android 5.0 (API level 21), executables require PIE. + +To use PIE to build your executables, set the {@code -fPIE} flag. This flag makes it harder to +exploit memory corruption bugs by randomizing code location. By default, {@code ndk-build} +automatically sets this value to {@code true} if your project targets {@code android-16} or higher. +You may set it manually to either {@code true} or {@code false}.</p> + +<p>This flag applies only to executables. It has no effect when building shared or static +libraries.</p> + +<p class="note"><strong>Note: </strong> PIE executables cannot run on Android releases prior to 4.1. +<p>This restriction only applies to executables. It has no effect when building shared or static +libraries.</p> + +<h4>APP_THIN_ARCHIVE</h4> +<p>Sets the default value of {@code LOCAL_THIN_ARCHIVE} in the {@code Android.mk} file for all +static library modules in this project. For more information, see the documentation for +{@code LOCAL_THIN_ARCHIVE} on <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}.</a> +</p> diff --git a/docs/html/ndk/guides/arch.jd b/docs/html/ndk/guides/arch.jd new file mode 100644 index 0000000..3dafe8f --- /dev/null +++ b/docs/html/ndk/guides/arch.jd @@ -0,0 +1,19 @@ +page.title=CPUs and Architectures +@jd:body + +<p>When you're working with native code, hardware matters. The NDK lets you ensure you're compiling +for the right architectures and CPUs by giving you a variety of ABIs from which +to choose.</p> + +<p>This section begins by explaining how to target specific +<a href="{@docRoot}ndk/guides/abis.html">architectures and CPUs</a>. It then +provides information you need to know when targeting the +<a href="{@docRoot}ndk/guides/abis.html">ARM</a> +family of CPUs and architectures. Next, it provides information about the other CPUs and +architectures that it supports: <a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON</a>, x86 +(<a href="{@docRoot}ndk/guides/x86.html">32-bit</a> and +<a href="{@docRoot}ndk/guides/x86-64.html">64-bit</a>), and +<a href="{@docRoot}ndk/guides/mips.html">MIPS</a>. Finally, it explains how to use the +<a href="{@docRoot}ndk/guides/cpu-features.html">{@code cpufeatures}</a> +library, which your app can use to query a given CPU and architecture about the optional +features they support.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/build.jd b/docs/html/ndk/guides/build.jd new file mode 100644 index 0000000..6286328 --- /dev/null +++ b/docs/html/ndk/guides/build.jd @@ -0,0 +1,18 @@ +page.title=Building Your Project +@jd:body + +<p>One of the NDK's core purposes is allowing you to build C and C++ source code into shared +libraries that you can use in your app.</p> + +<p>This section explains how to build native binaries for use in your Android app. It begins by +explaining the +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file, which +defines properties specific to individual <i>modules</i>, or libraries. Then, it explains the +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file, which defines +properties for all the modules that you use in your +app. Next, it tells you how to use the <a href="{@docRoot}ndk/guides/ndk-build.html"> +{@code ndk-build}</a> script, which is what the NDK uses to build your sources. Last, it ventures +into advanced territory, discussing how to incorporate the NDK into your own +<a href="{@docRoot}ndk/guides/standalone_toolchain.html">toolchain</a>, if you prefer to +build that way instead of using +<a href="{@docRoot}ndk/guides/ndk-build.html">{@code ndk-build}</a>.</p>
\ No newline at end of file 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> diff --git a/docs/html/ndk/guides/cpp-support.jd b/docs/html/ndk/guides/cpp-support.jd new file mode 100644 index 0000000..0074b80 --- /dev/null +++ b/docs/html/ndk/guides/cpp-support.jd @@ -0,0 +1,328 @@ +page.title=C++ Library Support +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#hr">Helper Runtimes</a></li> + <li><a href="#rc">Runtime Characteristics</a></li> + <li><a href="#ic">Important Considerations</a></li> + <li><a href="#li">Licensing</a></li> + </ol> + </div> + </div> + +<p>The Android platform provides a very minimal C++ runtime support library ({@code libstdc++}). +This minimal support does not include, for example:</p> + +<ul> + <li>Standard C++ Library support (except a few trivial headers).</li> + <li>C++ exceptions support</li> + <li>RTTI support</li> +</ul> + +<p>The NDK provides headers for use with this default library. In addition, the NDK provides a +number of helper runtimes that provide additional features. This page provides information about +these helper runtimes, their characteristics, and how to use them. +</p> + +<h2 id="hr">Helper Runtimes</h2> + +<p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</p> + +<p class="table-caption" id="runtimes"> + <strong>Table 1.</strong> NDK Runtimes and Features.</p> + +<table> +<tr> +<th>Name</th> +<th>Explanation> +<th>Features +</tr> + +<tr> +<td><a href="#system">{@code libstdc++} (default)</a> </td> +<td>The default minimal system C++ runtime library.</td> +<td>N/A</td> +</tr> + +<tr> +<td><a href="#ga">{@code gabi++_static}</a> </td> +<td>The GAbi++ runtime (static).</td> +<td>C++ Exceptions and RTTI</td> +</tr> + +<tr> +<td><a href="#ga">{@code gabi++_shared}</a> </td> +<td>The GAbi++ runtime (shared).</td> +<td>C++ Exceptions and RTTI</td> +</tr> + +<tr> +<td><a href="#stl">{@code stlport_static}</a> </td> +<td>The STLport runtime (static).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> + +<tr> +<td><a href="#stl">{@code stlport_shared}</a> </td> +<td>The STLport runtime (shared).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> + +<tr> +<td><a href="#gn">{@code gnustl_static}</a> </td> +<td>The GNU STL (static).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> + +<tr> +<td><a href="#gn">{@code gnustl_shared}</a> </td> +<td>The GNU STL (shared).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> + +<tr> +<td><a href="#cs">{@code c++_static}</a> </td> +<td>The LLVM libc++ runtime (static).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> + +<tr> +<td><a href="#cs">{@code c++_shared}</a> </td> +<td>The LLVM libc++ runtime (shared).</td> +<td> C++ Exceptions and RTTI; Standard Library</td> +</tr> +</table> + +<h3>How to set your runtime</h3> + +<p>Use the {@code APP_STL} variable in your <a href="{@docRoot}ndk/guides/application_mk.html"> +{@code Application.mk}</a> file to specify the runtime you wish to use. Use the values in +the "Name" column in Table 1 as your setting. For example:</p> + +<pre> +APP_STL := gnustl_static +</pre> + +<p>You may only select one runtime for your app, and can only do in +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p> + +<p>Even if you do not use the NDK build system, you can still use STLport, libc++ or GNU STL. +For more information on how to use these runtimes with your own toolchain, see <a href="{@docRoot}ndk/guides/standalone_toolchain.html">Standalone Toolchain</a>.</p> + +<h2 id="rc">Runtime Characteristics</h2> +<h3 id="system">libstdc++ (default system runtime)</h3> + +<p>This runtime only provides the following headers, with no support beyond them:</p> +<ul> + <li>{@code cassert}</li> + <li>{@code cctype}</li> + <li>{@code cerrno}</li> + <li>{@code cfloat}</li> + <li>{@code climits}</li> + <li>{@code cmath}</li> + <li>{@code csetjmp}</li> + <li>{@code csignal}</li> + <li>{@code cstddef}</li> + <li>{@code cstdint}</li> + <li>{@code cstdio}</li> + <li>{@code cstdlib}</li> + <li>{@code cstring}</li> + <li>{@code ctime}</li> + <li>{@code cwchar}</li> + <li>{@code new}</li> + <li>{@code stl_pair.h}</li> + <li>{@code typeinfo}</li> + <li>{@code utility}</li> +</ul> + +<h3 id="ga">GAbi++ runtime</h3> +<p>This runtime provides the same headers as the default runtime, but adds support for RTTI +(RunTime Type Information) and exception handling.</p> + + +<h3 id="stl">STLport runtime</h3> +<p>This runtime is an Android port of STLport +(<a href="http://www.stlport.org">http://www.stlport.org</a>). It provides a complete set of C++ +standard library headers. It also, by embedding its own instance of GAbi++, provides support for +RTTI and exception handling.</p> + +<p>While shared and static versions of this runtime are avilable, we recommend using the shared +version. For more information, see <a href="#sr">Static runtimes</a>.</p> + +<p>The shared library file is named {@code libstlport_shared.so} instead of {@code libstdc++.so} +as is common on other platforms.</p> + +<p>In addition to the static- and shared-library options, you can also force the NDK to +build the library from sources by adding the following line to your {@code Application.mk} +file, or setting it in your environment prior to building: </p> + +<pre> +STLPORT_FORCE_REBUILD := true +</pre> + + +<h3 id="gn">GNU STL runtime</h3> +<p>This runtime is the GNU Standard C++ Library, ({@code libstdc++-v3}). Its shared library file is +named {@code libgnustl_shared.so}.</p> + + +<h3 id="cs">libC++ runtime:</h3> +<p>This runtime is an Android port of <a href="http://libcxx.llvm.org/">LLVM libc++</a>. Its +shared library file is named {@code libc++_shared.so}.</p> + +<p>By default, this runtime compiles with {@code -std=c++11}. As with GNU {@code libstdc++}, you +need to explicitly turns on exceptions or RTTI support. For information on how to do this, see +<a href="#xp">C++ Exceptions</a> and <a href="#rt">RTTI</a>.</p> + +<p>The NDK provides prebuilt static and shared libraries for {@code libc++} compiled by Clang 3.4, +but you can force the NDK to rebuild {@code libc++} from sources by adding the following line to +your {@code Application.mk} file, or setting it in your environment prior to building: </p> + +<pre> +LIBCXX_FORCE_REBUILD := true +</pre> + +<h4>atomic support</h4> + +<p>If you include {@code <atomic>}, it's likely that you also need {@code libatomic}. +If you are using {@code ndk-build}, add the following line:</p> + +<pre> +LOCAL_LDLIBS += -latomic +</pre> + +<p>If you are using your own toolchain, use:</p> + +<pre> +-latomic +</pre> + +<p class="note"><strong>Note: </strong>{@code -latomic} is only available for GCC 4.8. +Because Clang 3.5 and Clang 3.6 use GCC 4.8's headers and libraries, as well as its +{@code as} and {@code ld} options, those versions of Clang also get {@code -latomic}.</p> + + +<h4>Compatibility</h4> + +<p>Around 99% of tests pass when compiling {@code libc++} with Clang 3.4 for all supported ABIs. +The failures are mostly in the areas of {@code wchar_t} and locales that Android bionic +doesn't support. Switching locale from the default produces the following warning in +{@code logcat}:</p> + +<pre> +newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX" +</pre> + +<p>We do not recommend using {@code libc++} with GCC 4.6 because of GCC 4.6's limited c++11 +support.</p> + +<p>For information on {@code libc++} tests that fail to compile, {@code black_list*} in +{@code $NDK/tests/device/test-libc++-shared-full/jni/Android.mk}. For information about tests +that fail to run correctly, see {@code $NDK/tests/device/test-libc++-shared-full/BROKEN_RUN}. +{@code $NDK}, here, is the your NDK installation's root directory.</p> + + +<h2 id="ic">Important Considerations</h2> + +<h3 id="xp">C++ Exceptions</h3> +<p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes +that support exception handling. However, to ensure compatibility with earlier releases, it +compiles all C++ sources with {@code -fno-exceptions} support by default. You can enable C++ +exceptions either for your entire app, or for individual modules. + +<p>To enable exception-handling support for your entire app, add the following line to +your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. +To enable exception-handling support for individual modules', add the following line to +their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files.</p> + +<pre> +APP_CPPFLAGS += -fexceptions +</pre> + +<h3 id="rt">RTTI</h3> +<p>In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes +that support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++ +sources with {@code -fno-rtti} by default. + +<p>To enable RTTI support for your entire app for your entire application, add the following line to +your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file: + +<pre> +APP_CPPFLAGS += -frtti +</pre> + +To enable RTTI support for individual modules, add the following line to +their respective <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files: + +<pre> +LOCAL_CPP_FEATURES += rtti +</pre> + +Alternatively, you can use: + +<pre> +LOCAL_CPPFLAGS += -frtti +</pre> + +<h3 id="sr">Static runtimes</h3> +<p>Linking the static library variant of a C++ runtime to more than one binary may result in +unexpected behavior. For example, you may experience:</p> + +<ul> +<li>Memory allocated in one library, and freed in the other, causing memory leakage or heap +corruption.</li> +<li>Exceptions raised in {@code libfoo.so} going uncaught in {@code libbar.so}, causing your app +to crash.</li> +<li>Buffering of {@code std::cout} not working properly</li> +</ul> + +<p>In addition, if you link two shared libraries–or a shared library and an executable– +against the same static runtime, the final binary image of each shared library includes a copy of +the runtime's code. Having multiple instances of runtime code is problematic because of duplication +of certain global variables that the runtime uses or provides internally.</p> + +<p>This problem does not apply to a project comprising a single shared library. For example, +you can link against {@code stlport_static}, and expect your app to behave correctly. If your +project requires several shared library modules, we recommend that you use the shared library +variant of your C++ runtime.</p> + +<h3>Shared runtimes</h3> +<p>If your app targets a version of Android earlier than Android 4.3 (Android API level 18), +and you use the shared library variant of a given C++ runtime, you must load the shared library +before any other library that depends on it.</p> + +<p>For example, an app may have the following modules:</p> + +<ul> +<li>libfoo.so</li> +<li>libbar.so which is used by libfoo.so</li> +<li>libstlport_shared.so, used by both libfoo and libbar</li> +</ul> + +<p>You must load the libraries in reverse dependency order: </p> +<pre> + static { + System.loadLibrary("stlport_shared"); + System.loadLibrary("bar"); + System.loadLibrary("foo"); + } +</pre> + +<p class="note"><strong>Note: </strong>Do not use the {@code lib} prefix when calling +{@code System.loadLibrary()}.</p> + +<h2 id="li">Licensing</h2> + +<p>STLport is licensed under a BSD-style open-source license. See +{@code $NDK/sources/cxx-stl/stlport/README} for more details about STLport.</p> + +<p>GNU libstdc++ is covered by the GPLv3 license, and <em>not</em> the LGPLv2 or LGPLv3. For +more information, see <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html"> +License</a> on the GCC website.</p> + +<p><a href="https://llvm.org/svn/llvm-project/libcxx/trunk/LICENSE.TXT">LLVM {@code libc++}</a> +is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.</p> diff --git a/docs/html/ndk/guides/cpu-arm-neon.jd b/docs/html/ndk/guides/cpu-arm-neon.jd new file mode 100644 index 0000000..1d12937 --- /dev/null +++ b/docs/html/ndk/guides/cpu-arm-neon.jd @@ -0,0 +1,109 @@ +page.title=NEON Support +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#ul">Using {@code LOCAL_ARM_NEON}</a></li> + <li><a href="#uns">Using the {@code .neon} Suffix</a></li> + <li><a href="#build">Build Requirements</a></li> + <li><a href="#rd">Runtime Detection</a></li> + <li><a href="#sc">Sample Code</a></li> + </ol> + </div> + </div> + +<p>The NDK supports the ARM Advanced SIMD, an optional instruction-set extension of the ARMv7 spec. +NEON provides a set of scalar/vector instructions and registers (shared with the FPU) comparable to +MMX/SSE/3DNow! in the x86 world. To function, it requires VFPv3-D32 (32 hardware FPU 64-bit +registers, instead of the minimum of 16).</p> + +<p>The NDK supports the compilation of modules or even specific source files with support for NEON. +As a result, a specific compiler flag enables the use of GCC ARM NEON intrinsics and VFPv3-D32 +at the same time.</p> + +<p>Not all ARMv7-based Android devices support NEON, but devices that do may benefit significantly +from its support for scalar/vector instructions. For x86 devices, the NDK can also translate NEON +instructions into SSE, although with several restrictions. For more information, see +<a href="{@docRoot}ndk/guides/x86.html#an">x86 Support for ARM NEON Intrinsics.</a></p> + +<h2 id="ul">Using LOCAL_ARM_NEON</h2> +<p>To have the NDK build all its source files with NEON support, include the following line in +your module definition:</p> + +<pre class="no-pretty-print"> +LOCAL_ARM_NEON := true +</pre> + +<p>It can be especially useful to build all source files with NEON support if you want to build a +static or shared library that specifically contains NEON code paths.</p> + +<h2 id="uns">Using the .neon Suffix</h2> +<p>When listing source files for your {@code LOCAL_SRC_FILES} variable, you have the option of +using the {@code .neon} suffix to indicate that you want to build binaries with NEON support. +For example, the following example builds one file with {@code .neon} support, and another +without it:</p> + +<pre class="no-pretty-print"> +LOCAL_SRC_FILES := foo.c.neon bar.c +</pre> + +<p>You can combine the {@code .neon} suffix with the {@code .arm} suffix, which specifies the 32-bit +ARM instruction set for non-NEON instructions. In such a definition, {@code arm} must come before +{@code neon}. For example: {@code foo.c.arm.neon} works, but {@code foo.c.neon.arm} does not.</p> + +<h2 id="build">Build Requirements</h2> +<p>NEON support only works with the {@code armeabi-v7a} and {@code x86} ABIs. If the NDK build +scripts encounter other ABIs while attempting to build with NEON support, the NDK build scripts +exit. x86 provides <a href="x86.html">partial NEON support</a> via translation header. It is +important to use checks like the following in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre class="no-pretty-print"> +# define a static library containing our NEON code +ifeq ($(TARGET_ARCH_ABI),$(filter $(TARGET_ARCH_ABI), armeabi-v7a x86)) +include $(CLEAR_VARS) +LOCAL_MODULE := mylib-neon +LOCAL_SRC_FILES := mylib-neon.c +LOCAL_ARM_NEON := true +include $(BUILD_STATIC_LIBRARY) +endif # TARGET_ARCH_ABI == armeabi-v7a || x86 +</pre> + +<h2 id="rd">Runtime Detection</h2> +<p>Your app must perform runtime detection to confirm that NEON-capable machine code can be run on +the target device. This is because not all ARMv7-based Android devices support NEON. The app can +perform this check using the +<a href="{@docRoot}ndk/guides/cpu-features.html">{@code cpufeatures}</a> library that comes with +this NDK.</p> + +<p>You should explicitly check that {@code android_getCpuFamily()} returns {@code +ANDROID_CPU_FAMILY_ARM}, and that {@code android_getCpuFeatures()} returns a value including the +{@code ANDROID_CPU_ARM_FEATURE_NEON flag} set. For example: </p> + +<pre class="no-pretty-print"> +#include <cpu-features.h> +... +... +if (android_getCpuFamily() == ANDROID_CPU_FAMILY_ARM && + (android_getCpuFeatures() & ANDROID_CPU_ARM_FEATURE_NEON) != 0) +{ + // use NEON-optimized routines + ... +} +else +{ + // use non-NEON fallback routines instead + ... +} + +... +</pre> + +<h2 id="sc">Sample Code</h2> +<p>The source code for the NDK's hello-neon sample provides an example of how to use the +{@code cpufeatures} library and NEON intrinsics at the same time. This sample implements a tiny +benchmark for a FIR filter loop using a C version, and a NEON-optimized one for devices that +support it.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/cpu-features.jd b/docs/html/ndk/guides/cpu-features.jd new file mode 100644 index 0000000..b031909 --- /dev/null +++ b/docs/html/ndk/guides/cpu-features.jd @@ -0,0 +1,210 @@ +page.title=The cpufeatures Library +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#usage">Usage</a></li> + <li><a href="#functions">Functions</a></li> + <li><a href="#ch">Change History</a></li> + </ol> + </div> + </div> + +<p>The NDK provides a small library named {@code cpufeatures} that your app can use at runtime to +detect the target device's CPU family and the optional features it supports. It is designed to work +as-is on all official Android platform versions.</p> + +<h2 id="usage">Usage</h2> +<p>The {@code cpufeatures} library is available as an import module. To use it, follow the procedure +below:</p> + +<ol> +<li>List {@code cpufeatures} in your list of static library dependencies. For example: + +<pre class="no-pretty-print"> +LOCAL_STATIC_LIBRARIES := cpufeatures +</pre> +</li> + +<li>In your source code, include the {@code <cpu-features.h>} header file.</li> + +<li>At the end of your <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file, +insert an instruction to import the {@code android/cpufeatures} module. For example: + +<pre class="no-pretty-print"> +$(call import-module,android/cpufeatures) +</pre> + +<p>Here is a simple example of an {@code Android.mk} file that imports the {@code cpufeatures} +library:</p> + +<pre class="no-pretty-print"> +<project-path>/jni/Android.mk: +LOCAL_PATH := $(call my-dir) + +include $(CLEAR_VARS) +LOCAL_MODULE := <your-module-name> +LOCAL_SRC_FILES := <your-source-files> +LOCAL_STATIC_LIBRARIES := cpufeatures +include $(BUILD_SHARED_LIBRARY) + +$(call import-module,android/cpufeatures) +</pre> +</li> +</ol> + +<h2 id="functions">Functions</h2> +<p>The {@code cpufeatures} library provides two functions. The first function returns the family to +which the device's CPU belongs. Declare it as follows:</p> + +<pre class="no-pretty-print"> +AndroidCpuFamily android_getCpuFamily(); +</pre> + +<p>The function returns one of the following enums, representing the CPU family/architecture that +the device supports.</p> +<ul> +<li>{@code ANDROID_CPU_FAMILY_ARM}</li> +<li>{@code ANDROID_CPU_FAMILY_X86}</li> +<li>{@code ANDROID_CPU_FAMILY_MIPS}</li> +<li>{@code ANDROID_CPU_FAMILY_ARM64}</li> +<li>{@code ANDROID_CPU_FAMILY_X86_64}</li> +<li>{@code ANDROID_CPU_FAMILY_MIPS64}</li> +</ul> + +<p>For a 32-bit executable on a 64-bit system, this function returns only the 32-bit value.</p> + +<p>The second function returns the set of optional features that the device's CPU supports. Declare +it as follows: + +<pre class="no-pretty-print"> +uint64_t android_getCpuFeatures(); +</pre> + +<p>The return value takes the form of a set of bit flags, each flag representing one +CPU-family-specific feature. The rest of this section provides information on features for +the respective families.</p> + +<h4>32-bit ARM CPU family</h4> + +<p>The following flags are available for the 32-bit ARM CPU family:</p> +<dl> +<dt>{@code ANDROID_CPU_ARM_FEATURE_VFPv2}</dt> +<dd>Indicates that the device's CPU supports the VFPv2 instruction set. Most ARMv6 CPUs support +this instruction set.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_ARMv7}</dt> +<dd>Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the +<a href="{@docRoot}ndk/guides/abis.html#v7a">armeabi-v7a</a> ABI. This instruction set supports both +Thumb-2 and VFPv3-D16 instructions. This return value also indicates support for the VFPv3 hardware +FPU instruction-set extension.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_VFPv3}</dt> +<dd>Indicates that the device's CPU supports the VFPv3 hardware FPU instruction-set extension. +<p>This value is equivalent to the {@code VFPv3-D16} instruction set, which provides provides only +16 hardware double-precision FP registers.</p></dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_D32}</dt> +<dd> Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of +16. Even when there are 32 hardware double-precision FP registers, there are still only 32 +single-precision registers mapped to the same register banks.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_NEON}</dt> +<dd>Indicates that the device's CPU supports the ARM Advanced SIMD (NEON) vector instruction set +extension. Note that ARM mandates that such CPUs also implement VFPv3-D32, which provides 32 +hardware FP registers (shared with the NEON unit).</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_FP16}</dt> +<dd>Indicates that the device's CPU supports instructions to perform floating-point operations on +16-bit registers. This feature is part of the VFPv4 specification.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_FMA}</dt> +<dd>Indicates that the device's CPU supports the fused multiply-accumulate extension for the VFP +instruction set. Also part of the VFPv4 specification.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_NEON_FMA}</dt> +<dd>Indicates that the device's CPU supports the fused multiply-accumulate extension for the NEON +instruction set. Also part of the VFPv4 specification.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_IDIV_ARM}</dt> +<dd>Indicates that the device's CPU supports integer division in ARM mode. Only available on later- +model CPUs, such as Cortex-A15.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2}</dt> +<dd>Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on +later-model CPUs, such as Cortex-A15.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_iWMMXt}</dt> +<dd>Indicates that the device's CPU supports an instruction-set extension that adds MMX registers +and instructions. This feature is only available on a few XScale- based CPUs.</dd> + +<dt>{@code ANDROID_CPU_ARM_FEATURE_LDREX_STREX}</dt> +<dd>Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. +Together, these instructions provide atomic updates on memory with the help of exclusive +monitor.</dd> +</dl> + +<h4>64-bit ARM CPU family</h4> + +<p>The following flags are available for the 64-bit ARM CPU family:</p> +<dl> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_FP}</dt> +<dd>Indicates that the device's CPU has a Floating Point Unit (FPU). All Android ARM64 devices must +support this feature.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_ASIMD}</dt> +<dd>Indicates that the device's CPU has an Advanced SIMD (ASIMD) unit. All Android ARM64 devices +must support this feature.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_AES}</dt> +<dd>Indicates that the device's CPU supports {@code AES} instructions.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_CRC32}</dt> +<dd>Indicates that the device's CPU supports {@code CRC32} instructions.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_SHA1}</dt> +<dd>Indicates that the device's CPU supports {@code SHA1} instructions.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_SHA2}</dt> +<dd>Indicates that the device's CPU supports {@code SHA2} instructions.</dd> +<dt>{@code ANDROID_CPU_ARM64_FEATURE_PMULL}</dt> +<dd>Indicates that the device's CPU supports 64-bit {@code PMULL} and {@code PMULL2} +instructions.</dd> +</dl> + +<h4>32-bit x86 CPU family</h4> + +<p>The following flags are available for the 32-bit x86 CPU family.<p> +<dl> +<dt>{@code ANDROID_CPU_X86_FEATURE_SSSE3}</dt> +Indicates that the device's CPU supports the SSSE3 instruction extension set.</dd> + +<dt>{@code ANDROID_CPU_X86_FEATURE_POPCNT}</dt> +<dd>Indicates that the device's CPU supports the {@code POPCNT} instruction.</dd> + +<dt>{@code ANDROID_CPU_X86_FEATURE_MOVBE}</dt> +<dd>Indicates that the device's CPU supports the {@code MOVBE} instruction. This instruction is +specific to some Intel IA-32 CPUs, such as Atom.</dd> +<dl> + +<p>{@code android_getCpuFeatures()} returns {@code 0} for CPU families for which there are no +listed extensions.</p> + +<p>The following function returns the maximum number of CPU cores on the target device: </p> + +<pre class="no-pretty-print"> +int android_getCpuCount(void); +</pre> + +<h4>MIPS CPU family</h4> + +<dl> +<dt>{@code ANDROID_CPU_MIPS_FEATURE_R6}</dt> +<dd>Indicates that the CPU executes MIPS Release 6 instructions natively, and supports obsoleted R1..R5 instructions only via kernel traps.</dd> + +<dt>{@code ANDROID_CPU_MIPS_FEATURE_MSA}</dt> +<dd>Indicates that the CPU supports MIPS SIMD Architecture instructions.</dd> +</dl> + +<h2 id="ch">Change History</h2> +<p>For the complete change history of this library, see the comments in +{@code $NDK/sources/android/cpufeatures/cpu-features.c}, where {@code $NDK} is the root of your +NDK installation.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/debug.jd b/docs/html/ndk/guides/debug.jd new file mode 100644 index 0000000..3c4da3b --- /dev/null +++ b/docs/html/ndk/guides/debug.jd @@ -0,0 +1,11 @@ +page.title=Debugging Your Project +@jd:body + +<p>After you've built your app, you'll probably need to debug it. This section introduces you to the +NDK's debugging tools.</p> + +<p>It begins by telling you how to use the <a href="{@docRoot}ndk/guides/ndk-gdb.html"> +{@code ndk-gdb}</a> tool to debug your code. It closes with an explanation of the +<a href="{@docRoot}ndk/guides/ndk-stack.html">{@code ndk-stack}</a> tool, which helps you use the +<a href="{@docRoot}tools/help/logcat.html">ADB logcat tool</a> +as you debug.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/guides_toc.cs b/docs/html/ndk/guides/guides_toc.cs new file mode 100644 index 0000000..981eb51 --- /dev/null +++ b/docs/html/ndk/guides/guides_toc.cs @@ -0,0 +1,75 @@ +<?cs # Table of contents for Dev Guide. + + For each document available in translation, add an localized title to this TOC. + Do not add localized title for docs not available in translation. + Below are template spans for adding localized doc titles. Please ensure that + localized titles are added in the language order specified below. +?> + +<ul id="nav"> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/index.html"> + <span class="en">Getting Started</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/setup.html">Setup</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/concepts.html">Concepts</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/build.html"> + <span class="en"> + Building</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/android_mk.html">Android.mk</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/application_mk.html">Application.mk</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/ndk-build.html">ndk-build</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/standalone_toolchain.html">Standalone Toolchain + </a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/arch.html"> + <span class="en">Architectures and CPUs</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/abis.html">ABI Management</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/cpu-arm-neon.html">NEON</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/x86.html">x86</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/x86-64.html">x86-64</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/mips.html">MIPS</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/cpu-features.html">The cpufeatures Library</a> + </li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/debug.html"> + <span class="en">Debugging</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/ndk-gdb.html">ndk-gdb</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/ndk-stack.html">ndk-stack</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/libs.html"> + <span class="en">Libraries</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/prebuilts.html">Prebuilt Libraries</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/cpp-support.html">C++ Support</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/stable_apis.html">Stable APIs</a></li> + + </ul> + </li> + +</ul> + + +<script type="text/javascript"> +<!-- + buildToggleLists(); + changeNavLang(getLangPref()); +//--> +</script> + diff --git a/docs/html/ndk/guides/images/NDK_build_string.png b/docs/html/ndk/guides/images/NDK_build_string.png Binary files differnew file mode 100644 index 0000000..338378b --- /dev/null +++ b/docs/html/ndk/guides/images/NDK_build_string.png diff --git a/docs/html/ndk/guides/images/NDK_build_string@2x.png b/docs/html/ndk/guides/images/NDK_build_string@2x.png Binary files differnew file mode 100644 index 0000000..5ba3ce3 --- /dev/null +++ b/docs/html/ndk/guides/images/NDK_build_string@2x.png diff --git a/docs/html/ndk/guides/images/verification_screen.png b/docs/html/ndk/guides/images/verification_screen.png Binary files differnew file mode 100644 index 0000000..91858ba --- /dev/null +++ b/docs/html/ndk/guides/images/verification_screen.png diff --git a/docs/html/ndk/guides/images/verification_screen@2x.png b/docs/html/ndk/guides/images/verification_screen@2x.png Binary files differnew file mode 100644 index 0000000..0d666c9 --- /dev/null +++ b/docs/html/ndk/guides/images/verification_screen@2x.png diff --git a/docs/html/ndk/guides/index.jd b/docs/html/ndk/guides/index.jd new file mode 100644 index 0000000..465ce13 --- /dev/null +++ b/docs/html/ndk/guides/index.jd @@ -0,0 +1,25 @@ +page.title=Getting Started with the NDK +@jd:body + +<p>The Native Development Kit (NDK) is a set of tools that allow you to leverage C and +C++ code in your Android apps. You can use it either to build from your own source code, or to take +advantage of existing prebuilt libraries.</p> + +<p>The NDK is not appropriate for most novice Android programmers, and has little value for many +types of Android apps. It is often not worth the additional complexity it inevitably brings to the +development process. However, it can be useful in cases in which you need to:</p> + +<ul> + <li>Squeeze extra performance out of a device for computationally intensive applications like + games or physics simulations.</li> + <li>Reuse your own or other developers' C or C++ libraries.</li> +</ul> + +<p>This guide gives you the information you need to get up and running with the NDK. It starts by +explaining the <a href="{@docRoot}ndk/guides/concepts.html">concepts</a> underpinning the NDK, and +how to <a href="{@docRoot}ndk/guides/setup.html">set it up</a>. Next, it continues with information +about targeting <a href="{@docRoot}ndk/guides/arch.html">different hardware platforms</a> in your +builds. Then, it explains how to use +the NDK to <a href="{@docRoot}ndk/guides/build.html">build</a> and +<a href="{@docRoot}ndk/guides/debug.html">debug</a> your app. Finally, it discusses how to use your +own and other prebuilt <a href="{@docRoot}ndk/guides/libs.html">libraries</a>.</p> diff --git a/docs/html/ndk/guides/libs.jd b/docs/html/ndk/guides/libs.jd new file mode 100644 index 0000000..ea607de --- /dev/null +++ b/docs/html/ndk/guides/libs.jd @@ -0,0 +1,13 @@ +page.title=Using Existing Libraries +@jd:body + +<p>This section discusses the use of existing libraries–both your own, and those that the NDK +provides.</p> + +<p>It begins by telling you how to use your own <a href="{@docRoot}ndk/guides/prebuilts.html"> +prebuilt libraries</a>. Then, it explains the <a href="{@docRoot}ndk/guides/cpp-support.html"> +C++ helper runtimes</a> available with the NDK, and how to use them. Finally, it provides +information on <a href="{@docRoot}ndk/guides/stable_apis.html">the other libraries</a> that the NDK provides, such +as <a href="https://www.khronos.org/opengles/">OpenGL ES</a> and +<a href="https://www.khronos.org/opensles/">OpenSL ES</a>, and the minimum Android API levels +required to support those libraries.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/mips.jd b/docs/html/ndk/guides/mips.jd new file mode 100644 index 0000000..2b4eea4 --- /dev/null +++ b/docs/html/ndk/guides/mips.jd @@ -0,0 +1,43 @@ +page.title=MIPS Support +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#over">Overview</a></li> + <li><a href="#comp">Compatibility</a></li> + </ol> + </div> + </div> + +<p>The NDK supports the {@code mips} ABI, which allows native code to run on Android-based devices +that have CPUs supporting the MIPS32 instruction set.</p> + +<h2 id="over">Overview</h2> +<p>To generate MIPS machine code, include {@code mips} in your +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file's +{@code APP_ABI} definition. For example: </p> + +<pre class="no-pretty-print"> +APP_ABI := mips +</pre> + +<p>For more information about defining the {@code APP_ABI} variable, see +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p> + +<p>The build system places generated libraries into {@code $PROJECT/libs/mips/}, where +{@code $PROJECT} represents your project's root directory, and embeds them in your APK under +the {@code /lib/mips/} directory.</p> + +<p>The Android package manager extracts these libraries when installing your APK on a compatible +MIPS-based device, placing them under your app's private data directory.</p> + +<p>In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.</p> + +<h2 id="comp">Compatibility</h2> +<p>MIPS support requires, at minimum, Android 2.3 (Android API level 9). If your project files +target an older API level, but include MIPS as a targeted platform, the NDK build script +automatically selects the right set of native platform headers/libraries for you.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/ndk-build.jd b/docs/html/ndk/guides/ndk-build.jd new file mode 100644 index 0000000..18ca2d8 --- /dev/null +++ b/docs/html/ndk/guides/ndk-build.jd @@ -0,0 +1,192 @@ +page.title=ndk-build +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#int">Internals</a></li> + <li><a href="#ifc">Invoking from the Command Line</a></li> + <li><a href="#ife">Invoking from Eclipse</a></li> + <li><a href="#6432">64-Bit and 32-Bit Toolchains</a></li> + <li><a href="#req">Requirements</a></li> + </ol> + </li> + </ol> + </div> + </div> + +<p>The {@code ndk-build} file is a shell script introduced in Android NDK r4. Its purpose +is to invoke the right NDK build script. + +<h2 id="int">Internals</h2> + +<p>Running the {@code ndk-build} script is equivalent to running the following command:</p> + +<pre class="no-pretty-print"> +$GNUMAKE -f <ndk>/build/core/build-local.mk +<parameters> +</pre> + +<p><code>$GNUMAKE</code> points to GNU Make 3.81 or later, and +<code><ndk></code> points to your NDK installation directory. You can use +this information to invoke ndk-build from other shell scripts, or even your own +make files.</p> + +<h2 id="ifc">Invoking from the Command Line</h2> +<p>The {@code ndk-build} file lives in the top level the NDK installation directory. To run it +from the command line, invoke it while in or under your application project directory. +For example: </p> + +<pre class="no-pretty-print"> +cd <project> +$ <ndk>/ndk-build +</pre> + +<p>In this example, <code><project></code> points to your +project’s root directory, and <code><ndk></code> is the directory where +you installed the NDK.</p> + +<p><a class="anchor" id="options"></a> </p> +<h3>Options</h3> +<p>All parameters to ndk-build are passed directly to the underlying GNU {@code make} +command that runs the NDK build scripts. Combine <code>ndk-build</code> and +options in the form <code>ndk-build <option></code>. For example: </p> + +<pre class="no-pretty-print"> +$ ndk-build clean +</pre> + +<p>The following options are available:</p> +<dl> + <dt>{@code clean}</dt> + <dd>Remove any previously generated binaries.</dd> + <dt>{@code V=1}</dt> + <dd>Launch build, and display build commands.<dd> + <dt>{@code -B}</dt> + <dd>Force a complete rebuild.</dd> + <dt>{@code -B V=1}</dt> + <dd>Force a complete rebuild, and display build commands.</dd> + <dt>{@code NDK_LOG=1}</dd> + <dd>Display internal NDK log messages (used for debugging the NDK itself).</dd> + <dt>{@code NDK_DEBUG=1}</dt> + <dd>Force a debuggable build (see <a href="#dvr">Table 1</a>).</dd> + <dt>{@code NDK_DEBUG=0}</dt> + <dd>Force a release build (see <a href="#dvr">Table 1</a>).</dd> + <dt>{@code NDK_HOST_32BIT=1}</dt> + <dd>Always use the toolchain in 32-bit mode (see <a href="#6432">64-bit and 32-bit + Toolchains</a>).</dd> + <dt>{@code NDK_APPLICATION_MK=<file>}</dt> + <dd>Build, using a specific <code>Application.mk</code> file pointed to by the + {@code NDK_APPLICATION_MK} variable.</dd> + <dt>{@code -C <project>}</dt> + <dd>Build the native code for the project path located at {@code <project>}. Useful if you + don't want to {@code cd} to it in your terminal.</dd> +</dl> + +<h2 id="ife">Invoking from Eclipse</h2> +<p>To build from Eclipse, make sure that you have configured it as described in +<a href="{@docRoot}ndk/guides/setup.html#configure">Setup</a>. If you +wish to build using the default <code>ndk-build</code> command, with no +options, you can just build your project just as you would any Android project. +To get Eclipse to add any of the options described above, follow these steps:</p> +<ol type="1"> +<li>In the <em>Project Explorer</em> pane, right-click your project name.</li> +<li>Select <strong>Properties</strong>.</li> +<li>Click <strong>C/C++ Build</strong>.</li> +<li>Under the <em>Builder Settings</em> tab, uncheck <strong>Use default build command</strong>.</li> +<li>In the <em>Build command</em> field, enter the entire build string as if you were typing it on +the command line.</li> +<li>Click <strong>OK</strong>.</li> +</ol> +Figure 1 shows an example of an entered string.<br> +<br> +<img src="./images/NDK_build_string.png" + srcset="./images/NDK_build_string@2x.png 2x" + alt="enter the build string next to 'Build command'" + height="152" width="501"> +<p style="clear:both"><b>Figure 1.</b> Specifying a debug build from within +Eclipse</p> +<p><a class="anchor" id="dvr"></a> </p> +<h3>Debuggable versus Release builds</h3> +<p>Use the <code>NDK_DEBUG</code> option and, in certain cases, +{@code AndroidManifest.xml} to specify debug or release build, +optimization-related behavior, and inclusion of symbols. Table 1 shows the +results of each possible combination of settings.</p> +<p><em>Table 1.</em> Results of <code>NDK_DEBUG</code> (command line) and +<code>android:debuggable</code> (manifest) combinations.</p> +<table> +<tr> +<th></th><th>NDK_DEBUG=0 </th><th>NDK_DEBUG=1</th><th>NDK_DEBUG not specified +</th></tr> +<tr> +<td>android:debuggble="true" </td><td>Debug; Symbols; Optimized*1 +</td><td>Debug; Symbols; Not optimized*2 </td><td>(same as NDK_DEBUG=1) +</td></tr> +<tr> +<td>android:debuggable="false"</td><td>Release; Symbols; Optimized +</td><td>Release; Symbols; Not optimized</td><td>Release; No symbols; +Optimized*3 </td></tr> +</table> +*1: Useful for profiling.<br> +*2: Default for running <a href="{@docRoot}ndk/guides/ndk-gdb.html">{@code ndk-gdb}</a>.<br> +*3: Default mode.<br> +<br> +<p class="note"><strong>Note:</strong> {@code NDK_DEBUG=0} is the equivalent of +{@code APP_OPTIM=release}, and complies with the GCC {@code -O2} option. {@code NDK_DEBUG=1} is the +equivalent of {@code APP_OPTIM=debug} in {@code Application.mk}, and complies with the GCC +{@code -O0} option. For more information about {@code APP_OPTIM}, see +<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p> +<p>The syntax on the command line is, for example: </p> + +<pre class="no-pretty-print"> +$ ndk-build NDK_DEBUG=1 +</pre> + +<p>If you are using build tools from prior to SDK r8, you must also modify your +{@code AndroidManifest.xml} file to specify debug mode. The syntax for doing so resembles the +following:</p> + +<pre class="no-pretty-print"><application android:label="@string/app_name" +android:debuggable="true"> +</pre> + +From SDK r8 onward, you do not need to touch {@code AndroidManifest.xml}. Building a debug package +(e.g. with ant debug or the corresponding option of the ADT plugin) causes the tool automatically to +pick the native debug files generated with {@code NDK_DEBUG=1}. + + +<h2 id="6432">64-Bit and 32-Bit Toolchains</h2> +<p>Some toolchains come with both 64-bit and 32-bit versions. For example, +directories {@code <ndk>/toolchain/<name>/prebuilt/} and +{@code <ndk>/prebuilt/} may contain both {@code linux-x86} and +{@code linux-x86_64} folders for Linux tools in 32-bit and 64-bit modes, +respectively. The ndk-build script automatically chooses a 64-bit version of +the toolchain if the host OS supports it. You can force the use of a 32-bit +toolchain by using {@code NDK_HOST_32BIT=1} either in your environment or +on the ndk-build command line.</p> +<p>Note that 64-bit tools utilize host resources better (for instance, they are faster, and handle +larger programs), and they can still generate 32-bit binaries for Android.</p> + +<h2 id="req">Requirements</h2> +<p>You need GNU Make 3.81 or later to use ndk-build or the NDK in general. +The build scripts will detect a non-compliant Make tool, and generate an error +message.</p> +<p>If you have GNU Make 3.81 installed, but the default <code>make</code> +command doesn’t launch it, define {@code GNUMAKE} in your environment to point to it +before launching ndk-build. For example: </p> + +<pre class="no-pretty-print"> +$ export GNUMAKE=/usr/local/bin/gmake +$ ndk-build +</pre> + +<p>You can override other host prebuilt tools in {@code $NDK/prebuilt/<OS>/bin/} +with the following environment variables: </p> + +<pre class="no-pretty-print"> +$ export NDK_HOST_AWK=<path-to-awk> +$ export NDK_HOST_ECHO=<path-to-echo> +$ export NDK_HOST_CMP=<path-to-cmp> +</pre> diff --git a/docs/html/ndk/guides/ndk-gdb.jd b/docs/html/ndk/guides/ndk-gdb.jd new file mode 100644 index 0000000..b15e67e --- /dev/null +++ b/docs/html/ndk/guides/ndk-gdb.jd @@ -0,0 +1,241 @@ +page.title=ndk-gdb +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#req">Requirements</a></li> + <li><a href="#use">Usage</a></li> + <li><a href="#thread">Thread Support</a></li> + </ol> + </div> + </div> + +<p>The NDK includes a helper shell script named {@code ndk-gdb} to easily launch a native debugging + session for your NDK-generated machine code.</p> + +<h2 id="req">Requirements</h2> + +<p>For native debugging to work, you must follow these requirements:</p> + +<ul> +<li>Build your app using the {@code ndk-build} script. The {@code ndk-gdb} script +does not support using the legacy {@code make APP=<name>} method to build.</p></li> +<li>Enable app debugging in your {@code AndroidManifest.xml} file by including an +{@code <application>} element that sets the {@code android:debuggable} attribute to {@code +true}.</li> +<li>Build your app to run on Android 2.2 (Android API level 8) or higher.</li> +<li>Debug on a device or emulator running Android 2.2 or higher. For debugging purposes, the target +API level that you declare in your {@code AndroidManifest.xml} file does not matter.</li> +<li>Develop your app in a Unix shell. On Windows, use <a href="https://www.cygwin.com/">Cygwin</a> +or the experimental {@code ndk-gdb-py} <a href="https://www.python.org/">Python</a> +implementation.</li> +<li>Use GNU Make 3.81 or higher.</li> +<li>If you are building your app from +<a href="{@docRoot}sdk/installing/installing-adt.html">Eclipse</a>, build it +using version 0.9.7 or higher of the ADT plug-in.</li> + +<h2 id="use">Usage</h2> + To invoke the {@code ndk-gdb} script, change into the application directory or any directory under + it. For example:</p> + +<pre class="no-pretty-print"> +cd $PROJECT +$NDK/ndk-gdb +</pre> + +<p>Here, {@code $PROJECT} points to your project's root directory, and {@code $NDK} points to your +NDK installation path.</p> + +<p>When you invoke {@code ndk-gdb}, it configures the session to look for your source files +and symbol/debug versions of your generated native libraries. On successfully attaching to your +application process, {@code ndk-gdb} outputs a long series of error messages, noting that it cannot +find various system libraries. This is normal, because your host machine does not contain +symbol/debug versions of these libraries on your target device. You can safely ignore these +messages.</p> + +<p>Next, {@code ndk-gdb} displays a normal GDB prompt.</p> + +<p>You interact with {@code ndk-gdb} in the same way as you would with GNU GDB. For example, you can +use {@code b <location>} to set breakpoints, and {@code c} (for "continue") to +resume execution. For a comprehensive list of commands, see the +<a href="http://www.gnu.org/software/gdb/">GDB manual.</a></p> + +<p>Note that when you quit the GDB prompt, the application process that you're debugging stops. This +behavior is a gdb limitation.</p> + +<p>{@code ndk-gdb} handles many error conditions, and displays an informative error message if it +finds a problem. these checks include making sure that the following conditions are satisfied:</p> + +<ul> +<li>Checks that ADB is in your path.</li> +<li>Checks that your application is declared debuggable in its manifest.</li> +<li>Checks that, on the device, the installed application with the same package name is also +debuggable.</li> +</ul> + +<p>By default, {@code ndk-gdb} searches for an already-running application process, and displays an +error if it doesn't find one. You can, however, use the {@code --start} or +{@code --launch=<name>} option to automatically start your activity before the debugging +session. For more information, see <a href="#opt">Options</a>.</p> + + +<h3 id="opt">Options</h3> +<p>To see a complete list of options, type {@code ndk-gdb --help} on the command line. Table 1 +shows a number of the more commonly used ones, along with brief descriptions.</p> + +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> Common ndk-gdb options and their descriptions.</p> + +<table> +<tr> +<th>Option</th> +<th>Description></th> +<tr> + +<tr> +<td>{@code --verbose}</td> +<td><p>This option tells the build system to print verbose information about the native-debugging +session setup. It is necessary only for debugging problems when the debugger can't connect to the +app, and the error messages that {@code ndk-gdb} displays are not enough.</p></td> +</tr> + +<tr> +<td>{@code --force}</td> +<td>By default, {@code ndk-gdb} aborts if it finds that another native debugging session is already + running on the same device. This option kills the other session, and replaces it with a new one. + Note that this option does not kill the actual app being debugged, which you must kill + separately.</td> +</tr> + +<tr> +<td>{@code --start}</td> +<td><p>When you start {@code ndk-gdb}, it tries by default to attach to an existing running instance of +your app on the target device. You can override this default behavior by using {@code --start} to +explicitly launch the application on the target device before the debugging session.</p></td> + +<p>Starting {@code ndk-gdb} with this option specified launches the first launchable activity listed +in your application manifest. Use {@code --launch=<name>} to start the next launchable +activity. To dump the list of launchable activities, run {@code --launch-list} from the command +line.</p> +</tr> + +<tr> +<td>{@code --launch=<name>}</td> +<td><p>This option is similar to {@code --start}, except that it allows you to start a specific + activity from your application. This feature is only useful if your manifest defines multiple + launchable activities.</p></td> +</tr> + +<tr> +<td>{@code --launch-list}</td> +<td><p>This convenience option prints the list of all launchable activity names found in your + app manifest. {@code --start} uses the first activity name.</p></td> +</tr> + +<tr> +<td>{@code --project=<path>}</td> +<td>This option specifies the app project directory. It is useful if you want to launch the + script without first having to change to the project directory.</p></td> +</tr> + +<tr> +<td>{@code --port=<port>}</td> +<td> <p>By default, {@code ndk-gdb} uses local TCP port 5039 to communicate with the app it + is debugging on the target device. Using a different port allows you to natively debug programs + running on different devices or emulators connected to the same host machine.</p></td> +</tr> + +<tr> +<td>{@code --adb=<file>}</td> +<td><p>This option specifies the <a href="{@docRoot}tools/help/adb.html">adb</a> +tool executable. It is only necessary if you have not set your path to include that executable.</p> +</td> +</tr> + +<tr> +<td> +<li>{@code -d}</li> +<li>{@code -e}</li> +<li>{@code -s <serial>}</li></td> +<td><p>These flags are similar to the adb commands with the same names. Set these flags if you have +several devices or emulators connected to your host machine. Their meanings are as follows:</p> +<dl> + <dt>{@code -d}</dt> + <dd>Connect to a single physical device.</dd> + <dt>{@code -e}</dt> + <dd>Connect to a single emulator device.</dd> + <dt>{@code -s <serial>}</dt> + <dd>Connect to a specific device or emulator. Here, {@code <serial>} is the device's name + as listed by the {@code adb devices} command.</dd> +</dl> + +<p>Alternatively, you can define the {@code ADB_SERIAL} environment variable to list a specific +device, without the need for a specific option.</p></td> +</tr> + +<tr> +<td> +<li>{@code --exec=<file>}</li> +<li>{@code -x <file>}</li> +</td> +<td><p>This option tells {@code ndk-gdb} to run the GDB initialization commands found in +{@code <file>} after connecting to the process it is debugging. This is a useful feature if +you want to do something repeatedly, such as setting up a list of breakpoints, and then resuming +execution automatically.</p></td> +</tr> + +<tr> +<td>{@code --nowait}</td> +<td><p>Disable pausing the Java code until GDB connects. Passing this option may cause the debugger + to miss early breakpoints.</p> +</tr> + +<tr> +<td>{@code --tui} +{@code -t}</td> +<td><p>Enable Text User Interface if it is available.</p></td> +</tr> + +<tr> +<td>{@code --gnumake-flag=<flag>}</td> +<td><p>This option is an extra flag (or flags) to pass to the +{@code ndk-build} system when +querying it for project information. You can use multiple instances of this option in the +same command.</p></td> +</tr> + +<tr> +<td>{@code --stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}}</td> +<td><p>Use specified Python pretty-printers for displaying types in the Standard C++ Library. + {@code auto} mode works by looking at the {@code .so} files for a {@code libstdc++} library, + and as such only works for a shared library. When linking statically to a {@code libstdc++} library, + you must specify the required printers. The default is {@code none}.</p></td> +</tr> +</table> + +<p class="note"><strong>Note: </strong>The final three options in this table are only for the +Python version of {@code ndk-gdb}.</p></td> + +<h2 id="thread">Thread Support</h2> +<p>If your app runs on a platform older than Android 2.3 (API level 9), {@code ndk-gdb} +cannot debug native threads properly. The debugger can only debug the main thread, abd completely +ignores the execution of other threads.</p> + +<p>Using a version of Android prior to 2.3 causes {@code ndk-gdb} to display the following message +prior to showing the GDB prompt:</p> + +<pre class="no-pretty-print"> +Thread debugging is unsupported on this Android platform! +</pre> + + +<p>If you place a breakpoint on a function executed on a non-main thread, the program exits, and +GDB displays the following message:</p> + +<pre class="no-pretty-print"> +Program terminated with signal SIGTRAP, Trace/breakpoint trap. + The program no longer exists. +</pre> diff --git a/docs/html/ndk/guides/ndk-stack.jd b/docs/html/ndk/guides/ndk-stack.jd new file mode 100644 index 0000000..46146cb --- /dev/null +++ b/docs/html/ndk/guides/ndk-stack.jd @@ -0,0 +1,86 @@ +page.title=ndk-stack +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#use">Usage</a></li> + </ol> + </div> + </div> + +<p>The {@code ndk-stack} tool allows you to filter stack traces as they appear in the +output of <a href="{@docRoot}tools/help/logcat.html">{@code adb logcat}</a>. It also replaces any +address inside a shared library with the corresponding +{@code <source-file>:<line-number>} values from your source code, making issues easier +to pinpoint.</p> + +<p>For example, it translates something like:</p> + +<pre> +I/DEBUG ( 31): *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** +I/DEBUG ( 31): Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys' +I/DEBUG ( 31): pid: 351, tid: 351 %gt;%gt;%gt; /data/local/ndk-tests/crasher <<< +I/DEBUG ( 31): signal 11 (SIGSEGV), fault addr 0d9f00d8 +I/DEBUG ( 31): r0 0000af88 r1 0000a008 r2 baadf00d r3 0d9f00d8 +I/DEBUG ( 31): r4 00000004 r5 0000a008 r6 0000af88 r7 00013c44 +I/DEBUG ( 31): r8 00000000 r9 00000000 10 00000000 fp 00000000 +I/DEBUG ( 31): ip 0000959c sp be956cc8 lr 00008403 pc 0000841e cpsr 60000030 +I/DEBUG ( 31): #00 pc 0000841e /data/local/ndk-tests/crasher +I/DEBUG ( 31): #01 pc 000083fe /data/local/ndk-tests/crasher +I/DEBUG ( 31): #02 pc 000083f6 /data/local/ndk-tests/crasher +I/DEBUG ( 31): #03 pc 000191ac /system/lib/libc.so +I/DEBUG ( 31): #04 pc 000083ea /data/local/ndk-tests/crasher +I/DEBUG ( 31): #05 pc 00008458 /data/local/ndk-tests/crasher +I/DEBUG ( 31): #06 pc 0000d362 /system/lib/libc.so +I/DEBUG ( 31): +</pre> + +<p>into the more readable output: </p> + +<pre> +********** Crash dump: ********** +Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys' +pid: 351, tid: 351 >>> /data/local/ndk-tests/crasher <<< +signal 11 (SIGSEGV), fault addr 0d9f00d8 +Stack frame #00 pc 0000841e /data/local/ndk-tests/crasher : Routine zoo in /tmp/foo/crasher/jni/zoo.c:13 +Stack frame #01 pc 000083fe /data/local/ndk-tests/crasher : Routine bar in /tmp/foo/crasher/jni/bar.c:5 +Stack frame #02 pc 000083f6 /data/local/ndk-tests/crasher : Routine my_comparison in /tmp/foo/crasher/jni/foo.c:9 +Stack frame #03 pc 000191ac /system/lib/libc.so +Stack frame #04 pc 000083ea /data/local/ndk-tests/crasher : Routine foo in /tmp/foo/crasher/jni/foo.c:14 +Stack frame #05 pc 00008458 /data/local/ndk-tests/crasher : Routine main in /tmp/foo/crasher/jni/main.c:19 +Stack frame #06 pc 0000d362 /system/lib/libc.so +</pre> + +<h2>Usage</h2> +<p>To use {@code ndk-stack}, you first need a directory containing symbolic versions of your app's +shared libraries. If you use the NDK build system ({@code ndk-build}), these shared-library +files reside under {@code $PROJECT_PATH/obj/local/<abi>}, where {@code <abi>} represents +your device's ABI. By default, the system uses the {@code armeabi} ABI.</p> + +<p>There are two ways to use the tool. You can feed the logcat text as direct input to the program. +For example:</p> + +<pre class="no-pretty-print"> +adb logcat | $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi +</pre> + +<p>You can also use the {@code -dump} option to specify the logcat as an input file. For example: +</p> + +<pre class="no-pretty-print"> +adb logcat > /tmp/foo.txt +$NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi -dump foo.txt +</pre> + +<p>When it begins parsing the logcat output, the tool looks for an initial line of asterisks. +For example:</p> + +<pre class="no-pretty-print"> +*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** +</pre> + +<p class="note"><strong>Note: </strong>When copy/pasting traces, don't forget this line, or +{@code ndk-stack} won't work correctly.</p>
\ No newline at end of file diff --git a/docs/html/ndk/guides/prebuilts.jd b/docs/html/ndk/guides/prebuilts.jd new file mode 100644 index 0000000..52eb437 --- /dev/null +++ b/docs/html/ndk/guides/prebuilts.jd @@ -0,0 +1,145 @@ +page.title=Using Prebuilt Libraries +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#dm">Declaring a Prebuilt Library</a></li> + <li><a href="#rp">Referencing the Prebuilt Library from Other Modules</a></li> + <li><a href="#dp">Debugging Prebuilt Libraries</a></li> + <li><a href="#sa">Selecting ABIs for Prebuilt Libraries</a></li> + </ol> + </div> + </div> + +<p>The NDK supports the use of prebuilt libraries, both static and shared. There are two principal +use cases for this functionality:</p> + +<ul> + <li>Distributing your own libraries to third-party NDK developers without distributing your + sources.</li> + <li>Using a prebuilt version of your own libraries to speed up your build.</li> +</ul> + +<p>This page explains how to use prebuilt libraries.</p> + +<h2 id="dm">Declaring a Prebuilt Library</h2> +<p>You must declare each prebuilt library you use as a <em>single</em> independent module. To do + so, perform the following steps: + +<ol type="1"> + <li>Give the module a name. This name does not need to be the same as that of the prebuilt + library, itself.</li> + <li>In the module's <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> + file, assign to {@code LOCAL_SRC_FILES} the path to the prebuilt library you are providing. + Specify the path relative to the value of your {@code LOCAL_PATH} variable.</p> + <p class="note"><strong>Note: </strong> You must make sure to select the version of your prebuilt + library appropriate to your target ABI. For more information on ensuring library support for + ABIs, see <a href="#sa">Selecting ABIs for Prebuilt Libraries.</a></p></li> + <li>Include {@code PREBUILT_SHARED_LIBRARY} or {@code PREBUILT_STATIC_LIBRARY}, depending on + whether you are using a shared ({@code .so}) or static ({@code .a}) library.</li> +</ol> + + <p>Here is a trivial example that assumes the prebuilt library {@code libfoo.so} resides in + the same directory as the <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> + file that describes it.</p> + +<pre> +LOCAL_PATH := $(call my-dir) + +include $(CLEAR_VARS) +LOCAL_MODULE := foo-prebuilt +LOCAL_SRC_FILES := libfoo.so +include $(PREBUILT_SHARED_LIBRARY) +</pre> + +<p>In this example, the name of the module is the same as that of the prebuilt library.</p> + +<p>The build system places a copy of your prebuilt shared library into {@code $PROJECT/obj/local}, +and another copy, stripped of debug information, into {@code $PROJECT/libs/<abi>}. Here, +{@code $PROJECT} is the root directory of your project.</p> + +<h2 id="rp">Referencing the Prebuilt Library from Other Modules</h2> +<p>To reference a prebuilt library from other modules, specify its name as the value +of the {@code LOCAL_STATIC_LIBRARIES} or {@code LOCAL_SHARED_LIBRARIES} variable in the +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files associated with those +other modules.</p> + +<p>For example, the description of a module using {@code libfoo.so} might be as follows:</p> + +<pre> +include $(CLEAR_VARS) +LOCAL_MODULE := foo-user +LOCAL_SRC_FILES := foo-user.c +LOCAL_SHARED_LIBRARIES := foo-prebuilt +include $(BUILD_SHARED_LIBRARY) +</pre> + +<p>Here, {@code LOCAL_MODULE} is the name of the module referring to the prebuilt; {@code + LOCAL_SHARED_LIBRARIES} is the name of the prebuilt, itself.</p> + +<h2>Exporting Headers for Prebuilt Libraries</h2> +<p>The code in {@code foo-user.c} depends on specific declarations that normally +reside in a header file, such as {@code foo.h}, distributed with the prebuilt library. +For example, {@code foo-user.c} might have a line like the following:</p> + +<pre> +#include <foo.h> +</pre> + +<p>In such a case, you need to provide the header and its include path to the compiler when you +build the {@code foo-user} module. A simple way to accomplish this task is to use exports in the +prebuilt module definition. For example, as long as header {@code foo.h} is located under the +{@code include} directory associated with the prebuilt module, you can declare it as follows:</p> + +<pre> +include $(CLEAR_VARS) +LOCAL_MODULE := foo-prebuilt +LOCAL_SRC_FILES := libfoo.so +LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include +include $(PREBUILT_SHARED_LIBRARY) +</pre> + +<p>The {@code LOCAL_EXPORT_C_INCLUDES} definition here ensures that the build system +exports the path to the prebuilt library's {@code include} directory, prepending that path onto the +value of the {@code LOCAL_C_INCLUDES} for the module dependent on it.</p> + +<p>This operation allows the build system to find the necessary headers.</p> + +<h2 id="dp">Debugging Prebuilt Libraries</h2> +<p>We recommend that you provide prebuilt shared libraries containing debug symbols. The NDK build +system always strips the symbols from the version of the library that it installs into +{@code $PROJECT/libs/<abi>/}, but you can use the debug version for debugging with +{@code ndk-gdb}.</p> + +<h2 id="sa">Selecting ABIs for Prebuilt Libraries</h2> +<p>You must make sure to select the right version of your prebuilt shared library for your targeted +ABI. The <a href="{@docRoot}ndk/guides/android_mk.html#taa"> +{@code TARGET_ARCH_ABI}</a> variable in the <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file can point the build system at the appropriate version of the library. +</p> + +<p>For example, assume that your project contains two versions of library {@code libfoo.so}:</p> + +<pre class="no-pretty-print"> +armeabi/libfoo.so +x86/libfoo.so +</pre> + +<p>The following snippet shows how to use {@code TARGET_ARCH_ABI} so that the build system selects + the appropriate version of the library:</p> + +<pre> +include $(CLEAR_VARS) +LOCAL_MODULE := foo-prebuilt +LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libfoo.so +LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include +include $(PREBUILT_SHARED_LIBRARY) +</pre> + +<p>If you have specified {@code armeabi} as the value of {@code TARGET_ARCH_ABI}, the build system +uses the version of {@code libfoo.so} located in the {@code armeabi} directory. If you have +specified {@code x86} as the value {@code TARGET_ARCH_ABI}, the build system uses the version in the +{@code x86} directory.</p> diff --git a/docs/html/ndk/guides/sample.jd b/docs/html/ndk/guides/sample.jd new file mode 100644 index 0000000..18ca0b8 --- /dev/null +++ b/docs/html/ndk/guides/sample.jd @@ -0,0 +1,11 @@ +page.title=Sample Walkthroughs +@jd:body + +<div class="contents"> +<div class="textblock"><p>This section explains several of the sample apps provided with the NDK. It assumes that you already have a working knowledge of programming in Java and native code, and focuses on issues particular to working with the NDK.</p> +<p>It discusses the following samples:</p> +<ul> +<li><a href="./md_2__samples_sample--hellojni.html">hello-jni</a>: A very basic app that illustrates core workings of the NDK.</li> +<li><a href="./md_2__samples_sample--nativeactivity.html">native-activity</a>: An app that shows the fundamentals of how to construct a purely native app. It places particular emphasis on the android_native_app_glue library.</li> +<li><a href="./md_2__samples_samples-teapot.html">Teapot</a>: A simple OpenGL demo, showcasing the <code>ndk_helper</code> class. </li> +</ul>
\ No newline at end of file diff --git a/docs/html/ndk/guides/setup.jd b/docs/html/ndk/guides/setup.jd new file mode 100644 index 0000000..81a33c0 --- /dev/null +++ b/docs/html/ndk/guides/setup.jd @@ -0,0 +1,94 @@ +page.title=Setup +@jd:body + + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#install">Installation</a></li> + <li><a href="#configure">Configuring Eclipse</a></li> + <li><a href="#verify">Verification</a></li> + </ol> + </li> + </ol> + </div> + </div> + + +<div class="contents"> +<div class="textblock"><p>This document explains how to:</p> +<ul> +<li><a href="#install">Get</a> and install the NDK.</li> +<li><a href="#configure">Configure</a> your system and the Eclipse and the Android Development Tool +(ADT) for use with it.</li> +<li><a href="#verify">Verify</a>, using a simple sample, that everything is working as expected. +</li> +</ul> +<p>This document assumes that you are already familiar with Java-based Android development. For more +information on that topic, see the +<a href="{@docRoot}">Android developer site</a>.</p> + +<h2 id="install">Installation</h2> +<p>To install and configure the NDK, follow these steps:</p> +<ol type="1"> +<li>Get and install the <a href="{@docRoot}sdk/index.html">Android SDK</a>.</li> +<li><a href="{@docRoot}ndk/downloads/index.html">Download</a> and +<a href="{@docRoot}ndk/downloads/index.html#extract">extract</a> the NDK, +making sure to download the correct version for your development platform. You may place the +unzipped directory anywhere on your local drive.</li> +<li>Update your {@code PATH} environment variable with the location of the directory that +contains the NDK.</li> +</ol> + + +<h2 id="configure">Configuring Eclipse</h2> +<p>Eclipse must know where the NDK is in order to use it when building your app. Follow these steps +to set the location of the NDK.</p> +<ol type="1"> +<li>Launch Eclipse, which is installed as part of the Android SDK.</li> +<li>Open <b>Window</b> > <b>Preferences</b>.</li> +<li>In the pane on the left side of the <i>Preferences</i> window, select <i>Android</i>. +The <i>Android</i> section expands, revealing a number of subsections.</li> +<li>Select <b>NDK</b>. In the pane on the right side of the <i>Preferences</i> window, browse to +the directory that contains the NDK.</li> +<li>Click <b>OK</b> to return to the <i>Package Explorer</i> display.</li> +</ol> + +<h2 id="verify">Verification</h2> +<h3>Eclipse</h3> +<p>To confirm that you have installed the NDK, set it up correctly, and properly configured Eclipse, +follow these steps:</p> +<ol type="1"> +<li>Import the hello-jni sample from {@code <ndk>/samples/}, as you would any other Android +project.</li> +<li>In the <i>Project Explorer</i> pane, right-click the project name (<i>HelloJni</i>). A +context menu appears.</li> +<li>From the context menu, select <b>Android Tools</b> > <b>Add Native Support</b>. The +<i>Add Android Native Support</i> window appears.</li> +<li>Accept the default library name (“hello-jni”), and click <b>Finish</b>.</li> +<li>Build and execute the application.</li> +</ol> +<h3>Command line</h3> +<p>Follow these steps to build from the command line:</p> +<ol type="1"> +<li>Change to the root directory of your project.</li> +<li>Execute ndk-build to build the native component of your app. do this by +typing {@code ndk-build} at the command prompt.</li> +<li>Build and install your project as you would a regular Android app written in Java. For more +information, see +<a href="{@docRoot}tools/building/index.html">Building and Running</a> and +<a href="{@docRoot}tools/building/building-cmdline.html">Building and Running +from the Command Line</a>.</li> +</ol> + +<p>If you have successfully installed and configured the NDK, the screen on your target device looks +as shown in Figure 1.</p> + +<img src="./images/verification_screen.png" srcset="./images/verification_screen@2x.png 2x" +alt="Output: Hello from JNI!" id="figure1" /> + +<p class="img-caption"> +<strong>Figure 1.</strong> Target-device screen after successful launch. +</p> diff --git a/docs/html/ndk/guides/stable_apis.jd b/docs/html/ndk/guides/stable_apis.jd new file mode 100644 index 0000000..cad02ac --- /dev/null +++ b/docs/html/ndk/guides/stable_apis.jd @@ -0,0 +1,501 @@ +page.title=Android NDK Native APIs +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#purpose">Overview</a></li> + <li><a href="#mnu">Major Native API Updates</a><li> + <ol> + <li><a href="#a3">Android API level 3</a></li> + <li><a href="#a4">Android API level 4</a></li> + <li><a href="#a5">Android API level 5</a></li> + <li><a href="#a8">Android API level 8</a></li> + <li><a href="#a9">Android API level 9</a></li> + <li><a href="#a14">Android API level 14</a></li> + <li><a href="#a18">Android API level 18</a></li> + </ol> + </ol> + </div> + </div> + +<p>The Android NDK provides a set of native headers and shared library files that has gradually +increased with successive releases of new Android API levels. This page explains these headers and +files, and maps them to specific +<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels"> Android API levels</a>. +</p> + +<h2 id="purpose">Overview</h2> +<p>There are two basic steps to enable your app to use the libraries that the NDK provides: +</p> + +<ol type ="1"> +<li>Include in your code the headers associated with the libraries you wish to use.</li> + +<li>Tell the build system that your native module needs to link against the libraries at load time. +For example, to link against {@code /system/lib/libfoo.so}, add the following line to your +<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a> file:</li> + +<pre> +LOCAL_LDLIBS := -lfoo +</pre> + +<p>To list multiple libraries, use a space as a delimiter. For more information about using the +{@code LOCAL_LDLIBS} variable, see <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>. +</p> + +</ol> + +<p>For all API levels, the build system automatically links the standard C libraries, the +standard C++ libraries, real-time extensions, and {@code pthread}; you do not need +to include them when defining your {@code LOCAL_LDLIBS} variable. For more information about +the C and C++ libraries, see <a href="#a3">Android API level 3</a>.</p> + +<p>The NDK often provides new headers and libraries for new Android releases. These files reside +under {@code $NDK/platforms/android-<level>/<abi>/usr/include}. When the NDK does not +have a specific new group of headers and libraries for an Android API level, it means that +an app targeting that level should use the most recently released NDK assets. For example, +there was no new release of NDK headers or libraries for Android API levels 6 and 7. Therefore, +when developing an app targeting Android API level 7, you should use the headers and libraries +located under {@code android-5/}.</p> + +<p>Table 1 shows the correspondence between NDK-supported API levels and Android releases.</p> + +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> NDK-supported API levels and corresponding Android releases.</p> +<table> + <tr> + <th scope="col">NDK-supported API level</th> + <th scope="col">Android release</th> + </tr> + <tr> + <td>3</td> + <td>1.5</td> + </tr> + <tr> + <td>4</td> + <td>1.6</td> + </tr> + <tr> + <td>5</td> + <td>2.0</td> + </tr> + <tr> + <td>8</td> + <td>2.2</td> + </tr> + <tr> + <td>9</td> + <td>2.3 through 3.0.x</td> + </tr> + <tr> + <td>12</td> + <td>3.1.x</td> + </tr> + <tr> + <td>13</td> + <td>3.2</td> + </tr> + <tr> + <td>14</td> + <td>4.0 through 4.0.2</td> + </tr> + <tr> + <td>15</td> + <td>4.0.3 and 4.0.4</td> + </tr> + <tr> + <td>16</td> + <td>4.1 and 4.1.1</td> + </tr> + <tr> + <td>17</td> + <td>4.2 and 4.2.2</td> + </tr> + <tr> + <td>18</td> + <td>4.3</td> + </tr> + <tr> + <td>19</td> + <td>4.4</td> + </tr> + <tr> + <td>21</td> + <td>4.4W and 5.0</td> +</table> + +<p>Each new release of NDK headers and libraries for a given Android API level is cumulative; you +are nearly always safe if you use the most recently released headers when building your app. For +example, you can use the NDK headers for Android API level 21 for an app targeting API level 16. By doing so, however, you increase your APK's footprint.</p> + +<p> +For more information about Android API levels, see +<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API Level?</a>. +</p> + +<h2 id="mnu">Major Native API Updates</h2> + +<h3 id="a3">Android API level 3</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 1.5 system +images and above.</p> + +<h4>C library</h4> +<p>The C library headers for Android 1.5 are available through their standard names, such as +{@code stdlib.h} and {@code stdio.h}. If a header is missing at build time, it's because the +header is not available on the 1.5 system image.</p> + +<h4>C++ library</h4> +<p>An <em>extremely</em> minimal C++ support API is available. For more +information on C++ library support, see +<a href="{@docRoot}ndk/guides/cpp-support.html">C++ Library Support</a>.</p> + +<h4>Android-specific log support</h4> + +<p>{@code <android/log.h>} contains various definitions that an app can use to send log +messages to the kernel from native code. For more information about these definitions, see the +comments in {@code $NDK/platforms/android-3/arch-arm/usr/include/android/log.h}, where {@code $NDK} +is the root of your NDK installation.</p> + +<p>You can write your own wrapper macros to access this functionality. If you wish to perform +logging, your native module should link to {@code /system/lib/liblog.so}. Implement this +linking by including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -llog +</pre> + +<h4>ZLib compression library</h4> +<p>You can use the <a href="http://www.zlib.net/manual.html">Zlib compression library</a> +by including {@code zlib.h} and {@code zconf.h}. You must also link your native +module against {@code /system/lib/libz.so} by including the following line in your +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -lz +</pre> + +<h4>Dynamic linker library</h4> +<p>You can access the Android dynamic linker's {@code dlopen()}, {@code dlsym()}, and +{@code dlclose()} functions by including {@code dlfcn.h}. You must also link against +{@code /system/lib/libdl.so} by including the following line in your +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -ldl +</pre> + +<h3 id="a4">Android API level 4</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 1.6 system +images and above.</p> + +<h4>OpenGL ES 1.x Library</h4> +<p>The standard OpenGL ES headers {@code gl.h} and {@code glext.h} contain +the declarations necessary for performing OpenGL ES 1.x rendering calls from native code.</p> + +<p>To use these headers, link your native module to {@code /system/lib/libGLESv1_CM.so} by +including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> +</p> + +<pre> +LOCAL_LDLIBS := -lGLESv1_CM +</pre> +<p>All Android-based devices support OpenGL ES 1.0, because Android provides an Open GL 1.0-capable +software renderer that can be used on devices without GPUs.</p> +<p>Only Android devices that have the necessary GPU fully support OpenGL ES 1.1. An app can +query the OpenGL ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of +<a href="http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml">{@code glGetString()}</a> +in the OpenGL specification.</p> + +<p>Additionally, you must put a +<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code +<uses-feature>}</a> tag in your manifest file to indicate the version of +<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a> +that your application requires.</p> + +<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however, +use the VM to perform some of the operations that you would get from those APIS. These operations +include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see +<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html"> +Introducing GLSurfaceView</a>.</p> + +<p>The san-angeles sample application provides an example of how to perform these operations, +rendering each frame in native code. This sample is a small Android port of the excellent +<a href="http://jet.ro/visuals/san-angeles-observation/">San Angeles Observation</a> demo +program.</p> + +<h3 id="a5">Android API level 5</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 2.0 system +images and above.</p> + +<h4>OpenGL ES 2.0 library:</h4> +<p>The standard OpenGL ES 2.0 headers {@code <GLES2/gl2.h>} and {@code <GLES2/gl2ext.h>} +contain the declarations needed for performing OpenGL ES 2.0 rendering calls from native code. +These rendering calls provide the ability to use the GLSL language to define and use vertex and +fragment shaders.</p> + +<p>To use OpenGL ES 2.0, link your native module to {@code /system/lib/libGLESv2.so} by +including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -lGLESv2 +</pre> + +<p>Not all devices support OpenGL ES 2.0. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of +<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> +{@code glGetString()}</a> in the OpenGL specification.</p> + +<p>Additionally, you must put a +<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code +<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> + +<p>The hello-gl2 sample application provies a basic example of how to use OpenGL ES 2.0 with the +NDK.</p> + +<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however, +use the VM to perform some of the operations that you would get from those APIs. These operations +include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see +<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html"> +Introducing GLSurfaceView</a>.</p> + +<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 2.0 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 2.0.</p> + +<h3 id="a8">Android API level 8</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 2.2 system +images and above.</p> + +<h4>jnigraphics</h4> +<p>The {@code jnigraphics} library exposes a C-based interface that allows native code to reliably access +the pixel buffers of Java bitmap objects. The workflow for using {@code jnigraphics} is as follows: +</p> + +<ol type="1"> +<li>Use {@code AndroidBitmap_getInfo()} to retrieve information from JNI, such as width and height, +about a given bitmap handle.</li> + +<li>Use {@code AndroidBitmap_lockPixels()} to lock the pixel buffer and retrieve a pointer to it. +Doing so ensures that the pixels do not move until the app calls +{@code AndroidBitmap_unlockPixels()}.</li> + +<li>In native code, modify the pixel buffer as appropriate for its pixel format, width, and other +characteristics.</li> + +<li>Call {@code AndroidBitmap_unlockPixels()} to unlock the buffer.</li> +</ol> + +<p>To use {@code jnigraphics}, include the {@code <bitmap.h>} header in your source code, and +link against {@code jnigraphics} by including the following line in your +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS += -ljnigraphics +</pre> + +<p>Additional details about this feature are in the comments of the {@code bitmap.h} file. + +<h3 id="a9">Android API level 9</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 2.3 system +images and above.</p> + +<h4 id="egl"> EGL</h4> +<p>EGL provides a native platform interface for allocating and managing OpenGLES surfaces. +For more information about its features, see <a href="http://www.khronos.org/egl"> +EGL Native Platform Interface</a>.</p> + +<p>EGL allows you to perform the following operations from native code:</p> + +<ul> +<li>List supported EGL configurations.</li> +<li>Allocate and release OpenGLES surfaces.</li> +<li>Swap or flip surfaces.</li> +</ul> + +<p>The following headers provide EGL functionality:</p> +<ul> + <li>{@code EGL/egl.h}: the main EGL API definitions.</li> + <li>{@code EGL/eglext.h}: EGL extension-related definitions.</li> +</ul> + +<p>To link against the system's EGL library, add the following line to your +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS += -lEGL +</pre> + +<h4 id="osl">OpenSL ES</h4> +<p>Android native audio handling is based on the Khronos Group OpenSL ES 1.0.1 API.</p> + +<p>The standard OpenSL ES headers {@code OpenSLES.h} and {@code OpenSLES_Platform.h} contain +the declarations necessary for performing audio input and output from the native side of Android. +The NDK distribution of the OpenSL ES also provides Android-specific extensions. For information +about these extensions, see the comments in {@code OpenSLES_Android.h} and +{@code OpenSLES_AndroidConfiguration.h}.</p> + + +<p>The system library {@code libOpenSLES.so} implements the public native audio functions. Link +against it by adding the following line to your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS += -lOpenSLES +</pre> + +<p>For more information about the OpenSL ES API, refer to +{@code $NDK/docs/Additional_library_docs/opensles/index.html}, where {@code $NDK} is your NDK +installation root directory.</p> + +<h4>Android native application APIs</h4> +<p>Starting from API level 9, you can write an entire Android app with native code, without using +any Java.</p> + +<p class="note"><strong>Note: </strong>Writing your app in native code is not, in itself, enough +for your app to run in the VM. Moreover, your app must still access most features of the Android +platform via JNI.</p> + +<p>This release provides the following native headers:</p> +<ul> +<li>{@code <native_activity.h>}</li> +<li>{@code <looper.h>}</li> +<li>{@code <input.h>}</li> +<li>{@code <keycodes.h>}</li> +<li>{@code <sensor.h>}</li> +<li>{@code <rect.h>}</li> +<li>{@code <window.h>}</li> +<li>{@code <native_window.h>}</li> +<li>{@code <native_window_jni.h>}</li> +<li>{@code <configuration.h>}</li> +<li>{@code <asset_manager.h>}</li> +<li>{@code <storage_manager.h>}</li> +<li>{@code <obb.h>}</li> +</ul> + +<p>For more information about these headers, see the +<a href="{@docRoot}ndk/reference/index.html">NDK API Reference documentation</a>, as well as +the comments in the headers, themselves. Also, for more information about the larger topic of +writing native apps, see <a href="{@docRoot}ndk/guides/concepts.html#naa"> +Native Activities and Applications</a>. + +<p>When you include one or more of these headers, you must also link against the +{@code libandroid.so} library. To link against {@code libandroid.so}, include the following line in +your <a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS += -landroid +</pre> + +<h3 id="a14">Android API level 14</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 4.0 system +images and above.</p> + +<h4>OpenMAX AL</h4> +<p>Android native multimedia handling is based on Khronos Group OpenMAX AL 1.0.1 API.</p> +<p>The standard OpenMAX AL headers {@code <OMXAL/OpenMAXAL.h>} and +{@code <OMXAL/OpenMAXAL_Platform.h>} contain the declarations necessary for performing +multimedia output from the native side of Android.</p> + +<p>The NDK distribution of OpenMAX AL also provides Android-specific extensions. For information +about these extensions, see the comments in {@code OpenMAXAL_Android.h}.</p> + +<p>The system library {@code libOpenMAXAL.so} implements the public native multimedia functions. +To link against this library, include the following line in your +<a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p> + +<pre class="fragment"> LOCAL_LDLIBS += -lOpenMAXAL +</pre><p>For more information about this topic, see {@code $NDK/docs/openmaxal/index.html}, +where {@code $NDK} is the root directory of your NDK installation.</p> + +<h4>OpenSL ES</h4> +<p>OpenSL ES support for this Android API level adds PCM support. For more information about +OpenSL ES support in the NDK, see <a href="#osl">OpenSL ES</a>.</p> + +<h3 id="a18">Android API level 18</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system +images and above.</p> + +<h4>OpenGL ES 3.0</h4> + +<p>The standard OpenGL ES 3.0 headers {@code gl3.h} and {@code gl3ext.h} contain the declarations +needed for performing OpenGL ES 3.0 rendering calls from native code. These rendering calls provide +the ability to use the GLSL language to define and use vertex and fragment shaders. + +<p>To use OpenGL ES 3.0, link your native module against {@code /system/lib/libGLESv3.so} by +including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -lGLESv3 +</pre> + +<p>Not all devices support OpenGL ES 3.0. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of +<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> +{@code glGetString()}</a> in the OpenGL specification.</p> + +<p>Additionally, you must put a +<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code +<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> + +<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.0 with the +NDK.</p> + +<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.0 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 3.0.</p> + + +<h3 id="a18">Android API level 21</h3> +<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system +images and above.</p> + +<h4>OpenGL ES 3.1</h4> + +<p>The standard OpenGL ES 3.1 headers {@code gl31.h} and {@code gl3ext.h} contain the declarations +needed for performing OpenGL ES 3.1 rendering calls from native code. These rendering calls provide +the ability to use the GLSL language to define and use vertex and fragment shaders. + +<p>To use OpenGL ES 3.1, link your native module against {@code /system/lib/libGLESv3.so} by +including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> +{@code Android.mk}</a> file:</p> + +<pre> +LOCAL_LDLIBS := -lGLESv3 +</pre> + +<p>Not all devices support OpenGL ES 3.1. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of +<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> +{@code glGetString()}</a> in the OpenGL specification.</p> + +<p>Additionally, you must put a +<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code +<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> + +<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.1 with the +NDK.</p> + +<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.1 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 3.1.</p> + diff --git a/docs/html/ndk/guides/standalone_toolchain.jd b/docs/html/ndk/guides/standalone_toolchain.jd new file mode 100644 index 0000000..3b6f7f1 --- /dev/null +++ b/docs/html/ndk/guides/standalone_toolchain.jd @@ -0,0 +1,605 @@ +page.title=Standalone Toolchain +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#syt">Selecting Your Toolchain</a></li> + <li><a href="#sys">Selecting Your Sysroot</a></li> + <li><a href="#itc">Invoking the Compiler</a></li> + <li><a href="#wwc">Working with Clang</a></li> + <li><a href="#abi">ABI Compatibility</a></li> + <li><a href="#war">Warnings and Limitations</a></li> + </ol> + </div> + </div> + +<p>You can use the toolchains provided with the Android NDK independently, or as plug-ins +with an existing IDE, such as Eclipse. This flexibility +can be useful if you already have your own build system, and only need the ability to invoke the +cross-compiler in order to add support to Android for it.</p> + +<p>A typical use case is invoking the configure script of an open-source library that expects a +cross-compiler in the {@code CC} environment variable.</p> + +<p class="note"><strong>Note:</strong> This page assumes significant understanding of +compiling, linking, and low-level architecture. In addition, the techniques it describes are +unnecessary for most use cases. In most cases, we recommend that you forego using a standalone +toolchain, and instead stick to the NDK build system.</p> + +<h2 id="syt">Selecting Your Toolchain</h2> +<p>Before anything else, you need to decide which processing architecture your standalone toolchain +is going to target. Each architecture corresponds to a different toolchain name, as Table 1 +shows.</p> + +<p class="table-caption" id="table1"> + <strong>Table 1.</strong> {@code APP_ABI} settings for different instruction sets.</p> +<table> + <tr> + <th scope="col">Architecture</th> + <th scope="col">Toolchain name</th> + </tr> + <tr> + <td>ARM-based</td> + <td>{@code arm-linux-androideabi-<gcc-version>}</td> + </tr> + <tr> + <td>x86-based</td> + <td>{@code x86-<gcc-version>}</td> + </tr> + <tr> + <td>MIPS-based</td> + <td>{@code mipsel-linux-android-<gcc-version>}</td> + </tr> + <tr> + <td>ARM64-based</td> + <td>{@code aarch64-linux-android-<gcc-version>}</td> + </tr> + <tr> + <td>X86-64-based</td> + <td>{@code x86_64-<gcc-version>}</td> + </tr> + <tr> + <td>MIPS64-based</td> + <td>{@code mips64el-linux-android--<gcc-version>}</td> + </tr> +</table> + + + +<h2 id="sys">Selecting Your Sysroot</h2> +<p>The next thing you need to do is define your <i>sysroot</i> (A sysroot is a directory containing +the system headers and libraries for your target). To define the sysroot, you must must know the +Android API level you want to target for native support; available native APIs vary by Android API +level.</p> + +<p>Native APIs for the respective <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> +Android API levels</a> reside under {@code $NDK/platforms/}; each API-level +directory, in turn, contains subdirectories for the various CPUs and architectures. The +following example shows how to define a <em>sysroot</em> for a build targeting Android 5.0 +(API level 21), for ARM architecture:</p> + +<pre class="no-pretty-print"> +SYSROOT=$NDK/platforms/android-21/arch-arm +</pre> + +For more detail about the Android API levels and the respective native APIs they support, see +<a href={@docRoot}ndk/guides/stable_apis.html>Android NDK Native APIs</a>. + +<h2 id="itc">Invoking the Compiler</h2> + +<p>There are two ways to invoke the compiler. One method is simple, and leaves most of the lifting +to the build system. The other is more advanced, but provides more flexibility.</p> + +<h3 id="sm">Simple method</h3> +<p>The simplest way to build is by invoking the appropriate compiler directly from the command +line, using the {@code --sysroot} option to indicate the location of the system files for the +platform you're targeting. For example:</p> + +<pre class="no-pretty-print"> +export CC="$NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/ \ +linux-x86/bin/arm-linux-androideabi-gcc-4.8 --sysroot=$SYSROOT" +$CC -o foo.o -c foo.c +</pre> + +<p>While this method is simple, it lacks in flexibility: It does not allow you to use any C++ STL +(STLport, libc++, or the GNU libstdc++) with it. It also does not support exceptions or RTTI.</p> + +<p>For Clang, you need to perform an additional two steps:</p> +<ul> +<ol type="1"> +<li>Add the appropriate {@code -target} for the target architecture, as Table 2 shows.</li> + +<p class="table-caption" id="table2"> + <strong>Table 2.</strong> Architectures and corresponding values for {@code -target}.</p> + <table> + <tr> + <th scope="col">Architecture</th> + <th scope="col">Value</th> + </tr> + <tr> + <td>armeabi</td> + <td>{@code -target armv5te-none-linux-androideabi}</td> + </tr> + <tr> + <td>armeabi-v7a</td> + <td>{@code -target armv7-none-linux-androideabi}</td> + </tr> + <tr> + <td>arm64-v8a</td> + <td>{@code -target aarch64-none-linux-android}</td> + </tr> + <tr> + <td>x86</td> + <td>{@code -target i686-none-linux-android}</td> + </tr> + <tr> + <td>x86_64</td> + <td>{@code -target x86_64-none-linux-android}</td> + </tr> + <tr> + <td>mips</td> + <td>{@code -target mipsel-none-linux-android}</td> + </tr> +</table> + +<li>Add assembler and linker support by adding the {@code -gcc-toolchain} option, as in the +following example:</li> +<pre class="no-pretty-print"> +-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64 +</pre> +</ol> + +Ultimately, a command to compile using Clang might look like this: + +<pre class="no-pretty-print"> +export CC="$NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/ \ +linux-x86/bin/arm-linux-androideabi-gcc-4.8 --sysroot=$SYSROOT" -target \ +armv7-none-linux-androideabi \ +-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64" +$CC -o foo.o -c foo.c +</pre> +</ul> + +<h3>Advanced method</h3> +<p>The NDK provides the {@code make-standalone-toolchain.sh} shell script to allow you to perform a +customized toolchain installation from the command line. This approach affords you more flexibility +than the procedure described in <a href="#sm">Simple method</a>.</p> + +<p>The script is located in the {@code $NDK/build/tools/} directory, where {@code $NDK} is the +installation root for the NDK. An example of the use of this script appears below:</p> + +<pre class="no-pretty-print"> +$NDK/build/tools/make-standalone-toolchain.sh \ +--arch=arm --platform=android-21 --install-dir=/tmp/my-android-toolchain +</pre> + +<p>This command creates a directory named {@code /tmp/my-android-toolchain/}, containing a copy of +the {@code android-21/arch-arm} sysroot, and of the toolchain binaries for a 32-bit ARM +architecture.</p> + +<p>Note that the toolchain binaries do not depend on or contain host-specific paths, in other words, +you can install them in any location, or even move them if you need to.</p> + +<p>By default, the build system uses the 32-bit, ARM-based GCC 4.8 toolchain. You can specify a +different value, however, by specifying {@code --arch=<toolchain>} as an option. +Table 3 shows the values to use for other toolchains: + +<p class="table-caption" id="table3"> + <strong>Table 3.</strong> Toolchains and corresponding values, using {@code --arch}.</p> + <table> + <tr> + <th scope="col">Toolchain</th> + <th scope="col">Value</th> + </tr> + <tr> + <td>mips64 compiler</td> + <td>{@code --arch=mips64}</td> + </tr> + <tr> + <td>mips GCC 4.8 compiler</td> + <td>{@code --arch=mips}</td> + </tr> + <tr> + <td>x86 GCC 4.8 compiler</td> + <td>{@code --arch=x86}</td> + </tr> + <tr> + <td>x86_64 GCC 4.8 compiler</td> + <td>{@code --arch=x86_64}</td> + </tr> + <tr> + <td>mips GCC 4.8 compiler</td> + <td>{@code --arch=mips}</td> + </tr> +</table> + +<p>Alternatively, you can use the {@code --toolchain=<toolchain>} option. Table 4 shows the +values you can specify for {@code <toolchain>}:</p> + +<p class="table-caption" id="table4"> + <strong>Table 4.</strong> Toolchains and corresponding values, using {@code --toolchain}.</p> + <table> + <tr> + <th scope="col">Toolchain</th> + <th scope="col">Value</th> + </tr> + + <tr> + <td>arm</td> + <td> + <li>{@code --toolchain=arm-linux-androideabi-4.8}</li> + <li>{@code --toolchain=arm-linux-androideabi-4.9}</li> + <li>{@code --toolchain=arm-linux-android-clang3.5}</li> + <li>{@code --toolchain=arm-linux-android-clang3.6}</li> + </td> + </tr> + <tr> + <td>x86</td> + <td> + <li>{@code --toolchain=x86-linux-android-4.8}</li> + <li>{@code --toolchain=x86-linux-android-4.9}</li> + <li>{@code --toolchain=x86-linux-android-clang3.5}</li> + <li>{@code --toolchain=x86-linux-android-clang3.6}</li> + </td> + </tr> + <tr> + <td>mips</td> + <td> + <li>{@code --toolchain=mips-linux-android-4.8}</li> + <li>{@code --toolchain=mips-linux-android-4.9}</li> + <li>{@code --toolchain=mips-linux-android-clang3.5}</li> + <li>{@code --toolchain=mips-linux-android-clang3.6}</li> + </td> + </tr> + + <tr> + <td>arm64</td> + <td> + <li>{@code --toolchain=aarch64-linux-android-4.9}</li> + <li>{@code --toolchain=aarch64-linux-android-clang3.5}</li> + <li>{@code --toolchain=aarch64-linux-android-clang3.6}</li> + </td> + </tr> + <tr> + <td>x86_64</td> + <td> + <li>{@code --toolchain=x86_64-linux-android-4.9}</li> + <li>{@code --toolchain=x86_64-linux-android-clang3.5}</li> + <li>{@code --toolchain=x86_64-linux-android-clang3.6}</li> + </td> + </tr> + <tr> + <td>mips64</td> + <td> + <li>{@code --toolchain=mips64el-linux-android-4.9}</li> + <li>{@code --toolchain=mips64el-linux-android-clang3.5}</li> + <li>{@code --toolchain=mips64el-linux-android-clang3.6}</li> + </td> + </tr> +</table> + +<p class="note"><strong>Note: </strong> Table 4 is not an exhaustive list. Other combinations may +also be valid, but are unverified.</p> + +<p>You can also copy Clang/LLVM 3.6, using one of two methods: You can append {@code -clang3.6} to +the {@code --toolchain} option, so that the {@code --toolchain} option looks like the following +example: + +<pre class="no-pretty-print"> +--toolchain=arm-linux-androideabi-clang3.6 +</pre> + +<p>You can also add {@code -llvm-version=3.6} as a separate option on the command +line.</p> + +<p class="note"><strong>Note: </strong>Instead of specifying a specific version, you can also +use {@code <version>}, which defaults +to the highest available version of Clang.</p> + +<p>By default, the build system builds for a 32-bit host toolchain. You can specify a 64-bit +host toolchain instead. Table 5 shows the value to use with {@code -system} for different +platforms.</p> + +<p class="table-caption" id="table5"> + <strong>Table 5.</strong> Host toolchains and corresponding values, using {@code -system}.</p> + <table> + <tr> + <th scope="col">Host toolchain</th> + <th scope="col">Value</th> + </tr> + <tr> + <td>64-bit Linux</td> + <td>{@code -system=linux-x86_64}</td> + </tr> + <tr> + <td>64-bit MacOSX</td> + <td>{@code -system=darwin-x86_64}</td> + </tr> + <tr> + <td>64-bit Windows</td> + <td>{@code -system=windows-x86_64}</td> + </tr> +</table> + +For more information on specifying a 64- or 32-bit instruction host toolchain, see +<a href="{@docRoot}ndk/guides/ndk-build.html#6432">64-Bit and 32-Bit Toolchains</a>. + +<p>You may specify {@code --stl=stlport} to copy {@code libstlport} instead of the default +{@code libgnustl}. If you do so, and you wish to link against the shared library, you must +explicitly use {@code -lstlport_shared}. This requirement is similar to having to use +{@code -lgnustl_shared} for GNU {@code libstdc++}.</p> + +<p>Similarly, you can specify {@code --stl=libc++} to copy the LLVM libc++ headers and libraries. +To link against the shared library, you must explicitly use -lc++_shared.</p> + +<p>You can make these settings directly, as in the following example:</p> + +<pre class="no-pretty-print"> +export PATH=/tmp/my-android-toolchain/bin:$PATH +export CC=arm-linux-androideabi-gcc # or export CC=clang +export CXX=arm-linux-androideabi-g++ # or export CXX=clang++ +</pre> + +<p>Note that if you omit the {@code -install-dir} option, the {@code make-standalone-toolchain.sh} +shell script creates a tarball in {@code tmp/ndk/<toolchain-name>.tar.bz2}. This tarball makes +it easy to archive, as well as to redistribute the binaries.</p> + +<p>This standalone toolchain provides an additional benefit, as well, in that it contains a working +copy of a C++ STL library, with working exceptions and RTTI support.</p> + +<p>For more options and details, use {@code --help}.</p> + +<h2 id="wwc">Working with Clang</h2> +<p>You can install Clang binaries in the standalone installation by using the +{@code --llvm-version=<version>} option. {@code <version>} is a LLVM/Clang version +number, such as {@code 3.5} or {@code 3.6}. For example: + +<pre class="no-pretty-print"> +build/tools/make-standalone-toolchain.sh \ +--install-dir=/tmp/mydir \ +--toolchain=arm-linux-androideabi-4.8 \ +--llvm-version=3.6 +</pre> + +<p>Note that Clang binaries are copied along with the GCC ones, because they rely on the same +assembler, linker, headers, libraries, and C++ STL implementation.</p> + +<p>This operation also installs two scripts, named {@code clang} and {@code clang++}, under +{@code <install-dir>/bin/@}. These scripts invoke the real {@code clang} binary with default +target architecture flags. In other words, they should work without any modification, and you should +be able to use them in your own builds by just setting the {@code CC} and {@code CXX} environment +variables to point to them.</p> + +<h4>Invoking Clang</h4> +<p>In an ARM standalone installation built with {@code llvm-version=3.6}, invoking +<a href="http://clang.llvm.org/">Clang</a> on a Unix system takes the form of a single line. For +instance:</p> + +<pre class="no-pretty-print"> +`dirname $0`/clang36 -target armv5te-none-linux-androideabi "$@" +</pre> + +<p><code>clang++</code> invokes <code>clang++31</code> in the same way.</p> + +<h4>Clang targets with ARM</h4> + +<p>When building for ARM, Clang changes the target based on the presence of the +{@code -march=armv7-a} and/or {@code -mthumb} options:</p> + +<p class="table-caption" id="table5"> + <strong>Table 5.</strong> Specifiable {@code -march} values and their resulting targets.</p> + <table> + <tr> + <th scope="col">{@code -march} value</th> + <th scope="col">Resulting target</th> + </tr> + <tr> + <td>{@code -march=armv7-a}</td> + <td>{@code armv7-none-linux-androideabi}</td> + </tr> + <tr> + <td>{@code -mthumb}</td> + <td>{@code thumb-none-linux-androideabi}</td> + </tr> + <tr> + <td>Both {@code -march=armv7-a} and {@code -mthumb}</td> + <td>{@code thumbv7-none-linux-androideabi}</td> + </tr> +</table> + +<p>You may also override with your own {@code -target} if you wish.</p> + +<p>The {@code -gcc-toolchain} option is unnecessary because, in a standalone package, +Clang locates {@code as} and {@code ld} in a predefined relative location. <p> + +<p>{@code clang} and {@code clang++} should be easy drop-in replacements for {@code gcc} and +{@code g++} in a makefile. When in doubt, add the following options to verify that they are +working properly:</p> + +<ul> +<li>{@code -v} to dump commands associated with compiler driver issues</li> +<li>{@code -###} to dump command line options, including implicitly predefined ones.</li> +<li>{@code -x c < /dev/null -dM -E} to dump predefined preprocessor definitions</li> +<li>{@code -save-temps} to compare {@code *.i} or {@code *.ii} preprocessed files.</li> +</ul> + +<p>For more information about Clang, see +<a href="http://clang.llvm.org/">http://clang.llvm.org/</a>, especially the GCC compatibility +section.</p> + + +<h2 id="abi">ABI Compatibility</h2> +<p>The machine code that the ARM toolchain generates should be compatible with the official Android +{@code armeabi} <a href="{@docRoot}ndk/guides/abis.html">ABI</a> by default.</p> + +<p>We recommend use of the {@code -mthumb} compiler flag to force the generation of 16-bit Thumb-1 +instructions (the default being 32-bit ARM instructions).</p> + +<p>If you want to target the armeabi-v7a ABI, you must set the following flags: </p> + +<pre class="no-pretty-print"> +CFLAGS= -march=armv7-a -mfloat-abi=softfp -mfpu=vfpv3-d16 +</pre> + +<p>The first flag enables Thumb-2 instructions. The second flag enables hardware-FPU instructions +while ensuring that the system passes floating-point parameters in core registers, which is critical +for ABI compatibility.</p> + +<p class="note"><strong>Note: </strong>In versions of the NDK prior to r9b, do not use these flags +separately. You must set all or none of them. Otherwise, unpredictable behavior and crashes may +result.</p> + +<p>To use NEON instructions, you must change the {@code -mfpu} compiler flag:</p> + +<pre class="no-pretty-print"> +CFLAGS= -march=armv7-a -mfloat-abi=softfp -mfpu=neon +</pre> + +<p>Note that this setting forces the use of {@code VFPv3-D32}, per the ARM specification.</p> + +<p>Also, make sure to provide the following two flags to the linker:</p> + +<pre class="no-pretty-print"> +LDFLAGS= -march=armv7-a -Wl,--fix-cortex-a8 +</pre> + +<p>The first flag instructs the linker to pick {@code libgcc.a}, {@code libgcov.a}, and +{@code crt*.o}, which are tailored for armv7-a. The 2nd flag is required as a workaround for a CPU +bug in some Cortex-A8 implementations.</p> + +<p>Since NDK version r9b, all Android native APIs taking or returning double or float values have +{@code attribute((pcs("aapcs")))} for ARM. This makes it possible to compile user code in +{@code -mhard-float} (which implies {@code -mfloat-abi=hard}), and still link with the Android +native APIs that comply with the softfp ABI. For more information on this, see the comments in +{@code $NDK/tests/device/hard-float/jni/Android.mk}.</p> + +<p>If you want to use NEON intrinsics on x86, the build system can translate them to the native x86 +SSE intrinsics using a special C/C++ language header with the same name, {@code arm_neon.h}, as the +standard ARM NEON intrinsics header.</p> + +<p>By default, the x86 ABI supports SIMD up to SSSE3, and the header covers ~93% of (1869 of 2009) +NEON functions.</p> + +<p>You don't have to use any specific compiler flag when targeting the MIPS ABI.</p> + +<p>To learn more about ABI support, see <a href="{@docRoot}ndk/guides/x86.html">x86 Support</a>.</p> + +<h2 id="war">Warnings and Limitations</h2> +<h3>Windows support</h3> +<p>The Windows binaries do not depend on Cygwin. This lack of dependency makes them faster. The +cost, however, is that they do not understand Cygwin path specifications like +{@code cygdrive/c/foo/bar}, as opposed to {@code C:/foo/bar}.</p> + +<p>The NDK build system ensures that all paths passed to the compiler from Cygwin are automatically +translated, and manages other complexities, as well. If you have a custom build system, +you may need to resolve these complexities yourself.</p> + +<p>For information on contributing to support for Cygwin/MSys, visit the android-ndk +<a href="https://groups.google.com/forum/#!forum/android-ndk">forum</a>.</p> + +<h3>wchar_t support</h3> + +<p>The Android platform did not really support {@code wchar_t} until Android 2.3 (API level 9). This +fact has several ramifications:</p> +<ul> +<li>If you target platform Android 2.3 or higher, the size of {@code wchar_t} is 4 bytes, and most +{@code wide-char} functions are available in the C library (with the exception of multi-byte +encoding/decoding functions and {@code wsprintf}/{@code wsscanf}).</li> + +<li>If you target any lower API level, the size of {@code wchar_t} is 1 byte, and none of the +wide-char functions works.</li> +</ul> + +<p>We recommend that you get rid of any dependencies on the {@code wchar_t} type, and switch to +better representations. The support provided in Android is only there to help you migrate existing +code.</p> + +<h3>Exceptions, RTTI, and STL</h3> +<p>The toolchain binaries support C++ exceptions and RTTI by default. To disable C++ exceptions +and RTTI when building sources (to generate lighter-weight machine code, for example), use +{@code -fno-exceptions} and {@code -fno-rtti}.</p> + +<p>To use these features in conjunction with GNU libstdc++, you must explicitly link with libsupc++. +To do so, use {@code -lsupc++} when linking binaries. For example:</p> + +<pre class="no-pretty-print"> +arm-linux-androideabi-g++ .... -lsupc++ +</pre> + +<p>You do not need to do this when using the STLport or libc++ library.</p> + +<h3>C++ STL support</h3> +<p>The standalone toolchain includes a copy of a C++ Standard Template Library implementation. This +implementation is either for GNU libstdc++, STLport, or libc++, depending on what you specify for the +{@code --stl=<name>} option described previously. To use this implementation of STL, you need +to link your project with the proper library:</p> + +<ul> +<li> +Use {@code -lstdc++} to link against the static library version of any implementation. Doing so +ensures that all required C++ STL code is included into your final binary. This method is ideal if +you are only generating a single shared library or executable.</p> + +<p>This is the method that we recommend.</p> +</li> + +<li>Alternatively, use {@code -lgnustl_shared} to link against the shared library version of GNU +{@code libstdc++}. If you use this option, you must also make sure to copy +{@code libgnustl_shared.so} to your device in order for your code to load properly. Table 6 shows +where this file is for each toolchain type. +</li> + +<p class="note"><strong>Note: </strong>GNU libstdc++ is licensed under the GPLv3 license, with a +linking exception. If you cannot comply with its requirements, you cannot redistribute the +shared library in your project.</p> + + +<li>Use {@code -lstlport_shared} to link against the shared library version of STLport. When you do +so, you need to make sure that you also copy {@code libstlport_shared.so} to your device in order +for your code to load properly. Table 6 shows where this file is for each toolchain:</li> + +<p class="table-caption" id="table6"> + <strong>Table 6.</strong> Specifiable {@code -march} values and their resulting targets.</p> + <table> + <tr> + <th scope="col">Toolchain</th> + <th scope="col">Location</th> + </tr> + <tr> + <td>arm</td> + <td>{@code $TOOLCHAIN/arm-linux-androideabi/lib/}</td> + </tr> + <tr> + <td>arm64</td> + <td>{@code $TOOLCHAIN/aarch64-linux-android/lib/}</td> + </tr> + <tr> + <td>x86</td> + <td>{@code $TOOLCHAIN/i686-linux-android/lib/}</td> + </tr> + <tr> + <td>x86_64</td> + <td>{@code $TOOLCHAIN/x86_64-linux-android/lib/}</td> + </tr> + <tr> + <td>mips</td> + <td>{@code $TOOLCHAIN/mipsel-linux-android/lib/}</td> + </tr> + <tr> + <td>mips64</td> + <td>{@code $TOOLCHAIN/mips64el-linux-android/lib/}</td> + </tr> +</table> + +<p class="note"><strong>Note: </strong>If your project contains multiple shared libraries or +executables, you must link against a shared-library STL implementation. Otherwise, the build +system does not define certain global uniquely, which can result in unpredictable runtime behavior. +This behavior may include crashes and failure to properly catch exceptions.</p> + +<p>The reason the shared version of the libraries is not simply called {@code libstdc++.so} is that +this name would conflict at runtime with the system's own minimal C++ runtime. For this reason, +the build system enforces a new name for the GNU ELF library. The static library does not have +this problem.</p> diff --git a/docs/html/ndk/guides/x86-64.jd b/docs/html/ndk/guides/x86-64.jd new file mode 100644 index 0000000..c2f0d28 --- /dev/null +++ b/docs/html/ndk/guides/x86-64.jd @@ -0,0 +1,52 @@ +page.title=Support for 64-bit x86 +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#over">Overview</a></li> + <li><a href="#st">Standalone Toolchain</a></li> + <li><a href="#comp">Compatibilty</a></li> + </ol> + </li> + </ol> + </div> + </div> + +<p>The Android NDK supports the {@code x86_64} ABI. This ABI allows native code to run on +Android-based devices using CPUs that support the 64-bit x86 instruction set.</p> + +<h2 id="over">Overview</h2> +<p>To generate 64-bit machine code for x86, add {@code x86_64} to the {@code APP_ABI} definition in +your {@code Application.mk} file. For example: + +<pre> +APP_ABI := x86_64 +</pre> + +For more information on how to specify values for {@code APP_ABI}, see +<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p> + +<p>The build system places libraries generated for the {@code x86_64} ABI into +{@code $PROJECT/libs/x86_64/} on your host machine, where {@code $PROJECT} is the root directory +of your project. It also embeds them in your APK, under {@code /lib/x86_64/}.</p> + +<p>The Android package manager extracts these libraries when installing your APK on a compatible +64-bit, x86-powered device, placing them under your app's private data directory.</p> + +<p>In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.</p> + +<h2 id="st">Standalone Toolchain</h2> + +<p>You can use the 64-bit x86 toolchain in standalone mode with the NDK. For more +information about doing so, see <a href="{@docRoot}ndk/guides/standalone_toolchain.html"> +Standalone Toolchain</a>, under the "Advanced method" section. + +<h2 id="comp">Compatibility</h2> +<p>The NDK provides native versions of Android APIs for 64-bit x86 machine code starting from +Android 5.0 (Android API level 21). If your project files target an older API level, but include +{@code x86_64} as a targeted platform, the NDK build script automatically selects the right set of +native platform headers and libraries for you.</p> diff --git a/docs/html/ndk/guides/x86.jd b/docs/html/ndk/guides/x86.jd new file mode 100644 index 0000000..3a01b05 --- /dev/null +++ b/docs/html/ndk/guides/x86.jd @@ -0,0 +1,215 @@ +page.title=x86 Support +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#over">Overview</a></li> + <li><a href="#an">ARM NEON Intrinsics Support</a></li> + <li><a href="#st">Standalone Toolchain</a></li> + <li><a href="#comp">Compatibility</a></li> + </ol> + </li> + </ol> + </div> + </div> + +<p>The NDK includes support for the {@code x86} ABI, which allows native code to run on +Android-based devices running on CPUs supporting the IA-32 instruction set.</p> + +<h2 id="over">Overview</h2> +<p>To generate x86 machine code, add {@code x86} to the {@code APP_ABI} definition in your +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. For example:</p> + +<pre class="no-pretty-print"> +APP_ABI := armeabi armeabi-v7a x86 +</pre + +<p>For more information about defining the {@code APP_ABI} variable, see +<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a>.</p> + +<p>The build system places generated libraries into {@code $PROJECT/libs/x86/}, where +{@code $PROJECT} represents your project's root directory, and embeds them in your APK under +{@code /lib/mips/}.</p> + +<p>The Android package extracts these libraries when installing your APK on a compatible x86-based +device, placing them under your app's private data directory.</p> + +<p>In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.</p> + +<h2 id="an">x86 Support for ARM NEON Intrinsics</h2> +<p>Support for ARM NEON intrinsics is provided in the form of C/C++ language headers with the same +name as the standard ARM NEON intrinsics header, {@code arm_neon.h}. These headers are available for +all NDK x86 toolchains. They translate NEON intrinsics to native x86 SSE ones.</p> + +<p>Characteristics of this solution include the following:</p> +<ul> +<li>Default use of SSE through SSSE3 for porting ARM NEON to Intel SSE, covering ~93% +(1869 of total 2009) of all NEON functions.</li> +<li>Redefinition of ARM NEON 128 bit vectors into the equivalent x86 SIMD data.</li> +<li>Redefinition of some functions from ARM NEON to Intel SSE if a 1:1 correspondence exists.</li> +<li>Implementation of some ARM NEON functions using Intel SIMD if it will yield a performant result. +</li> +<li>Implementation of some of the remaining NEON functions using the serial solution, and issuing +the corresponding "low performance" compiler warning.</li> +</ul> + + +<h3>Performance</h3> +<p>In most cases, you should be able to attain performance similar to what you would get from ARM +NEON code. Recommendations for best results include:</p> + +<ul> +<li>Use 16-byte data alignment for faster load and store.</li> +<li>Avoid using constants with NEON functions. Using constants results in a performance penalty due +to having to load constants. If you must use constants, try to initialize them outside of hotspot +loops. If possible, replace them with logical and compare operations.</li> +<li>Try to avoid functions marked as "serially implemented" because they need to store data from +registers to memory. Instead, process them serially and reload them. You may be able to change the +data type or algorithm used to vectorize the whole port instead of leaving it as a serial one.</li> +</ul> + +<p>For more information on this topic, see +<a href="http://software.intel.com/en-us/blogs/2012/12/12/from-arm-neon-to-intel-mmxsse-automatic-porting-solution-tips-and-tricks"> +From ARM NEON to Intel SSE– the automatic porting solution, tips and tricks</a>.</p> + +<h3>Known differences from ARM version</h3> +<p>In the great majority of cases, x86 implementations produce the same results as ARM +implementations for NEON. x86 implementations pass +<a href="https://gitorious.org/arm-neon-tests/arm-neon-tests">NEON tests</a> nearly 100% of the +time. Still, there are several corner cases in which an x86 implementation produces results +different from its ARM counterpart. Known incompatibilities are as follows:</p> + +<ul> +<li>{@code VRECPS/VRECPSQ}<br/> + If one of the operands is +/- infinity and the second is +/- 0.0: + <ul> + <li>On ARM CPUs, these instructions + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0489h/CIHDIACI.html"> + return a result element equal to 2.0</a>.</li> + + <li>x86 CPUs return {@code QNaN Indefinite}. For more information about the QNaN floating-point + indefinite, see "4.2.2 Floating-Point Data Types" and "4.8.3.7 QNaN Floating-Point Indefinite," + in the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s Manual</a>. + </li> + + </ul> +</li> +<li>{@code VRSQRTS/VRSQRTSQ}<br/> + If one of the operands is +/- infinity and the second is +/- 0.0: + <ul> + <li>On ARM CPUs, these instructions + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0489h/CIHDIACI.html"> + return a result element equal to 1.5</a>.</li> + + <li>x86 CPUs return {@code QNaN Indefinite}. For more information about the QNaN floating-point + indefinite, see "4.2.2 Floating-Point Data Types" and "4.8.3.7 QNaN Floating-Point Indefinite," + in the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s Manual</a>. + </li> + </ul> +</li> + +<li>{@code VMAX/VMAXQ}<br/> + If one of the operands is NaN, or both operands are +/- 0.0: + <ul> + <li>On ARM CPUs, floating-point maximum works as follows: + <ul> + <li>max(+0.0, -0.0) = +0.0.</li> + <li>If any input is a NaN, the corresponding result element is the default NaN.</li> + </ul> + To learn more about this condition and result, see the + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0489h/CIHDEEBE.html"> + ARM Compiler toolchain Assembler Reference</a>, ignoring the "Superseded" watermark. + </li> + + <li>On x86 CPUs, floating-point maximum works as follows: + <ul> + <li>If one of the source operands is NaN, then return the second source operand.</li> + <li>If both source operands are equal to 0, then return the second source operand.</li> + </ul> + For more information about these conditions and results, see Volume 1 Appendix E chapter + E.4.2.3 and Volume 2, p 3-488, of the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s + Manual</a>. + </li> + </ul> +</li> + +<li>{@code VMIN/VMINQ}<br/> + If one of the operands is NaN or both are +/- 0.0: + <ul> + <li>On ARM CPUs floating-point minimum works as follows: + <ul> + <li>min(+0.0, -0.0) = -0.0.</li> + <li>If any input is a NaN, the corresponding result element is the default NaN.</li> + </ul> + To learn more about this condition and result, see the + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0489h/CIHDEEBE.html"> + ARM Compiler toolchain Assembler Reference</a>, ignoring the "Superseded" watermark. + </li> + <li>On x86 CPUs floating-point minimum works as follows: + <ul> + <li>If one of the source operands is NaN, than return the second source operand.</li> + <li>If both source operands are equal to 0, than return the second source operand.</li> + </ul> + For more information about these conditions and results, see Volume 1 Appendix E chapter + E.4.2.3 and Volume 2, p 3-497, of the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s + Manual</a>. + </li> + </ul> +</li> + +<li>{@code VRECPE/VRECPEQ}<br/> + These instructions provide different levels of accuracy on ARM and x86 CPUs. For more information + about these differences, see + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.faqs/ka14282.html"> + How do I use VRECPE/VRECPEQ for reciprocal estimate?</a> on the ARM website, and Volume 2, p. + 4-281 of the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s Manual</a>. +</li> + +<li>{@code VRSQRTE/VRSQRTEQ}<br/> + <ul> + <li>These instructions provide different levels of accuracy on ARM and x86 CPUs. For more + information about these differences, see the + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0204h/CIHCHECJ.html"> + RealView Compilation Tools Assembler Guide</a>, and Volume 2, p. 4-325 of the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s Manual</a>. + </li> + + <li>If one of the operands is negative or -infinity then + <ul> + <li>On ARM CPUs, these instructions by default return a (positive) NaN. For more information + about this result, see the + <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0489i/CIHIICBB.html"> + ARM Compiler toolchain Assembler Reference</a>.</li> + <li>On x86 CPUs, these instructions return a (negative) QNaN floating-point Indefinite. For + more information about this result, see Volume 1, Appendix E, E.4.2.3, of the + <a href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Intel® 64 and IA-32 Architectures Software Developer’s + Manual</a>.</li> + </ul> + </li> + </ul> +</li> +</ul> + +<h3>Sample code</h3> +<p>In your project make sure to include the {@code arm_neon.h} header, and define include +{@code x86} in your definition of {@code APP_ABI}. The build system then ports your code to x86.</p> + +<p>For an example of how porting ARM NEON to x86 SSE works, see the hello-neon sample.</p> + +<h2 id="st">Standalone Toolchain</h2> +<p>You can incorporate the {@code x86} ABI into your own toolchain. For more information, see +<a href="{@docRoot}ndk/guides/standalone_toolchain.html">Standalone Toolchain</a>.</p> + +<h2 id="comp">Compatibility</h2> +<p>x86 support requires, at minimum, Android 2.3 (Android API level 9). If your project files +target an older API level, but include x86 as a targeted platform, the NDK build script +automatically selects the right set of native platform headers/libraries for you.</p>
\ No newline at end of file |
