Merge "Docs: Final, master CL for NDK-docs-to-DAC for IO: "Guides,"...

       localized titles are added in the language order specified below.

?>

<ul id="nav">

   <li class="nav-section">

      <div class="nav-section-header empty"><a href="/ndk/downloads/index.html"><span class="en">

      NDK Download</span></a>

      Downloads</span></a></div>

   </li>

   <li class="nav-section">

      <div class="nav-section-header empty"><a href="/ndk/downloads/revision_history.html">

      <span class="en">Revision History</span></a></div>

   </li>

</ul>

</div>

 <div id="qv-wrapper">

    <div id="qv">

      <h2>In this document</h2>

      <ol>

        <li><a href="#Downloads">Downloads</a></li>

        <li><a href="#rel">Release Notes</a></li>

      </ol>

    </div>

  </div>

  <p>Select, from the table below, the NDK package suitable for your development platform.</p>

  <p>Select, from the table below, the NDK package for your development platform. For information

  about the changes in the newest version of the NDK, see <a href="#rel">Release Notes</a>. For

  information about earlier revisions, see <a href="{@docRoot}ndk/downloads/revision_history.html">

  NDK Revision History.</a></p>

<h2 id="Downloads">Downloads</h2>

<h2 id="Downloads">Downloading</h2>

<script>

$('#Downloads').after($('#download-table'));

</script>

  <h2 id="extract">Extraction</h2>

  <p>The NDK package is a self-extracting binary. To unpack it, follow the procedure for your

  development platform:</p>

       <ul>

       <li>On Linux and Mac OS X (Darwin):

          <ul>

          <ol>

          <li>Download the appropriate package from this page.</li>

          <li>Open a terminal window.</li>

          <li>Go to the directory to which you downloaded the package.</li>

          <li>Run <code>chmod a+x</code> on the downloaded package.</li>

          <li>Execute the package. For example:

          <pre class="no-pretty-print">

ndk$ chmod a+x android-ndk-r10c-darwin-x86_64.bin

ndk$ ./android-ndk-r10c-darwin-x86_64.bin

          </pre></li>

          <p>The folder containing the NDK extracts itself.</p>

          <p>You can also use a program like 7z to extract the package.</p>

          </ol>

          </ul>

       </li>

    <li>On Windows:</li>

       <ul>

       <ol>

       <li>Download the appropriate package from this page.</li>

       <li>Navigate to the folder to which you downloaded the package.</li>

       <li>Double-click the downloaded file. The folder containing the NDK extracts itself.</li>

       </ol>

       </ul>

     </ul>When uncompressed, the NDK files are contained in a directory called

    <code>android-ndk-&lt;version&gt;</code>. You can rename the NDK directory if necessary and you

    can move it to any location on your computer. This documentation refers to the NDK directory as

    <code>&lt;ndk&gt;</code>.

  <p>You are now ready to start working with the NDK.</p>

<h2 id="rel">Release Notes</h2>

 <p>Android NDK, Revision 10e</a> <em>(May 2015)</em></p>

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

Each combination of CPU and instruction sets has its own Application Binary Interface, or

<i>ABI</i>. The ABI defines, with great precision, how an application's machine code is supposed to

interact with the system at runtime. You must specify an ABI for each CPU architecture you want

your app to work with.</p>

</tr>

<tr>

<td><a href="#v7a">{@code armeabi-v7a}</a></td>

<td><a href="#v7a">{@code armeabi-v7a} ({@code armeabi-v7a-hard)}</a></td>

<td>

<li>armeabi</li>

<li>Thumb-2</li>

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

<code>LOCAL_ARM_MODE</code> variable in your

<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>

file.</p>

<h3 id="v7a">armeabi-v7a (armeabi-v7a-hard)</h3>

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

<a href="{@docRoot}ndk/guides/cpu-features.html">The {@code cpufeatures} Library</a>.

Also, for information about the NDK's support for building

machine code for NEON, see

<a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON Support</a>.</p>

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>

x86 performance hints</a>.</p>

</li>

<li>Use of the standard Linux x86 32-bit calling convention, as opposed to the one for SVR. For

more information, see section 6, "Register Usage", of

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

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

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

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

        <li><a href="#mdv">Module-Description Variables</a></li>

      </ol>

    </div>

  </div>

<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

for defining project-wide settings that <a href="{@docRoot}ndk/guides/application_mk.html">{@code

Application.mk}</a>, the build system, and your

environment variables leave undefined. It can also override project-wide settings for specific

<i>modules</i>.</p>

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

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

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.

{@code Android.mk} files that you can look at. In addition,

<a href="{@docRoot}ndk/guides/sample_na.html">Sample: native-activity</a> provides

a detailed explanation of that sample's {@code Android.mk} file. Finally, <a href="#var">

Variables and Macros</a> provides further information on the variables from this section.

<h2 id="var">Variables and Macros</h2>

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>

information about these variables, see <a href = "#mdv">Module-Description Variables</a>).</p>

<p>The syntax for using this variable is:</p>

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

{@code LOCAL_PREBUILTS} variable. For more information about using prebuilts, see

<a href="{@docRoot}ndk/guides/prebuilts.html">Using Prebuilt Libraries</a>.</p>

<h4>PREBUILT_STATIC_LIBRARY</h4>

<p>The same as {@code PREBUILT_SHARED_LIBRARY}, but for a prebuilt static library. For more

information about using prebuilts, see <a href="{@docRoot}ndk/guides/prebuilts.html">NDK Prebuilt

Library Support</a>.</p>

information about using prebuilts, see <a href="{@docRoot}ndk/guides/prebuilts.html">Using Prebuilt

Libraries</a>.</p>

<h4>TARGET_ARCH</h4>

<p>The name of the target CPU architecture as the Android Open Source Project specifies it.

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>

{@code Android.mk} file, which the system reads ahead of parsing the {@code Android.mk} file.</p>

<h4>TARGET_PLATFORM</h4>

<p>The Android API level number for the build system to target.

For example, the Android 5.1 system images correspond to Android API level 22: {@code android-22}.

For a complete list of platform names and corresponding Android system

images, see <a href="{@docRoot}ndk/guides/stable_apis.html">Android NDK Stable APIs</a>.

images, see <a href="{@docRoot}ndk/guides/stable_apis.html">Android NDK Native APIs</a>.

The following example shows the syntax for using this variable:</p>

<pre class="no-pretty-print">

    <th scope="col">Setting</th>

  </tr>

  <tr>

    <th scope="col">ARMv5TE</th>

    <th scope="col">{@code armeabi}</th>

    <td>ARMv5TE</td>

    <td>{@code armeabi}</td>

  </tr>

  <tr>

    <th scope="col">ARMv7</th>

    <th scope="col">{@code armeabi-v7a}</th>

    <td>ARMv7</td>

    <td>{@code armeabi-v7a}</td>

  </tr>

  <tr>

    <th scope="col">ARMv8 AArch64</th>

    <th scope="col">{@code arm64-v8a}</th>

    <td>ARMv8 AArch64</td>

    <td>{@code arm64-v8a}</td>

  </tr>

  <tr>

    <th scope="col">i686</th>

    <th scope="col">{@code x86}</th>

    <td>i686</td>

    <td>{@code x86}</td>

  </tr>

  <tr>

    <th scope="col">x86-64</th>

    <th scope="col">{@code x86_64}</th>

    <td>x86-64</td>

    <td>{@code x86_64}</td>

  </tr>

  <tr>

    <th scope="col">mips32 (r1)</th>

    <th scope="col">{@code mips}</th>

    <td>mips32 (r1)</td>

    <td>{@code mips}</td>

  </tr>

  <tr>

    <th scope="col">mips64 (r6)</th>

    <th scope="col">{@code mips64}</th>

    <td>mips64 (r6)</td>

    <td>{@code mips64}</td>

  </tr>

  <tr>

    <th scope="col">All</th>

    <th scope="col">{@code all}</th>

    <td>All</td>

    <td>{@code all}</td>

  </tr>

</table>

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

<a href="{@docRoot}ndk/guides/abis.html">ABI Management</a>.</p>

<p>New target ABIs in the future will have different values.</p>

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

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

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

automatically. Throughout your {@code Android.mk} and

<a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> files, refer to

your module by its unmodified name. For example, the following line results in the generation of a

shared library module called {@code libfoo.so}:</p>

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

<p>We recommend avoiding absolute file paths; relative paths make your {@code Android.mk} file more

portable.</p>

<p class="note"><strong>Note: </strong> Always use Unix-style forward slashes (/) in build files.

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

in the <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file. Doing it

this way allows the build system to generate useful data files used during debugging.</p>

<p class="note"><strong>Note: </strong>In android-ndk-1.5_r1, the corresponding flags only applied

to C source files, not C++ ones. They now match the full Android build system behavior.

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

<a href="stable_apis.html">Android NDK Native APIs</a>.</p>

<p class="note"><strong>Note: </strong> If you define this variable for a static library,

the build system ignores it, and {@code ndk-build} prints a warning.</p>

<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

<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

<p>This variable only matters when you are targeting the {@code armeabi-v7a} ABI. It allows the

use of ARM Advanced SIMD (NEON) GCC intrinsics in your C and C++ sources, as well as NEON

instructions in Assembly files.</p>

<p>Note that not all ARMv7-based CPUs support the NEON instruction set extensions. For this reason,

you must perform runtime detection to be able to safely use this code at runtime. For more

information, 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>

information, see <a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON Support</a> and <a

href="{@docRoot}ndk/guides/cpu-features.html">The {@code cpufeatures} Library</a>.</p>

<p>Alternatively, you can use the {@code .neon} suffix to specify that the build system only

compile specific source files with NEON support. In the following example, the build system compiles

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

<p>This protection is on by default, but you can disable it by setting the value of

this variable to {@code true}. We do not recommend doing so without a compelling reason.</p>

<h4>LOCAL_EXPORT_CFLAGS</h4>

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

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

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}

default value can be set in your <a href="{@docRoot}ndk/guides/application_mk.html">

{@code Application.mk}</a> file through the {@code APP_THIN_ARCHIVE}

variable.</p>

<p class="note"><strong>Note:</strong> This is ignored for non-static library modules, or prebuilt

myasmfilter bar.S $OBJS_DIR/bar.S

</pre>

<h3 id="npfm">NDK-Provided Function Macros</h2>

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

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>

<p>A function that allows you to find and include a module's {@code Android.mk} file by the name of

the module. A typical example is as follows: </p>

<pre class="no-pretty-print">

$(call import-module,<name>)

</pre>

<p>In this example, the build system looks for the module tagged &lt;name&gt; in the list of

<p>In this example, the build system looks for the module tagged {@code &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>For more information, see <a href="import.html">Android Module Paths (Sharing Code)</a>.

</p>