Merge "Docs: NDK docs--incorporating comments from eng review." into mnc-preview-docs

<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++ Library Support</a>.</p>

Use {@code APP_STL} to select one of them. For information about the supported runtimes, and the

features they offer, see <a href="{@docRoot}ndk/guides/cpp-support.html#runtimes">NDK Runtimes and

Features</a>.

<h4>APP_SHORT_COMMANDS</h4>

<p>The equivalent of {@code LOCAL_SHORT_COMMANDS} in {@code Application.mk} for your whole project.

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

executables (PIE). From Android 5.0 (API level 21), executables require PIE.

To use PIE to build your executables, set the {@code -fPIE} flag. This flag makes it harder to

exploit memory corruption bugs by randomizing code location. By default, {@code ndk-build}

automatically sets this value to {@code true} if your project targets {@code android-16} or higher.

You may set it manually to either {@code true} or {@code false}.</p>

<p>This flag applies only to executables. It has no effect when building shared or static

libraries.</p>

<p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</p>

<p class="table-caption" id="table1">

<p class="table-caption" id="runtimes">

  <strong>Table 1.</strong> NDK Runtimes and Features.</p>

<table>

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

following example shows how to define a <em>sysroot</em> for a build targeting Android 5.0

(API level 21), for ARM architecture:</p>

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

SYSROOT=$NDK/platforms/android-22/arch-arm

SYSROOT=$NDK/platforms/android-21/arch-arm

</pre>

For more detail about the Android API levels and the respective native APIs they support, see

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

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

  </tr>

  <tr>

    <td>armeabi</td>

    <td>{@code -target armv5te-none-linux-androideabi}</td>

  </tr>

  <tr>

    <td>armeabi-v7a</td>

    <td>{@code -target armv7-none-linux-androideabi}</td>

  </tr>

  <tr>

    <td>armeabi</td>

    <td>{@code -target armv5te-none-linux-androideabi}</td>

     <td>arm64-v8a</td>

     <td>{@code -target aarch64-none-linux-android}</td>

  </tr>

  <tr>

    <td>x86</td>

    <td>{@code -target i686-none-linux-android}</td>

  </tr>

  <tr>

    <td>MIPS</td>

    <td>x86_64</td>

    <td>{@code -target x86_64-none-linux-android}</td>

  </tr>

  <tr>

    <td>mips</td>

    <td>{@code -target mipsel-none-linux-android}</td>

  </tr>

</table>

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

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"

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

$NDK/build/tools/make-standalone-toolchain.sh \

--arch=arm --platform=android-22 --install-dir=/tmp/my-android-toolchain

--arch=arm --platform=android-21 --install-dir=/tmp/my-android-toolchain

</pre>

<p>This command creates a directory named {@code /tmp/my-android-toolchain/}, containing a copy of

the {@code android-22/arch-arm} sysroot, and of the toolchain binaries for a 32-bit ARM

the {@code android-21/arch-arm} sysroot, and of the toolchain binaries for a 32-bit ARM

architecture.</p>

<p>Note that the toolchain binaries do not depend on or contain host-specific paths, in other words,

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

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

  </tr>

  <tr>

    <td>mips64 compiler</td>

    <td>{@code --arch=mips64}</td>

  </tr>

  <tr>

    <td>mips GCC 4.8 compiler</td>

    <td>{@code --arch=mips}</td>

  </tr>

  <tr>

    <td>x86 GCC 4.8 compiler</td>

    <td>{@code --arch=x86}</td>

    <td>{@code --arch=x86_64}</td>

  </tr>

  <tr>

    <td>MIPS GCC 4.8 compiler</td>

    <td>mips GCC 4.8 compiler</td>

    <td>{@code --arch=mips}</td>

  </tr>

</table>

  <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-androideabi-4.8}</li>

       <li>{@code --toolchain=arm-linux-androideabi-4.9}</li>

       <li>{@code --toolchain=arm-linux-android-clang3.5}</li>

       <li>{@code --toolchain=arm-linux-android-clang3.6}</li>

    </td>

  </tr>

  <tr>

    <td>x86</td>

    <td>

       <li>{@code --toolchain=x86-linux-android-4.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>

       <li>{@code --toolchain=x86-linux-android-clang3.6}</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>

       <li>{@code --toolchain=mips-linux-android-clang3.6}</li>

    </td>

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

       <li>{@code --toolchain=aarch64-linux-android-clang3.6}</li>

    </td>

  </tr>

  <tr>

    <td>x86_64</td>

    <td>

       <li>{@code --toolchain=x86_64-linux-android-4.9}</li>

       <li>{@code --toolchain=x86_64-linux-android-clang3.4}</li>

       <li>{@code --toolchain=x86_64-linux-android-clang3.5}</li>

       <li>{@code --toolchain=x86_64-linux-android-clang3.6}</li>

    </td>

  </tr>

  <tr>

    <td>mips64</td>

    <td>

       <li>{@code --toolchain=mips64el-linux-android-4.9}</li>

       <li>{@code --toolchain=mips64el-linux-android-clang3.4}</li>

       <li>{@code --toolchain=mips64el-linux-android-clang3.5}</li>

       <li>{@code --toolchain=mips64el-linux-android-clang3.6}</li>

    </td>

  </tr>

</table>

<p class="note"<strong>Note: </strong> Table 4 is not an exhaustive list. Other combinations may

<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

<p>You can also copy Clang/LLVM 3.6, using one of two methods: You can append {@code -clang3.6} to

the {@code --toolchain} option, so that the {@code --toolchain} option looks like the following

example:

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

--toolchain=arm-linux-androideabi-clang3.3

--toolchain=arm-linux-androideabi-clang3.6

</pre>

<p>Alternatively, you can add {@code -llvm-version=3.3} as a separate option on the command

<p>You can also add {@code -llvm-version=3.6} as a separate option on the command

line.</p>

<p class="note"><strong>Note: </strong>Instead of specifying a specific version, you can also

use {@code <version>}, which defaults

to the highest available version of Clang.</p>

<p>By default, the build system builds for a 32-bit host toolchain. You can specify a 64-bit

host toolchain instead. Table 5 shows the value to use with {@code -system} for different

platforms.</p>

    <td>64-bit MacOSX</td>

    <td>{@code -system=darwin-x86_64}</td>

  </tr>

  <tr>

    <td>64-bit Windows</td>

    <td>{@code -system=windows-x86_64}</td>

  </tr>

</table>

For more information on specifying a 32- or 64-bit instruction host toolchain, see

<a href="{@docRoot}ndk/guides/ndk-build.html#6432">ndk-build</a>.

For more information on specifying a 64- or 32-bit instruction host toolchain, see

<a href="{@docRoot}ndk/guides/ndk-build.html#6432">64-Bit and 32-Bit Toolchains</a>.

<p>You may specify {@code stl=stlport} to copy {@code libstlport} instead of the default

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

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

<h2 id="wwc">Working with Clang</h2>

<p>You can install Clang binaries in the standalone installation by using the

{@code --llvm-version=<version>} option. {@code <version>} is a LLVM/Clang version

number, such as {@code 3.4} or {@code 3.5}. For example:

number, such as {@code 3.5} or {@code 3.6}. For example:

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

build/tools/make-standalone-toolchain.sh \

--install-dir=/tmp/mydir \

--toolchain=arm-linux-androideabi-4.7 \

--llvm-version=3.5

--toolchain=arm-linux-androideabi-4.8 \

--llvm-version=3.6

</pre>

<p>Note that Clang binaries are copied along with the GCC ones, because they rely on the same

variables to point to them.</p>

<h4>Invoking Clang</h4>

<p>In an ARM standalone installation built with {@code llvm-version=3.3}, invoking

<p>In an ARM standalone installation built with {@code llvm-version=3.6}, invoking

<a href="http://clang.llvm.org/">Clang</a> on a Unix system takes the form of a single line. For

instance:</p>

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

dirname $0 /clang31 -target armv5te-none-linux-androideabi "$@"

`dirname $0`/clang36 -target armv5te-none-linux-androideabi "$@"

</pre>

<p><code>clang++</code> invokes <code>clang++31</code> in the same way.</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 -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>

<h3>C++ STL support</h3>

<p>The standalone toolchain includes a copy of a C++ Standard Template Library implementation. This

implementation is either for GNU libstdc++, STLport, or libc++, depending on what you specify for the

{@code -stl=<name>} option described previously. To use this implementation of STL, you need

{@code --stl=<name>} option described previously. To use this implementation of STL, you need

to link your project with the proper library:</p>

<ul>

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

  </tr>

  <tr>

    <td>ARM</td>

    <td>arm</td>

    <td>{@code $TOOLCHAIN/arm-linux-androideabi/lib/}</td>

  </tr>

  <tr>

    <td>arm64</td>

    <td>{@code $TOOLCHAIN/aarch64-linux-android/lib/}</td>

  </tr>

  <tr>

    <td>x86</td>

    <td>{@code $TOOLCHAIN/i686-linux-android/lib/}</td>

  </tr>

  <tr>

    <td>MIPS</td>

    <td>x86_64</td>

    <td>{@code $TOOLCHAIN/x86_64-linux-android/lib/}</td>

  </tr>

  <tr>

    <td>mips</td>

    <td>{@code $TOOLCHAIN/mipsel-linux-android/lib/}</td>

  </tr>

  <tr>

    <td>mips64</td>

    <td>{@code $TOOLCHAIN/mips64el-linux-android/lib/}</td>

  </tr>

</table>

<p class="note"><strong>Note: </strong>If your project contains multiple shared libraries or