Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am e23031c9: Docs: Final CL for NDK-docs-onto-DAC, pulling all files into a single CL.

Browse Source 
* commit 'e23031c974c9b051ba639f9ad68f891e2ae87da3':
  Docs: Final CL for NDK-docs-onto-DAC, pulling all files into a single CL.
This commit is contained in:
David Friedman
2015-05-22 19:50:14 +00:00
committed by Android Git Automerger
parent 16580c9bb4 e23031c974
commit 7044ee162b
33 changed files with 5895 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/html-ndk/ndk/downloads/index.jd
View File

@@ -1,4 +1,25 @@
page.title=NDK Downloads
@jd:body
ndk=true
page.template=sdk
<p>downloads
ndk.mac64_download=android-ndk-r10e-darwin-x86_64.bin
ndk.mac64_bytes=388937326
ndk.mac64_checksum=2cb8893a5701603519d38a7e04c50e81
ndk.linux64_download=android-ndk-r10e-linux-x86_64.bin
ndk.linux64_bytes=401522849
ndk.linux64_checksum=19af543b068bdb7f27787c2bc69aba7f
ndk.linux32_download=android-ndk-r10e-linux-x86.bin
ndk.linux32_bytes=394281908
ndk.linux32_checksum=c3edd3273029da1cbd2f62c48249e978
ndk.win64_download=android-ndk-r10e-windows-x86_64.exe
ndk.win64_bytes=419616132
ndk.win64_checksum=8412bb4991a95e08fda50b5a44d95df7
ndk.win32_download=android-ndk-r10e-windows-x86.exe
ndk.win32_bytes=396563176
ndk.win32_checksum=1a82445baaf62aec3a46386ab1e5772c
page.title=NDK Downloads
@jd:body

493
docs/html-ndk/ndk/guides/abis.jd Normal file
View File

@@ -0,0 +1,493 @@
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 set(s) 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}</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="android_mk.html"><code>Android.mk</code></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">CPU Features</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</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&amp;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">MIPS 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/&lt;abi&gt;/lib&lt;name&gt;.so
</pre>
<p>Here, {@code &lt;abi&gt;} is one of the ABI names listed under <a href="#sa">Supported ABIs</a>,
and {@code &lt;name&gt;} 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/&lt;primary-abi&gt;/lib&lt;name&gt;.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/&lt;secondary-abi&gt;/lib&lt;name&gt;.so
</pre>
<p>When it finds the libraries that it's looking for, the package manager
copies them to <code>/lib/lib&lt;name&gt;.so</code>, under the application's
{@code data} directory ({@code data/data/&lt;package_name&gt;/lib/}).</p>
<p>If there is no shared-object file at all, the application builds and installs, but crashes at
runtime.</p>

891
docs/html-ndk/ndk/guides/android_mk.jd Normal file
View File

@@ -0,0 +1,891 @@
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="#npv">NDK-provided variables</a></li>
<li><a href="#npfm">NDK-provided function 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 {@code Application.mk}, 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, the
<a href="{@docRoot}ndk/guides/native-activity.html">walkthrough</a> of the native-activity sample
disucsses that sample's {@code Android.mk} file in some detail. Finally, the next section explains
the variables from this section in a bit more detail.
<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. The following example shows an example of using
{@code LOCAL_PREBUILTS}:
<!--
<pre class="no-pretty-print">
(TODO: Example of referencing prebuilt library from another, using LOCAL_PREBUILTS.)
</pre>
-->
<p>For more information about using prebuilts, see <a href="{@docRoot}ndk/guides/prebuilts.html">
NDK Prebuilt Library Support</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">NDK Prebuilt
Library Support</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
<a href="{docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> 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 Stable APIs</a>.
The following example shows the syntax for using this variable:</p>
<pre class="no-pretty-print">
TARGET_PLATFORM := android-22
</pre>
<h4>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>
<th scope="col">ARMv5TE</th>
<th scope="col">{@code armeabi}</th>
</tr>
<tr>
<th scope="col">ARMv7</th>
<th scope="col">{@code armeabi-v7a}</th>
</tr>
<tr>
<th scope="col">ARMv8 AArch64</th>
<th scope="col">{@code arm64-v8a}</th>
</tr>
<tr>
<th scope="col">i686</th>
<th scope="col">{@code x86}</th>
</tr>
<tr>
<th scope="col">x86-64</th>
<th scope="col">{@code x86_64}</th>
</tr>
<tr>
<th scope="col">mips32 (r1)</th>
<th scope="col">{@code mips}</th>
</tr>
<tr>
<th scope="col">mips64 (r6)</th>
<th scope="col">{@code mips64}</th>
</tr>
<tr>
<th scope="col">All</th>
<th scope="col">{@code all}</th>
</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/md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">
Android Native CPU 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 {@code Application.mk} 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
<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> 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 {@code Application.mk} 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&lt;path&gt;,
</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 Stable 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 targetting 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, please see <a href="{@docRoot}ndk/guides/cpu_support.html">Android
NDK &amp; ARM NEON Instruction Set Extension Support</a> and <a
href="{@docRoot}ndk/guides/cpu_features.html">Android
NDK CPU Features Detection 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 off 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>
<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 {@code Application.mk} 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--&gt; $OBJS_DIR/foo.S.original --2--&gt; $OBJS_DIR/foo.S --3--&gt; $OBJS_DIR/foo.o
bar.S --2--&gt; $OBJS_DIR/bar.S --3--&gt; $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 &lt;function&gt;)} 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 the {@code Android.mk}
of another module by name. A typical example is as follows: </p>
<pre class="no-pretty-print">
$(call import-module,&lt;name&gt;)
</pre>
<p>In this example, the build system looks for the module tagged &lt;name&gt; 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>
<p>For more information, see <a href="import_module.html">Android Module Paths (Sharing Code)</a>.
</p>

241
docs/html-ndk/ndk/guides/application_mk.jd Normal file
View File

@@ -0,0 +1,241 @@
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 syntax of 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/&lt;myapp&gt;/Application.mk
</pre>
<p>Here, {@code &lt;myapp&gt;} 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/&lt;myapp&gt;/}, 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 &lt;application&gt;}
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">Android Native CPU 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 Stable 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. Table 2 shows the {@code APP_STL} values to specify
support for different libraries.</p>
<p class="table-caption" id="table2">
<strong>Table 2.</strong> {@code APP_STL} settings to support different libraries.</p>
<table>
<tr>
<th scope="col">Library</th>
<th scope="col">Value</th>
</tr>
<tr>
<td>Static STLport</td>
<td>{@code APP_STL := stlport_static}</td>
</tr>
<tr>
<td>Shared STLport</td>
<td>{@code APP_STL := stlport_shared}</td>
</tr>
<tr>
<td>Default C++ runtime</td>
<td>{@code APP_STL := system}</td>
</tr>
</table>
<p>For more information on this subject, see <a href="{@docRoot}ndk/guides/cpp_support.html">C++
Support</a>.</p>
<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). Use the {@code -fPIE} flag to build them. 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>

31
docs/html-ndk/ndk/guides/arch.jd Normal file
View File

@@ -0,0 +1,31 @@
page.title=Architectures and CPUs
@jd:body
<div class="contents">
<div class="textblock"><p>This section includes detailed information about ABIs and detailed information on support for respective instruction sets. It includes these topics:</p>
<ul>
<li><a href="./md_3__key__topics__c_p_u__support__chapter_1-section_8__a_b_is.html">ABI Management</a><ul>
<li>Different ABIs support different CPUs and processing capabilities.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__c_p_u__support__c_p_u-_a_r_m-_n_e_o_n.html">Neon</a><ul>
<li>Details about targeting devices whose CPUs support Neon, or Advanced SIMD. Neon is an optional extension of the armv7 architecture.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__c_p_u__support__c_p_u-_m_i_p_s.html">Mips</a><ul>
<li>Details about targeting devices with CPUs supporting the MIPS32 instruction set.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__c_p_u__support__c_p_u-_x86.html">x86</a><ul>
<li>Details about targeting devices with CPUs supporting the IA-32 instruction set.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__c_p_u__support__c_p_u-_x86-64.html">x86-64</a><ul>
<li>Details about targeting devices whose CPUs support the x86-64 instruction set.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__c_p_u__support__c_p_u-_f_e_a_t_u_r_e_s.html">CPU Features</a><ul>
<li>A small library that detects the target device's CPU family and supported features. </li>
</ul>
</li>
</ul>

23
docs/html-ndk/ndk/guides/build.jd Normal file
View File

@@ -0,0 +1,23 @@
page.title=Building
@jd:body
<div class="contents">
<div class="textblock"><p>This section explains, in detail, how to use the NDK to build your project. It comprises the following topics:</p>
<ul>
<li><a href="./md_3__key__topics__building__chapter_1-section_8_ndk-build.html">ndk-build</a><ul>
<li>How to use the shell script that invokes the tools to build your shared libraries.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk</a><ul>
<li>Syntax for the file that describes your build sources to the build system.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Application.mk</a><ul>
<li>Syntax for the file that describes the native modules that your application requires.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__building__s_t_a_n_d_a_l_o_n_e-_t_o_o_l_c_h_a_i_n.html">Standalone Toolchain</a><ul>
<li>How to integrate the NDK into your existing build system. </li>
</ul>
</li>
</ul>

301
docs/html-ndk/ndk/guides/concepts.jd Normal file
View File

@@ -0,0 +1,301 @@
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 the
<a href="{@docRoot}ndk/guides/ndk-build.html">ndk-build</a> section of this guide.</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>. The
<a href="#naa">Native Activity</a> section provides more detail on how to do this, under
“Using the native-activity.h interface.”
</li>
</ul>
<p>The following two items only apply in cases in which you are using the toolchains provided with
the Android NDK as standalone compilers.</p>
<ul>
<li>{@code Android.mk}: You must create an {@code Android.mk} configuration file inside your
{@code jni} folder. The ndk-build script looks at this file, which defines the module and its name,
the source files to be compiled, build flags and libraries to link. For more information, see the
<a href="{@docRoot}ndk/guides/android.mk.html">Android.mk</a> section of this document.</li>
</ul>
<ul>
<li>{@code Application.mk}: You may optionally create an Application.mk file. This file enumerates
and describes the modules that your app requires. This information includes:<ul>
<li>ABIs used to compile for specific platforms.</li>
<li>Toolchains.</li>
<li>Standard libraries to include (static and dynamic STLport or default system).</li>
</ul>
<p>For more information, see the
<a href="{@docRoot}ndk/guides/application.mk.html">Application.mk</a> section.</p>
</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 Activity</a> section.
</li>
<li>Create an Android.mk file describing the native library, including name, flags, linked libraries
and source files to be compiled in the ‘JNI’ directory.</li>
<li>OPTIONAL: Create an {@code Application.mk} 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&ndash;such as for sensors, input events, and
assets&ndash;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">Stable 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 {@code native_activity.h} 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 android_native_app_glue.h file defines a static helper library built on top of the
{@code native_activity.h} 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 &lt;ndk_root&gt;/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 &lt;ndk_root&gt;/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 {@code native-activity.h} 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>
&lt;application android:label="@string/app_name" android:hasCode="false"&gt;
</pre>
<p>You must set the {@code android:name} attribute of the activity tag to
{@link android.app.NativeActivity}.</p>
<pre>
&lt;activity android:name="android.app.NativeActivity"
android:label="@string/app_name"&gt;
</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>
&lt;meta-data android:name="android.app.lib_name"
android:value="native-activity" /&gt;
&lt;intent-filter&gt;
&lt;action android:name="android.intent.action.MAIN" /&gt;
&lt;category android:name="android.intent.category.LAUNCHER" /&gt;
&lt;/intent-filter&gt;
&lt;/activity&gt;
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
<li>Create a file for your native activity, and implement the {@code ANativeActivity_onCreate()}
function, which the app calls when the native activity starts. This function, analogous
to {@code main} in C/C++, receives a pointer to an {@code ANativeActivity} structure,
which contains function pointers to the various callback implementations that you need to write.
Set the applicable callback function pointers in {@code ANativeActivity-&gt;;callbacks} to the
implementations of your callbacks.</li>
<!--TODO: API Ref links in the above para.-->
<li>Set the {@code ANativeActivity-&gt;;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-&gt;;callbacks}. For
more information on when the callbacks are called, see the
<a href="{@docRoot}training/basics/activity-lifecycle/index.html">SDK documentation for Activity Lifecycles</a>.
</li>
<li>Develop the rest of your application.</li>
<li>Create an {@code Android.mk file} in the {@code jni/} directory of your project to describe your
native module to the build system. For more information, see the
<a href="./md_3__key__topics__building__chapter_1-section_8__android_8mk.html">Android.mk section.</a>.
</li>
<li>Once you have an {@code Android.mk} file, compile your native code using the {@code ndk-build}
command.</li>
<pre class="no-pretty-print">
$ cd &lt;path&gt;/&lt;to&gt;/&lt;project&gt;
$ &lt;ndk&gt;/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>
<p>You can find further information on using {@code native-activity.h} here.</p>
<!-- (TODO: Link to API ref guide in the above para)-->
</li>
</ul>

328
docs/html-ndk/ndk/guides/cpp-support.jd Normal file
View File

@@ -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="table1">
<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">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 &lt;atomic&gt;}, 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.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.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&ndash;or a shared library and an executable&ndash;
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 need to 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>

109
docs/html-ndk/ndk/guides/cpu-arm-neon.jd Normal file
View File

@@ -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 &lt;cpu-features.h&gt;
...
...
if (android_getCpuFamily() == ANDROID_CPU_FAMILY_ARM &amp;&amp;
(android_getCpuFeatures() &amp; 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>

210
docs/html-ndk/ndk/guides/cpu-features.jd Normal file
View File

@@ -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 &lt;cpu-features.h&gt;} 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">
&lt;project-path&gt;/jni/Android.mk:
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := &lt;your-module-name&gt;
LOCAL_SRC_FILES := &lt;your-source-files&gt;
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">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>

17
docs/html-ndk/ndk/guides/debug.jd Normal file
View File

@@ -0,0 +1,17 @@
page.title=Debugging
@jd:body
<div class="title">Debugging </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This section introduces you to debugging with the NDK. It includes:</p>
<ul>
<li><a href="./md_3__key__topics__debugging__n_d_k-_g_d_b.html">ndk-gdb and ndk-gdb-py</a><ul>
<li>The helper shell script named <code>ndk-gdb</code>, which allows you to launch a native debugging session for your NDK-generated machine code.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__debugging__n_d_k-_s_t_a_c_k.html">ndk-stack</a><ul>
<li>A tool that helps you use ADB <code>logcat</code> in your debugging. </li>
</ul>
</li>
</ul>

61
docs/html-ndk/ndk/guides/guides_toc.cs
View File

@@ -8,8 +8,65 @@
<ul id="nav">
<li><a href="/ndk/guides/index.html"><span class="en">Getting Started</span></a></li>
<li><a href="/ndk/guides/pg_html/md_1__concepts__concepts.html">Concepts</a></li>
<li><strong>NDK</strong>
<ul>
<li><a href="/ndk/guides/index.html"><span class="en">Getting Started</span></a>
<ul>
<li><a href="setup.html">Setup</a></li>
<li><a href="concepts.html">Concepts</a></li>
</ul></li>
<li><a href="/ndk/guides/build.html"><span class="en">Building</span></a>
<ul>
<li><a href="">ndk-build</a></li>
<li><a href="">Android.mk</a></li>
<li><a href="">Application.mk</a></li>
<li><a href="">Standalone Toolchain</a></li>
</ul></li>
<li><a href="/ndk/guides/debug.html"><span class="en">Debugging</span></a>
<ul>
<li><a href="">ndk-gdb</a></li>
<li><a href="">ndk-stack</a></li>
</ul></li>
<li><a href="/ndk/guides/arch.html"><span class="en">Architectures and CPUs</span></a>
<ul>
<li><a href="">ABI Management</a></li>
<li><a href="">Neon</a></li>
<li><a href="">Mips</a></li>
<li><a href="">x86</a></li>
<li><a href="">x86-64</a></li>
<li><a href="">CPU Features</a></li>
</ul></li>
<li><a href="/ndk/guides/libs.html"><span class="en">Libraries</span></a>
<ul>
<li><a href="">Stable APIs</a></li>
<li><a href="">C++ Support</a></li>
<li><a href="">Prebuilt Libraries</a></li>
</ul></li>
<li><a href="/ndk/guides/sample.html"><span class="en">Sample Walkthrough</span></a>
<ul>
<li><a href="">hello-jni</a></li>
<li><a href="">native-activity</a></li>
<li><a href="">Teapot</a></li>
</ul></li>
<li><a href="/ndk/guides/atomics.html"><span class="en">Atomics</span></a></li>
<li><a href="/ndk/guides/importing.html"><span class="en">Importing Modules</span></a></li>
<li><a href="/ndk/guides/depends.html"><span class="en">ndk-depends</span></a></li>
<li><a href="/ndk/guides/system.html"><span class="en">System Image Issues</span></a></li>
<li><a href="/ndk/guides/licenses.html"><span class="en">Licenses</span></a></li>
</ul></li>
<li><strong>Radiance</strong>
<ul>
<li><a href="/ndk/guides/null.html"><span class="en">Stub 1</span></a>
<ul>
<li><a href="">Stublet</a></li>
<li><a href="">Stublet</a></li>
</ul></li>
<li><a href="/ndk/guides/null.html"><span class="en">Stub 2, etc.</span></a>
<ul>
<li><a href="">Another Stublet</a></li>
<li><a href="">Another Stublet</a></li>
</ul></li>
</ul></li>
</ul>

BIN
docs/html-ndk/ndk/guides/images/NDK_build_string.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
docs/html-ndk/ndk/guides/images/NDK_build_string@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
docs/html-ndk/ndk/guides/images/verification_screen.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
docs/html-ndk/ndk/guides/images/verification_screen@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 280 KiB

17
docs/html-ndk/ndk/guides/index.jd
View File

@@ -1,4 +1,17 @@
page.title=Concepts
page.title=Getting Started
@jd:body
<p>To use the NDK, you must download it and install it separately from the SDK. To do so, follow these directions.
<p>This section provides the information you need to get up and running
with the NDK.</p>
<ul>
<li><a href="setup.html">Setup</a></li>
<ul>
<li>Learn how to set up the NDK, and verify that it's integrated into
your toolchain.</li>
</ul>
<li><a href="concepts.html">Concepts</a></li>
<ul>
<li>Learn some basics about how the NDK works and its components, and about how to use it.
</li>
</ul>
</ul>

20
docs/html-ndk/ndk/guides/libs.jd Normal file
View File

@@ -0,0 +1,20 @@
page.title=Libraries
@jd:body
<div class="contents">
<div class="textblock"><p>This section discusses libraries included with the NDK, as well as how to use other people's libraries and modules in your own application. It discusses:</p>
<ul>
<li><a href="./md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Stable APIs</a><ul>
<li>This section discusses the stable APIs exposed by the NDK.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__libraries__p_r_e_b_u_i_l_t_s.html">Prebuilt Libraries</a><ul>
<li>How to include and use prebuilt libraries in your own application.</li>
</ul>
</li>
<li><a href="./md_3__key__topics__libraries__c_p_l_u_s_p_l_u_s-_s_u_p_p_o_r_t.html">C++ Support</a><br/>
<ul>
<li>Information about the NDK's C++ runtime support library and corresponding header files. </li>
</ul>
</li>
</ul>

4
docs/html-ndk/ndk/guides/md_1__concepts__concepts.html
View File

@@ -1,4 +0,0 @@
page.title=Concepts
@jd:body
<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:

43
docs/html-ndk/ndk/guides/mips.jd Normal file
View File

@@ -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
{@code /lib/mips/}.</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>

194
docs/html-ndk/ndk/guides/ndk-build.jd Normal file
View File

@@ -0,0 +1,194 @@
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>ndk-build is a tiny shell script introduced in Android NDK r4. Its purpose
is simply to invoke the right NDK build script.
<h2 id="int">Internals</h2>
ndk-build is equivalent to: </p>
<pre class="no-pretty-print">
$GNUMAKE -f &lt;ndk&gt;/build/core/build-local.mk
&lt;parameters&gt;
</pre>
<p><code>$GNUMAKE</code> points to GNU Make 3.81 or later, and
<code>&lt;ndk&gt;</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>ndk-build 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 &lt;project&gt;
$ &lt;ndk&gt;/ndk-build
</pre>
<p>In this example, <code>&lt;project&gt;</code> points to your
project’s root directory, and <code>&lt;ndk&gt;</code> is the directory where
you installed the NDK. As noted in <a
href="{@docRoot}ndk/guides/setup.html#install">Setup</a>, you can add {@code $NDK} to your
{@code PATH} to avoid having to type the whole filepath every time you use ndk-build.
Alternatively, you can create an alias.</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 &lt;option&gt;</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=&lt;file&gt;}</dt>
<dd>Build, using a specific <code>Application.mk</code> file pointed to by the
{@code NDK_APPLICATION_MK} variable.</dd>
<dt>{@code -C &lt;project&gt;}</dt>
<dd>Build the native code for the project path located at {@code &lt;project&gt;}. 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">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">&lt;application android:label="@string/app_name"
android:debuggable="true"&gt;
</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 &lt;ndk&gt;/toolchain/&lt;name&gt;/prebuilt/} and
{@code &lt;ndk&gt;/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/&lt;OS&gt;/bin/}
with the following environment variables: </p>
<pre class="no-pretty-print">
$ export NDK_HOST_AWK=&lt;path-to-awk&gt;
$ export NDK_HOST_ECHO=&lt;path-to-echo&gt;
$ export NDK_HOST_CMP=&lt;path-to-cmp&gt;
</pre>

241
docs/html-ndk/ndk/guides/ndk-gdb.jd Normal file
View File

@@ -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=&lt;name&gt;} method to build.</p></li>
<li>Enable app debugging in your {@code AndroidManifest.xml} file by including an
{@code &lt;application&gt;} 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
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="http://developer.android.com/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 &lt;location&gt;} 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=&lt;name&gt;} 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=&lt;name&gt;} 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=&lt;name&gt;}</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=&lt;path&gt;}</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=&lt;port&gt;}</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=&lt;file&gt;}</td>
<td><p>This option specifies the <a href="http://developer.android.com/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 &lt;serial&gt;}</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 &lt;serial&gt;}</dt>
<dd>Connect to a specific device or emulator. Here, {@code &lt;serial&gt;} 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=&lt;file&gt;}</li>
<li>{@code -x &lt;file&gt;}</li>
</td>
<td><p>This option tells {@code ndk-gdb} to run the GDB initialization commands found in
{@code &lt;file&gt;} 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=&lt;flag&gt;}</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>

84
docs/html-ndk/ndk/guides/ndk-stack.jd Normal file
View File

@@ -0,0 +1,84 @@
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 {@code adb logcat}, and replace any address inside a shared library with the corresponding
{@code &lt;source-file&gt;:&lt;line-number&gt;} values.</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 &lt;&lt;&lt;
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 &gt;&gt;&gt; /data/local/ndk-tests/crasher &lt;&lt;&lt;
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/&lt;abi&gt;}, where {@code &lt;abi&gt;} 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 &gt; /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>

145
docs/html-ndk/ndk/guides/prebuilts.jd Normal file
View File

@@ -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 that 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/&lt;abi&gt;}. 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 &lt;foo.h&gt;
</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/&lt;abi&gt;/}, 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>

11
docs/html-ndk/ndk/guides/sample.jd Normal file
View File

@@ -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>

122
docs/html-ndk/ndk/guides/sample_hellojni.jd Normal file
View File

@@ -0,0 +1,122 @@
page.title=Sample: HelloJNI
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>On this page</h2>
<ol>
<li><a href="#an">Android.mk</a></li>
<li><a href="#ap">Application.mk</a></li>
<li><a href="#ji">Java-side Implementation</a></li>
<li><a href="#ci">C-side Implementation</a></li>
</ol>
</li>
</ol>
</div>
</div>
<p>This sample provides a bare-bones look at a minimal
application built with the NDK.</p>
<h2 id="an">Android.mk</h2>
<p>The following two lines provide the name of the native source file, along
with the name of the shared library to build. The full name of the built
library is {@code libhello-jni.so}, but you should omit the
{@code lib} prefix and the {@code .so} extension.</p>
<pre class="no-pretty-print">
LOCAL_SRC_FILES := hello-jni.c
LOCAL_MODULE := hello-jni
</pre>
<p>For more information on what this file does, and how to use it, see
<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>.</p>
<h2 id="ap">Application.mk</h2>
<p>This line tells the build system the architecture against which to build. If
you don't specify anything, the build system defaults to {@code armeabi}.</p>
<pre class="no-pretty-print">
APP_ABI := all
</pre>
<p>For more information on what this file does, and how to use it, see
<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p>
<h2 id="ji">Java-side implementation</h2>
<p>This file calls a function to retrieve a string from the native side, then
displays it on the screen.</p>
<p>The source code contains three lines of particular interest to the NDK user.
They are presented here in the order in which they are used, rather than by
line order.</p>
<p>This function call loads the {@code .so} file upon application startup.</p>
<pre class="no-pretty-print">
System.loadLibrary("hello-jni");
</pre>
<p>The {@code native} keyword in this method declaration tells the
virtual machine that the function is in the shared library (i.e., implemented on the native side).
</p>
<pre class="no-pretty-print">
public native String stringFromJNI();
</pre>
<p>The Android framework calls the function loaded and declared in the
previous steps, displaying the string on the screen.</p>
<pre class="no-pretty-print">
tv.setText( stringFromJNI() );
</pre>
<h2 id="ci">C-side implementation</h2>
<p>This file contains a function that returns a string that the Java side
requested (see <a href="#ji">Java-side implementation</a>). The function declaration is as
follows:</p>
<pre>
jstring Java_com_example_hellojni_HelloJni_stringFromJNI(
JNIEnv* env,
jobject x )
</pre>
<p>This declaration corresponds to the native function declared in the
Java source code. The return type, {@code jstring}, is a data type defined
in the
<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html">Java Native
Interface Specification</a>. It is not actually a string, but a
pointer to a Java string.</p>
<p>After {@code jstring} comes the function name, which is based on the
Java function name and and the path to the file containing it. Construct it
according to the following rules:</p>
<ul>
<li>Prepend {@code Java_} to it.</li>
<li>Describe the filepath relative to the top-level source directory.</li>
<li>Use underscores in place of forward slashes.</li>
<li>Omit the {@code .java} file extension.</li>
<li>After the last underscore, append the function name.</li>
</ul>
<p>Based on these rules, in this example, the function name
{@code Java_com_example_hellojni_HelloJni_stringFromJNI} refers to a Java
function called {@code stringFromJNI()}, which resides in
{@code hellojni/src/com/example/hellojni/HelloJni.java}.</p>
<p>Finally, {@code JNIEnv*} is the pointer to the VM, and
{@code jobject} is a pointer to the implicit {@code this} object passed from
the Java side.</p>
<p>The following line calls the VM API {@code (*env)}, and passes it a return value:
that is, the string that the function on the Java side had requested.</p>
<pre class="no-pretty-print">
return (*env)-&gt;NewStringUTF(env, "Hello from JNI !
Compiled with ABI " ABI ".");
</pre>

194
docs/html-ndk/ndk/guides/sample_na.jd Normal file
View File

@@ -0,0 +1,194 @@
page.title=Sample: Native Activity
@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>
<p>This is a very simple example of a purely native
application, with no Java source code. In the absence of any Java source, the
Java compiler still creates an executable stub for the Dalvik Virtual Machine
("DVM") to run. The stub serves as a wrapper for the actual, native program,
which lives in the .so file.</p>
<p>The application itself simply renders a color onto the entire screen, and
then changes the color partly in response to detected movement.</p>
<h3>AndroidManifest.xml</h3>
<p>Make sure not to specify an Android API level lower than 9.</p>
<pre class="fragment">&lt;uses-sdk android:minSdkVersion="9" /&gt;
</pre><p>Because this application has only native code, specify
<code>android:hasCode</code> as <code>false</code>.</p>
<pre class="fragment">&lt;application android:label="@string/app_name"
android:hasCode="false"&gt;
</pre><p>Declare the <code>NativeActivity</code> class.</p>
<pre class="fragment"> &lt;activity android:name="android.app.NativeActivity"
</pre><p>For <code>android:value</code>, provide the name of the shared library
to be built, minus the initial <code>lib</code> and the <code>.so</code>
extension. This value must be the same as the one you described for
<code>LOCAL_MODULE</code> in <code>Android.mk</code>.</p>
<pre class="fragment"> &lt;meta-data android:name="android.app.lib_name"
android:value="native-activity" /&gt;
</pre><h3>Android.mk</h3>
<p>This file tells the build system the following information:</p>
<p>The name of the shared library to generate.</p>
<pre class="fragment">LOCAL_MODULE := native-activity
</pre><p>The name of the native source-code file.</p>
<pre class="fragment">LOCAL_SRC_FILES := main.c
</pre><p>A list of external libraries that will be used in building the binary,
each preceded by the <code>-l</code> (link-against) option.</p>
<ul>
<li>log is a logging library.</li>
<li>android encompasses the standard Android support APIs for NDK. The <a href="./md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html">Stable APIs</a>
section discusses these in more detail.</li>
<li>EGL, standardized by Khronos, corresponds to the platform-specific portion
of the graphics API.</li>
<li>OpenGL ES, the version of OpenGL for Android, depends on EGL.</li>
</ul>
<p>Note that, for each library:</p>
<ul>
<li>The actual file name starts with <code>lib</code>, and ends with the
<code>.so</code> extension. For example, the actual file name for the
<code>log</code> library is <code>liblog.so</code>.</li>
<li>The library lives in the following directory, relative to the NDK root:
<code>&lt;ndk&gt;/platforms/android-&lt;sdk_version&gt;/arch-&lt;abi&gt;/usr/lib/</code>.</li>
</ul>
<pre class="fragment">LOCAL_LDLIBS := -llog -landroid -lEGL -lGLESv1_CM
</pre><p>A static library, <code>android_native_app_glue</code>, that the
application uses to manage <code>NativeActivity</code> lifecycle events, along
with touch input.</p>
<pre class="fragment">LOCAL_STATIC_LIBRARIES := android_native_app_glue
</pre><p>The final line tells the build system to build this static library.
<code>ndk-build</code> places the built library
(<code>libandroid_native_app_glue.a</code>) into the <code>obj</code> directory
generated during the build process. The next sample discusses the
android_native_app_glue in more detail.</p>
<pre class="fragment">$(call import-module,android/native_app_glue)
</pre><p>For more information about the Application.mk file, consult the <a
href="./md_3__key__topics__building__a_p_p_l_i_c_a_t_i_o_n-_m_k.html">Application.mk section</a> of this guide.</p>
<h3><code>Application.mk</code></h3>
<p>This line defines the minimum level of Android API Level support.</p>
<pre class="fragment">APP_PLATFORM := android-10
</pre><p>Because there is no ABI definition, the build system defaults to
building only for armeabi.</p>
<h3>main.c</h3>
<p>This file essentially contains the entire progam.</p>
<p>The following includes correspond to the libraries, both shared and static,
enumerated in <code>Android.mk</code>.</p>
<pre class="fragment">#include &lt;EGL/egl.h&gt;
#include &lt;GLES/gl.h&gt;
#include &lt;android/sensor.h&gt;
#include &lt;android/log.h&gt;
#include &lt;android_native_app_glue&gt;
</pre><p><code>android_native_app_glue</code> calls the following function,
passing it a predefined state structure. It also serves as a wrapper that
simplifies handling of <code>NativeActivity</code> callbacks.</p>
<pre class="fragment">void android_main(struct android_app* state) {
</pre><p>Next, the program handles events queued by the glue library. The event
handler follows the state structure.</p>
<pre class="fragment">struct engine engine;
// Make sure glue isn't stripped by suppressing link-time optimization that
removes unreferenced code.
app_dummy();
memset(&amp;engine, 0, sizeof(engine));
state-&gt;userData = &amp;engine;
state-&gt;onAppCmd = engine_handle_cmd;
state-&gt;onInputEvent = engine_handle_input;
engine.app = state;
</pre><p>The application prepares to start monitoring the sensors, using the
APIs in <code>sensor.h</code>.</p>
<pre class="fragment"> engine.sensorManager = ASensorManager_getInstance();
engine.accelerometerSensor =
ASensorManager_getDefaultSensor(engine.sensorManager,
ASENSOR_TYPE_ACCELEROMETER);
engine.sensorEventQueue =
ASensorManager_createEventQueue(engine.sensorManager,
state-&gt;looper, LOOPER_ID_USER, NULL, NULL);
</pre><p>Now, a loop begins, in which the application polls the system for
messages (sensor events). It sends messages to
<code>android_native_app_glue</code>, which checks to see whether they match
any <code>onAppCmd</code> events defined in <code>android_main</code>. When a
match occurs, the message is sent to the handler for execution.</p>
<pre class="fragment">while (1) {
// Read all pending events.
int ident;
int events;
struct android_poll_source* source;
// If not animating, we will block forever waiting for events.
// If animating, we loop until all events are read, then continue
// to draw the next frame of animation.
while ((ident=ALooper_pollAll(engine.animating ? 0 : -1, NULL,
&amp;events,
(void**)&amp;source)) &gt;= 0) {
// Process this event.
if (source != NULL) {
source-&gt;process(state, source);
}
// If a sensor has data, process it now.
if (ident == LOOPER_ID_USER) {
if (engine.accelerometerSensor != NULL) {
ASensorEvent event;
while (ASensorEventQueue_getEvents(engine.sensorEventQueue,
&amp;event, 1) &gt; 0) {
LOGI("accelerometer: x=%f y=%f z=%f",
event.acceleration.x, event.acceleration.y,
event.acceleration.z);
}
}
}
// Check if we are exiting.
if (state-&gt;destroyRequested != 0) {
engine_term_display(&amp;engine);
return;
}
}
</pre><p>Once the queue is empty, and the program exits the polling loop, the
program calls OpenGL to draw the screen.</p>
<pre class="fragment"> if (engine.animating) {
// Done with events; draw next animation frame.
engine.state.angle += .01f;
if (engine.state.angle &gt; 1) {
engine.state.angle = 0;
}
// Drawing is throttled to the screen update rate, so there
// is no need to do timing here.
engine_draw_frame(&amp;engine);
}
} </pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK
Programmer&#39;s Guide by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
</body>
</html>

236
docs/html-ndk/ndk/guides/sample_teapot.jd Normal file
View File

@@ -0,0 +1,236 @@
page.title=Sample: Teapot
@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>
<p>This sample uses the OpenGL library to render the
iconic <a
href="http://math.hws.edu/bridgeman/courses/324/s06/doc/opengl.html#basic">Utah
teapot</a>. It particularly showcases the <code>ndk_helper</code> helper class,
a collection of native helper functions required for implementing games and
similar applications as native applications. This class provides:</p>
<ul>
<li>an abstraction layer that handles certain NDK-specific behaviors (e.g.,
<code>GLContext</code>).</li>
<li>some helper functions that are useful but not present in the NDK, itself
(e.g., tap detection).</li>
<li>wrappers for JNI calls for certain platform features (e.g., texture
loading).</li>
</ul>
<h3>AndroidManifest.xml</h3>
<p>The activity declaration here is not <code>NativeActivity</code> itself, but
a subclass: <code>TeapotNativeActivity</code>.</p>
<pre class="fragment"> &lt;activity
android:name="com.sample.teapot.TeapotNativeActivity"
android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden"&gt;
</pre><p>The name of the <code>.so</code> file is
<code>libTeapotNativeActivity.so</code>; the <code>lib</code> and
<code>.so</code> are stripped off from the value assigned to
<code>android:value</code>.</p>
<pre class="fragment"> &lt;meta-data android:name="android.app.lib_name"
android:value="TeapotNativeActivity" /&gt;
</pre><h3><code>Application.mk</code></h3>
<p>Define the minimum level of Android API Level support.</p>
<pre class="fragment">APP_PLATFORM := android-9
</pre><p>Build for all supported architectures.</p>
<pre class="fragment">APP_ABI := all
</pre><p>Specify the <a
href="./md_3__key__topics__libraries__c_p_l_u_s_p_l_u_s-_s_u_p_p_o_r_t.html">C++
runtime support library</a> to use. </p>
<pre class="fragment">APP_STL := stlport_static
</pre><h3>Java-side implementation: TeapotNativeActivity.java</h3>
<p>This file handles activity lifecycle events, as well as displaying text on
the screen.</p>
<pre class="fragment">// Our popup window, you will call it from your C/C++
code later
void setImmersiveSticky() {
View decorView = getWindow().getDecorView();
decorView.setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
| View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
| View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
| View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
| View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
| View.SYSTEM_UI_FLAG_LAYOUT_STABLE);
}
</pre><h3>Native-side implementation</h3>
<p>This section explores the C++ part of the Teapot app.</p>
<h4>TeapotRenderer.*</h4>
<p>This code does the actual rendering of the teapot. It uses
<code>ndk_helper</code> for matrix calculation, and to reposition the camera
based on where the user taps:</p>
<pre>
ndk_helper::Mat4 mat_projection_;
ndk_helper::Mat4 mat_view_;
ndk_helper::Mat4 mat_model_;
ndk_helper::TapCamera* camera_;
</pre>
<h4>TeapotNativeActivity.cpp</code></h4>
<p>Include <code>ndk_helper</code> in your native source file, and define the
helper-class name:</p>
<pre class="fragment">#include "NDKHelper.h"
//-------------------------------------------------------------------------
//Preprocessor
//-------------------------------------------------------------------------
#define HELPER_CLASS_NAME "com/sample/helper/NDKHelper" //Class name of helper
function
</pre><p>The first use of the <code>ndk_helper</code> class is to handle the
EGL-related lifecycle, associating EGL context states (created/lost) with
Android lifecycle events. It enables the application to preserve context
information so that a destroyed activity can be restored. This is useful, for
example, when the target machine is rotated (causing an activity to be
destroyed, then immediately restored in the new orientation), or when the lock
screen appears.</p>
<pre class="fragment">ndk_helper::GLContext* gl_context_; // handles
EGL-related lifecycle.
</pre><p>Next, <code>ndk_helper</code> provides touch control.</p>
<pre class="fragment">ndk_helper::DoubletapDetector doubletap_detector_;
ndk_helper::PinchDetector pinch_detector_;
ndk_helper::DragDetector drag_detector_;
ndk_helper::PerfMonitor monitor_;
</pre><p>And camera control (openGL view frustum).</p>
<pre class="fragment">ndk_helper::TapCamera tap_camera_;
</pre><p>As in the native-activity sample, the application prepares to use the
sensors, using the native APIs provided in the NDK.</p>
<pre class="fragment">ASensorManager* sensor_manager_;
const ASensor* accelerometer_sensor_;
ASensorEventQueue* sensor_event_queue_;
</pre><p>The following functions are called in response to various Android
lifecycle events and EGL context state changes, using various functionalities
provided by <code>ndk_helper</code> via the <code>Engine</code> class.</p>
<pre class="fragment">void LoadResources();
void UnloadResources();
void DrawFrame();
void TermDisplay();
void TrimMemory();
bool IsReady();
</pre><p>This function calls back to the Java side to update the UI display.</p>
<pre class="fragment">void Engine::ShowUI()
{
JNIEnv *jni;
app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL );
//Default class retrieval
jclass clazz = jni-&gt;GetObjectClass( app_-&gt;activity-&gt;clazz );
jmethodID methodID = jni-&gt;GetMethodID( clazz, "showUI", "()V" );
jni-&gt;CallVoidMethod( app_-&gt;activity-&gt;clazz, methodID );
app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread();
return;
}
</pre><p>And this one calls back to the Java side to draw a text box
superimposed on the screen rendered on the native side, and showing frame
count.</p>
<pre class="fragment">void Engine::UpdateFPS( float fFPS )
{
JNIEnv *jni;
app_-&gt;activity-&gt;vm-&gt;AttachCurrentThread( &amp;jni, NULL );
//Default class retrieval
jclass clazz = jni-&gt;GetObjectClass( app_-&gt;activity-&gt;clazz );
jmethodID methodID = jni-&gt;GetMethodID( clazz, "updateFPS", "(F)V" );
jni-&gt;CallVoidMethod( app_-&gt;activity-&gt;clazz, methodID, fFPS );
app_-&gt;activity-&gt;vm-&gt;DetachCurrentThread();
return;
}
</pre><p>The application gets the system clock and supplies it to the renderer
for time-based animation based on real-time clock. For example, calculating
momentum, where speed declines as a function of time.</p>
<pre class="fragment">renderer_.Update( monitor_.GetCurrentTime() );
</pre><p>Having earlier been set up to preserve context information, the
application now checks whether <code>GLcontext</code> is still valid. If not,
<code>ndk-helper</code> swaps the buffer, reinstantiating the GL context.</p>
<pre class="fragment">if( EGL_SUCCESS != gl_context_-&gt;Swap() ) // swaps
buffer.
</pre><p>The program passes touch-motion events to the gesture detector defined
in the <code>ndk_helper</code> class. The gesture detector tracks multitouch
gestures, such as pinch-and-drag, and sends a notification when triggered by
any of these events.</p>
<pre class="fragment">if( AInputEvent_getType( event ) ==
AINPUT_EVENT_TYPE_MOTION )
{
ndk_helper::GESTURE_STATE doubleTapState =
eng-&gt;doubletap_detector_.Detect( event );
ndk_helper::GESTURE_STATE dragState = eng-&gt;drag_detector_.Detect( event
);
ndk_helper::GESTURE_STATE pinchState = eng-&gt;pinch_detector_.Detect(
event );
//Double tap detector has a priority over other detectors
if( doubleTapState == ndk_helper::GESTURE_STATE_ACTION )
{
//Detect double tap
eng-&gt;tap_camera_.Reset( true );
}
else
{
//Handle pinch state
if( pinchState &amp; ndk_helper::GESTURE_STATE_START )
{
//Start new pinch
ndk_helper::Vec2 v1;
ndk_helper::Vec2 v2;
eng-&gt;pinch_detector_.GetPointers( v1, v2 );
</pre><p><code>ndk_helper</code> also provides access to a vector-math library
(<code>vecmath.h</code>), using it here to transform touch coordinates.</p>
<pre class="fragment">void Engine::TransformPosition( ndk_helper::Vec2&amp; vec
) { vec = ndk_helper::Vec2( 2.0f, 2.0f ) * vec / ndk_helper::Vec2(
gl_context_-&gt;GetScreenWidth(), gl_context_-&gt;GetScreenHeight() )
ndk_helper::Vec2( 1.f, 1.f ); }</li></pre>
</ul>
<p><code>HandleCmd()</code> handles commands posted from the
android_native_app_glue library. For more information about what the messages
mean, refer to the comments in the <code>android_native_app_glue.h</code> and
<code>.c</code> source files.</p>
<pre>
void Engine::HandleCmd( struct android_app* app, int32_t
cmd ) { Engine* eng = (Engine*) app-&gt;userData; switch( cmd ) { case
APP_CMD_SAVE_STATE: break; case APP_CMD_INIT_WINDOW: // The window is being
shown, get it ready. if( app-&gt;window != NULL )
</pre>
<p><code>ndk_helper</code> posts APP_CMD_INIT_WINDOW when android_app_glue
receives an <code>onNativeWindowCreated()</code> callback from the system.
Applications can normally perform window initializations, such as EGL
initialization. They do this outside of the activity lifecycle, since the
activity is not yet ready.</p>
<pre class="fragment">ndk_helper::JNIHelper::Init( state-&gt;activity,
HELPER_CLASS_NAME );
state-&gt;userData = &amp;g_engine;
state-&gt;onAppCmd = Engine::HandleCmd;
state-&gt;onInputEvent = Engine::HandleInput; </pre>

520
docs/html-ndk/ndk/guides/setup.html Normal file
View File

@@ -0,0 +1,520 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width" />
<meta name="Description" content="This document explains how to: This document assumes that you are already familiar with Java-based Android development. For more information on that topic, see the Android developer site . To install and configure the NDK, follow these steps: Eclipse …">
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
<title>Setup | Android Developers</title>
<!-- STYLESHEETS -->
<link rel="stylesheet"
href="//fonts.googleapis.com/css?family=Roboto+Condensed">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold"
title="roboto">
<link href="/assets/css/default.css?v=5" rel="stylesheet" type="text/css">
<!-- JAVASCRIPT -->
<script src="//www.google.com/jsapi" type="text/javascript"></script>
<script src="/assets/js/android_3p-bundle.js" type="text/javascript"></script>
<script type="text/javascript">
var toRoot = "/";
var metaTags = [];
var devsite = false;
</script>
<script src="/assets/js/docs.js?v=3" type="text/javascript"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-5831155-1', 'android.com');
ga('create', 'UA-49880327-2', 'android.com', {'name': 'universal'}); // New tracker);
ga('send', 'pageview');
ga('universal.send', 'pageview'); // Send page view for new tracker.
</script>
</head>
<body class="gc-documentation develop guide" itemscope itemtype="http://schema.org/Article">
<a name="top"></a>
<!-- dialog to prompt lang pref change when loaded from hardcoded URL
<div id="langMessage" style="display:none">
<div>
<div class="lang en">
<p>You requested a page in English, would you like to proceed with this language setting?</p>
</div>
<div class="lang es">
<p>You requested a page in Spanish (Español), would you like to proceed with this language setting?</p>
</div>
<div class="lang ja">
<p>You requested a page in Japanese (日本語), would you like to proceed with this language setting?</p>
</div>
<div class="lang ko">
<p>You requested a page in Korean (한국어), would you like to proceed with this language setting?</p>
</div>
<div class="lang ru">
<p>You requested a page in Russian (Русский), would you like to proceed with this language setting?</p>
</div>
<div class="lang zh-cn">
<p>You requested a page in Simplified Chinese (简体中文), would you like to proceed with this language setting?</p>
</div>
<div class="lang zh-tw">
<p>You requested a page in Traditional Chinese (繁體中文), would you like to proceed with this language setting?</p>
</div>
<a href="#" class="button yes" onclick="return false;">
<span class="lang en">Yes</span>
<span class="lang es">Sí</span>
<span class="lang ja">Yes</span>
<span class="lang ko">Yes</span>
<span class="lang ru">Yes</span>
<span class="lang zh-cn">是的</span>
<span class="lang zh-tw">没有</span>
</a>
<a href="#" class="button" onclick="$('#langMessage').hide();return false;">
<span class="lang en">No</span>
<span class="lang es">No</span>
<span class="lang ja">No</span>
<span class="lang ko">No</span>
<span class="lang ru">No</span>
<span class="lang zh-cn">没有</span>
<span class="lang zh-tw">没有</span>
</a>
</div>
</div> -->
<!-- Header -->
<div id="header-wrapper">
<div id="header">
<div class="wrap" id="header-wrap">
<div class="col-3 logo">
<a href="/index.html">
<img src="/assets/images/dac_logo.png"
srcset="/assets/images/dac_logo@2x.png 2x"
width="123" height="25" alt="Android Developers" />
</a>
<div class="btn-quicknav" id="btn-quicknav">
<a href="#" class="arrow-inactive">Quicknav</a>
<a href="#" class="arrow-active">Quicknav</a>
</div>
</div>
</div><!-- end header-wrap.wrap -->
</div><!-- end header -->
<!-- Secondary x-nav -->
<div id="nav-x">
<div class="wrap" style="position:relative;z-index:1">
<ul class="nav-x col-9 develop" style="width:100%">
<li class="guide"><a href="/ndk/guides/index.html">
Guides</a></li>
<li class="reference"><a href="/ndk/reference/index.html">
Reference</a></li>
<li class="samples"><a href="/ndk/samples/index.html">
Samples</a></li>
<li class="downloads"><a href="/ndk/downloads/index.html">
Downloads</a></li>
</li>
</ul>
</div>
</div>
<div id="searchResults" class="wrap" style="display:none;">
<h2 id="searchTitle">Results</h2>
<div id="leftSearchControl" class="search-control">Loading...</div>
</div>
</div> <!--end header-wrapper -->
<div id="sticky-header">
<div>
<a class="logo" href="#top"></a>
<a class="top" href="#top"></a>
<ul class="breadcrumb">
<li class="current">Setup</li>
</ul>
</div>
</div>
<div class="wrap clearfix" id="body-content">
<div class="col-3" id="side-nav" itemscope itemtype="http://schema.org/SiteNavigationElement">
<div id="devdoc-nav" class="scroll-pane">
<ul id="nav">
<li><strong>NDK</strong>
<ul>
<li><a href="/ndk/guides/index.html"><span class="en">Getting Started</span></a>
<ul>
<li><a href="setup.html">Setup</a></li>
<li><a href="concepts.html">Concepts</a></li>
</ul></li>
<li><a href="/ndk/guides/build.html"><span class="en">Building</span></a>
<ul>
<li><a href="">ndk-build</a></li>
<li><a href="">Android.mk</a></li>
<li><a href="">Application.mk</a></li>
<li><a href="">Standalone Toolchain</a></li>
</ul></li>
<li><a href="/ndk/guides/debug.html"><span class="en">Debugging</span></a>
<ul>
<li><a href="">ndk-gdb</a></li>
<li><a href="">ndk-stack</a></li>
</ul></li>
<li><a href="/ndk/guides/arch.html"><span class="en">Architectures and CPUs</span></a>
<ul>
<li><a href="">ABI Management</a></li>
<li><a href="">Neon</a></li>
<li><a href="">Mips</a></li>
<li><a href="">x86</a></li>
<li><a href="">x86-64</a></li>
<li><a href="">CPU Features</a></li>
</ul></li>
<li><a href="/ndk/guides/libs.html"><span class="en">Libraries</span></a>
<ul>
<li><a href="">Stable APIs</a></li>
<li><a href="">C++ Support</a></li>
<li><a href="">Prebuilt Libraries</a></li>
</ul></li>
<li><a href="/ndk/guides/sample.html"><span class="en">Sample Walkthrough</span></a>
<ul>
<li><a href="">hello-jni</a></li>
<li><a href="">native-activity</a></li>
<li><a href="">Teapot</a></li>
</ul></li>
<li><a href="/ndk/guides/atomics.html"><span class="en">Atomics</span></a></li>
<li><a href="/ndk/guides/importing.html"><span class="en">Importing Modules</span></a></li>
<li><a href="/ndk/guides/depends.html"><span class="en">ndk-depends</span></a></li>
<li><a href="/ndk/guides/system.html"><span class="en">System Image Issues</span></a></li>
<li><a href="/ndk/guides/licenses.html"><span class="en">Licenses</span></a></li>
</ul></li>
<li><strong>Radiance</strong>
<ul>
<li><a href="/ndk/guides/null.html"><span class="en">Stub 1</span></a>
<ul>
<li><a href="">Stublet</a></li>
<li><a href="">Stublet</a></li>
</ul></li>
<li><a href="/ndk/guides/null.html"><span class="en">Stub 2, etc.</span></a>
<ul>
<li><a href="">Another Stublet</a></li>
<li><a href="">Another Stublet</a></li>
</ul></li>
</ul></li>
</ul>
<script type="text/javascript">
<!--
buildToggleLists();
changeNavLang(getLangPref());
//-->
</script>
</div>
</div> <!-- end side-nav -->
<script>
$(document).ready(function() {
scrollIntoView("devdoc-nav");
});
</script>
<div class="col-12" id="doc-col" >
<h1 itemprop="name" >Setup</h1>
<div id="jd-content">
<div class="jd-descr" itemprop="articleBody">
<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="/">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="/sdk/index.html">Android SDK</a>.if you
have not already done so.</li>
<li><a href="/tools/sdk/ndk/index.html">Download</a> and unzip 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</code> 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> &gt; <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>&lt;ndk&gt;/samples/</code>, 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> &gt; <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</code> 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="/tools/building/index.html">Building and Running</a> and
<a href="/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="figure2" />
<p class="img-caption">
<strong>Figure 1.</strong> Target-device screen after successful launch.
</p>
</div>
<div class="content-footer layout-content-row"
itemscope itemtype="http://schema.org/SiteNavigationElement">
<div class="paging-links layout-content-col col-10">
</div>
<div class="layout-content-col plus-container col-2" >
<div class="g-plusone" data-size="medium"></div>
</div>
</div>
</div> <!-- end jd-content -->
<div id="footer" class="wrap" >
<div id="copyright">
Except as noted, this content is
licensed under <a href="http://creativecommons.org/licenses/by/2.5/">
Creative Commons Attribution 2.5</a>. For details and
restrictions, see the <a href="/license.html">Content
License</a>.
</div>
<div id="footerlinks">
<p>
<a href="/about/index.html">About Android</a>&nbsp;&nbsp;|&nbsp;
<a href="/legal.html">Legal</a>&nbsp;&nbsp;|&nbsp;
<a href="/support.html">Support</a>
</p>
</div>
</div> <!-- end footer -->
</div><!-- end doc-content -->
</div> <!-- end body-content -->
<script src="https://developer.android.com/ytblogger_lists_unified.js" type="text/javascript"></script>
<script src="/jd_lists_unified.js?v=8" type="text/javascript"></script>
<script src="/jd_extras.js?v=10" type="text/javascript"></script>
<script src="/jd_collections.js?v=10" type="text/javascript"></script>
<script src="/jd_tag_helpers.js?v=5" type="text/javascript"></script>
</body>
</html>

501
docs/html-ndk/ndk/guides/stable_apis.jd Normal file
View File

@@ -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-&lt;level&gt;/&lt;abi&gt;/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 would 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 &lt;android/log.h&gt;} 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
&lt;uses-feature&gt;}</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 &lt;GLES2/gl2.h&gt;} and {@code &lt;GLES2/gl2ext.h&gt;}
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
&lt;uses-feature&gt;}</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 &lt;uses-feature&gt;}, 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 &lt;bitmap.h&gt;} 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 &lt;native_activity.h&gt;}</li>
<li>{@code &lt;looper.h&gt;}</li>
<li>{@code &lt;input.h&gt;}</li>
<li>{@code &lt;keycodes.h&gt;}</li>
<li>{@code &lt;sensor.h&gt;}</li>
<li>{@code &lt;rect.h&gt;}</li>
<li>{@code &lt;window.h&gt;}</li>
<li>{@code &lt;native_window.h&gt;}</li>
<li>{@code &lt;native_window_jni.h&gt;}</li>
<li>{@code &lt;configuration.h&gt;}</li>
<li>{@code &lt;asset_manager.h&gt;}</li>
<li>{@code &lt;storage_manager.h&gt;}</li>
<li>{@code &lt;obb.h&gt;}</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 &lt;OMXAL/OpenMAXAL.h&gt;} and
{@code &lt;OMXAL/OpenMAXAL_Platform.h&gt;} 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
&lt;uses-feature&gt;}</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 &lt;uses-feature&gt;}, 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
&lt;uses-feature&gt;}</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 &lt;uses-feature&gt;}, 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>

575
docs/html-ndk/ndk/guides/standalone_toolchain.jd Normal file
View File

@@ -0,0 +1,575 @@
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-&lt;gcc-version&gt;}</td>
</tr>
<tr>
<td>x86-based</td>
<td>{@code x86-&lt;gcc-version&gt;}</td>
</tr>
<tr>
<td>MIPS-based</td>
<td>{@code mipsel-linux-android-&lt;gcc-version&gt;}</td>
</tr>
<tr>
<td>ARM64-based</td>
<td>{@code aarch64-linux-android-&lt;gcc-version&gt;}</td>
</tr>
<tr>
<td>X86-64-based</td>
<td>{@code x86_64-&lt;gcc-version&gt;}</td>
</tr>
<tr>
<td>MIPS64-based</td>
<td>{@code mips64el-linux-android--&lt;gcc-version&gt;}</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.1
(API level 22), for ARM architecture:</p>
<pre class="no-pretty-print">
SYSROOT=$NDK/platforms/android-22/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>Stable 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-v7a</td>
<td>{@code -target armv7-none-linux-androideabi}</td>
</tr>
<tr>
<td>armeabi</td>
<td>{@code -target armv5te-none-linux-androideabi}</td>
</tr>
<tr>
<td>x86</td>
<td>{@code -target i686-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="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-22 --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-22/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=&lt;toolchain&gt;} 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>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=&lt;toolchain&gt;} option. Table 4 shows the
values you can specify for {@code &lt;toolchain&gt;}:</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-android-4.6}</li>
<li>{@code --toolchain=arm-linux-android-4.7}</li>
<li>{@code --toolchain=arm-linux-android-4.8}</li>
<li>{@code --toolchain=arm-linux-android-4.9}</li>
<li>{@code --toolchain=arm-linux-android-clang3.4}</li>
<li>{@code --toolchain=arm-linux-android-clang3.5}</li>
</td>
</tr>
<tr>
<td>x86</td>
<td>
<li>{@code --toolchain=x86-linux-android-4.6}</li>
<li>{@code --toolchain=x86-linux-android-4.7}</li>
<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.4}</li>
<li>{@code --toolchain=x86-linux-android-clang3.5}</li>
</td>
</tr>
<tr>
<td>mips</td>
<td>
<li>{@code --toolchain=mips-linux-android-4.6}</li>
<li>{@code --toolchain=mips-linux-android-4.7}</li>
<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.4}</li>
<li>{@code --toolchain=mips-linux-android-clang3.5}</li>
</td>
</tr>
<tr>
<td>arm64</td>
<td>
<li>{@code --toolchain=aarch64-linux-android-4.9}</li>
<li>{@code --toolchain=aarch64-linux-android-clang3.4}</li>
<li>{@code --toolchain=aarch64-linux-android-clang3.5}</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.4}</li>
<li>{@code --toolchain=x86_64-linux-android-clang3.5}</li>
</td>
</tr>
<tr>
<td>mips64</td>
<td>
<li>{@code --toolchain=mips64el-linux-android-4.9}</li>
<li>{@code --toolchain=mips64el-linux-android-clang3.4}</li>
<li>{@code --toolchain=mips64el-linux-android-clang3.5}</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.3, using one of two methods: You can append {@code -clang3.3} 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.3
</pre>
<p>Alternatively, you can add {@code -llvm-version=3.3} as a separate option on the command
line.</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>
</table>
For more information on specifying a 32- or 64-bit instruction host toolchain, see
<a href="{@docRoot}/ndk/guides/ndk-build.html#6432">ndk-build</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/&lt;toolchain-name&gt;.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>Working with Clang</h2>
<p>You can install Clang binaries in the standalone installation by using the
{@code --llvm-version=&lt;version&gt;} option. {@code &lt;version&gt;} is a LLVM/Clang version
number, such as {@code 3.4} or {@code 3.5}. For example:
<pre class="no-pretty-print">
build/tools/make-standalone-toolchain.sh \
--install-dir=/tmp/mydir \
--toolchain=arm-linux-androideabi-4.7 \
--llvm-version=3.5
</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 &lt;install-dir&gt;/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.3}, 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 /clang31 -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>ABI Compatibility</h2>
<p>The machine code that the ARM toolchain generates should be compatible with the official Android
<a href="{docRoot}/ndk/guides/cpu-arch-abis.html">armeabi 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</a>.</p>
<h2>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=&lt;name&gt;} 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>x86</td>
<td>{@code $TOOLCHAIN/i686-linux-android/lib/}</td>
</tr>
<tr>
<td>MIPS</td>
<td>{@code $TOOLCHAIN/mipsel-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>

52
docs/html-ndk/ndk/guides/x86-64.jd Normal file
View File

@@ -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>It is possible to 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>

215
docs/html-ndk/ndk/guides/x86.jd Normal file
View File

@@ -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&ndash; 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>