Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 32ad52fb authored by David Friedman's avatar David Friedman Committed by Android Git Automerger
Browse files

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

* commit 'db7b487e':
  Docs: NDK docs--incorporating comments from eng review.
parents 130c674b db7b487e

docs/html-ndk/ndk/guides/application_mk.jd

+9 −31
Original line number Original line Diff line number Diff line
@@ -181,33 +181,9 @@ Android system images, see <a href="{@docRoot}ndk/guides/stable_apis.html">Andro 
<p>By default, the NDK build system provides C++ headers for the minimal C++ runtime library

<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

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

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

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

support for different libraries.</p>

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



Features</a>.

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







<h4>APP_SHORT_COMMANDS</h4>

<h4>APP_SHORT_COMMANDS</h4>

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

<p>The equivalent of {@code LOCAL_SHORT_COMMANDS} in {@code Application.mk} for your whole project.
@@ -222,10 +198,12 @@ To select a version of Clang, define this variable as {@code clang3.4}, {@code c 




<h4>APP_PIE</h4>

<h4>APP_PIE</h4>

<p>Starting from Android 4.1 (API level 16), Android's dynamic linker supports position-independent

<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

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

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

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

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

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

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

libraries.</p>

libraries.</p>

docs/html-ndk/ndk/guides/cpp-support.jd

+1 −1
Original line number Original line Diff line number Diff line
@@ -32,7 +32,7 @@ these helper runtimes, their characteristics, and how to use them. 




<p>Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.</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>

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





<table>

<table>

docs/html-ndk/ndk/guides/standalone_toolchain.jd

+73 −43
Original line number Original line Diff line number Diff line
@@ -78,11 +78,11 @@ level.</p> 
<p>Native APIs for the respective <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">

<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

Android API levels</a> reside under {@code $NDK/platforms/}; each API-level

directory, in turn, contains subdirectories for the various CPUs and architectures. The

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

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

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

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





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

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

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

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

</pre>

</pre>





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

For more detail about the Android API levels and the respective native APIs they support, see
@@ -119,20 +119,28 @@ $CC -o foo.o -c foo.c 
    <th scope="col">Architecture</th>

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

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

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

  </tr>

  </tr>

  <tr>

    <td>armeabi</td>

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

  </tr>

  <tr>

  <tr>

    <td>armeabi-v7a</td>

    <td>armeabi-v7a</td>

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

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

  </tr>

  </tr>

  <tr>

  <tr>

    <td>armeabi</td>

     <td>arm64-v8a</td>

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

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

  </tr>

  </tr>

  <tr>

  <tr>

    <td>x86</td>

    <td>x86</td>

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

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

  </tr>

  </tr>

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

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

  </tr>

  </tr>

</table>

</table>
@@ -147,7 +155,7 @@ following example:</li> 
Ultimately, a command to compile using Clang might look like this:

Ultimately, a command to compile using Clang might look like this:





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

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

linux-x86/bin/arm-linux-androideabi-gcc-4.8 --sysroot=$SYSROOT" -target \

armv7-none-linux-androideabi \

armv7-none-linux-androideabi \

-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64"

-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64"
@@ -165,11 +173,11 @@ installation root for the NDK. An example of the use of this script appears belo 




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

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

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

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

</pre>





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

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

architecture.</p>





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

<p>Note that the toolchain binaries do not depend on or contain host-specific paths, in other words,
@@ -186,6 +194,14 @@ Table 3 shows the values to use for other toolchains: 
    <th scope="col">Toolchain</th>

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

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

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

  </tr>

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

  <tr>

    <td>x86 GCC 4.8 compiler</td>

    <td>x86 GCC 4.8 compiler</td>

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

    <td>{@code --arch=x86}</td>
@@ -195,7 +211,7 @@ Table 3 shows the values to use for other toolchains: 
    <td>{@code --arch=x86_64}</td>

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

  </tr>

  </tr>

  <tr>

  <tr>

    <td>MIPS GCC 4.8 compiler</td>

    <td>mips GCC 4.8 compiler</td>

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

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

  </tr>

  </tr>

</table>

</table>
@@ -214,34 +230,28 @@ values you can specify for {@code &lt;toolchain&gt;}:</p> 
  <tr>

  <tr>

    <td>arm</td>

    <td>arm</td>

    <td>

    <td>

       <li>{@code --toolchain=arm-linux-android-4.6}</li>

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

       <li>{@code --toolchain=arm-linux-android-4.7}</li>

       <li>{@code --toolchain=arm-linux-androideabi-4.9}</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>

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

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

    </td>

    </td>

  </tr>

  </tr>

  <tr>

  <tr>

    <td>x86</td>

    <td>x86</td>

    <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.8}</li>

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

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

    </td>

    </td>

  </tr>

  </tr>

  <tr>

  <tr>

    <td>mips</td>

    <td>mips</td>

    <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.8}</li>

       <li>{@code --toolchain=mips-linux-android-4.9}</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.5}</li>

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

    </td>

    </td>

  </tr>

  </tr>
@@ -249,42 +259,46 @@ values you can specify for {@code &lt;toolchain&gt;}:</p> 
    <td>arm64</td>

    <td>arm64</td>

    <td>

    <td>

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

       <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.5}</li>

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

    </td>

    </td>

  </tr>

  </tr>

  <tr>

  <tr>

    <td>x86_64</td>

    <td>x86_64</td>

    <td>

    <td>

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

       <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.5}</li>

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

    </td>

    </td>

  </tr>

  </tr>

  <tr>

  <tr>

    <td>mips64</td>

    <td>mips64</td>

    <td>

    <td>

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

       <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.5}</li>

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

    </td>

    </td>

  </tr>

  </tr>

</table>

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

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

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

example:

example:





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

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

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

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

</pre>

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

line.</p>





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

use {@code &lt;version&gt;}, 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

<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

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

platforms.</p>

platforms.</p>
@@ -304,17 +318,21 @@ platforms.</p> 
    <td>64-bit MacOSX</td>

    <td>64-bit MacOSX</td>

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

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

  </tr>

  </tr>

  <tr>

    <td>64-bit Windows</td>

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

  </tr>

</table>

</table>





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

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

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

<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

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

explicitly use {@code -lstlport_shared}. This requirement is similar to having to use

{@code -lgnustl_shared} for GNU {@code libstdc++}.</p>

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

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>

<p>You can make these settings directly, as in the following example:</p>
@@ -337,13 +355,13 @@ copy of a C++ STL library, with working exceptions and RTTI support.</p> 
<h2 id="wwc">Working with Clang</h2>

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

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

<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

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

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





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

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

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

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

--install-dir=/tmp/mydir \

--install-dir=/tmp/mydir \

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

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

--llvm-version=3.5

--llvm-version=3.6

</pre>

</pre>





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

<p>Note that Clang binaries are copied along with the GCC ones, because they rely on the same
@@ -356,12 +374,12 @@ be able to use them in your own builds by just setting the {@code CC} and {@code 
variables to point to them.</p>

variables to point to them.</p>





<h4>Invoking Clang</h4>

<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

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

instance:</p>

instance:</p>





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

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

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

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

</pre>

</pre>





<p><code>clang++</code> invokes <code>clang++31</code> in the same way.</p>

<p><code>clang++</code> invokes <code>clang++31</code> in the same way.</p>
@@ -404,7 +422,7 @@ working properly:</p> 
<ul>

<ul>

<li>{@code -v} to dump commands associated with compiler driver issues</li>

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

<li>{@code -save-temps} to compare {@code *.i} or {@code *.ii} preprocessed files.</li>

</ul>

</ul>
@@ -516,7 +534,7 @@ arm-linux-androideabi-g++ .... -lsupc++ 
<h3>C++ STL support</h3>

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

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

<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

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

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

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





<ul>

<ul>
@@ -551,17 +569,29 @@ for your code to load properly. Table 6 shows where this file is for each toolch 
    <th scope="col">Location</th>

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

  </tr>

  </tr>

  <tr>

  <tr>

    <td>ARM</td>

    <td>arm</td>

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

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

  </tr>

  </tr>

  <tr>

    <td>arm64</td>

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

  </tr>

  <tr>

  <tr>

    <td>x86</td>

    <td>x86</td>

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

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

  </tr>

  </tr>

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

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

  </tr>

  </tr>

  <tr>

    <td>mips64</td>

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

  </tr>

</table>

</table>





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

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