From a766e6860a51cf2ab83e1462a4314084ab95597e Mon Sep 17 00:00:00 2001 From: David Friedman Date: Tue, 26 May 2015 17:41:42 -0700 Subject: [PATCH] Docs: NDK docs--incorporating comments from eng review. The comments were entered into CL 682309, but implemented in this CL because of a change in branch. Change-Id: Ief5693b768890103fb48d9f377143002bd1a793d --- docs/html-ndk/ndk/guides/application_mk.jd | 40 ++---- docs/html-ndk/ndk/guides/cpp-support.jd | 2 +- .../ndk/guides/standalone_toolchain.jd | 116 +++++++++++------- 3 files changed, 83 insertions(+), 75 deletions(-) diff --git a/docs/html-ndk/ndk/guides/application_mk.jd b/docs/html-ndk/ndk/guides/application_mk.jd index d51cf6478be11..fab611b3ca55d 100644 --- a/docs/html-ndk/ndk/guides/application_mk.jd +++ b/docs/html-ndk/ndk/guides/application_mk.jd @@ -181,33 +181,9 @@ Android system images, see Andro

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.

- -

- Table 2. {@code APP_STL} settings to support different libraries.

- - - - - - - - - - - - - - - - - -
LibraryValue
Static STLport{@code APP_STL := stlport_static}
Shared STLport{@code APP_STL := stlport_shared}
Default C++ runtime{@code APP_STL := system}
- -

For more information on this subject, see -C++ Library Support.

- +Use {@code APP_STL} to select one of them. For information about the supported runtimes, and the +features they offer, see NDK Runtimes and +Features.

APP_SHORT_COMMANDS

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

APP_PIE

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

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

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

diff --git a/docs/html-ndk/ndk/guides/cpp-support.jd b/docs/html-ndk/ndk/guides/cpp-support.jd index ff170f42d9df4..0074b808aa8fc 100644 --- a/docs/html-ndk/ndk/guides/cpp-support.jd +++ b/docs/html-ndk/ndk/guides/cpp-support.jd @@ -32,7 +32,7 @@ these helper runtimes, their characteristics, and how to use them.

Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.

-

+

Table 1. NDK Runtimes and Features.

diff --git a/docs/html-ndk/ndk/guides/standalone_toolchain.jd b/docs/html-ndk/ndk/guides/standalone_toolchain.jd index 62d22b5624a33..895f0fc5e39dd 100644 --- a/docs/html-ndk/ndk/guides/standalone_toolchain.jd +++ b/docs/html-ndk/ndk/guides/standalone_toolchain.jd @@ -78,11 +78,11 @@ level.

Native APIs for the respective Android API levels 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 sysroot for a build targeting Android 5.1 -(API level 22), for ARM architecture:

+following example shows how to define a sysroot for a build targeting Android 5.0 +(API level 21), for ARM architecture:

-SYSROOT=$NDK/platforms/android-22/arch-arm
+SYSROOT=$NDK/platforms/android-21/arch-arm
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 + + + + - - + + - + - - + + + + + +
Architecture Value
armeabi{@code -target armv5te-none-linux-androideabi}
armeabi-v7a {@code -target armv7-none-linux-androideabi}
armeabi{@code -target armv5te-none-linux-androideabi}arm64-v8a{@code -target aarch64-none-linux-android}
x86 {@code -target i686-none-linux-android}
MIPS
x86_64{@code -target x86_64-none-linux-android}
mips {@code -target mipsel-none-linux-android}
@@ -147,7 +155,7 @@ following example: Ultimately, a command to compile using Clang might look like this: 
-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"
@@ -165,11 +173,11 @@ installation root for the NDK. An example of the use of this script appears belo
 
 
 $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
 

 
 
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.

 
 
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:
     Toolchain
     Value
   
+  
+    mips64 compiler
+    {@code --arch=mips64}
+  
+  
+    mips GCC 4.8 compiler
+    {@code --arch=mips}
+  
   
     x86 GCC 4.8 compiler
     {@code --arch=x86}
@@ -195,7 +211,7 @@ Table 3 shows the values to use for other toolchains:
     {@code --arch=x86_64}
   
   
-    MIPS GCC 4.8 compiler
+    mips GCC 4.8 compiler
     {@code --arch=mips}
   
 
@@ -214,34 +230,28 @@ values you can specify for {@code <toolchain>}:

   
     arm
     
-       
  • {@code --toolchain=arm-linux-android-4.6}
    • 
-       
  • {@code --toolchain=arm-linux-android-4.7}
    • 
-       
  • {@code --toolchain=arm-linux-android-4.8}
    • 
-       
  • {@code --toolchain=arm-linux-android-4.9}
    • 
-       
  • {@code --toolchain=arm-linux-android-clang3.4}
    • 
+       
  • {@code --toolchain=arm-linux-androideabi-4.8}
    • 
+       
  • {@code --toolchain=arm-linux-androideabi-4.9}
    • 
        
  • {@code --toolchain=arm-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=arm-linux-android-clang3.6}
    • 
     
   
   
     x86
     
-       
  • {@code --toolchain=x86-linux-android-4.6}
    • 
-       
  • {@code --toolchain=x86-linux-android-4.7}
    • 
        
  • {@code --toolchain=x86-linux-android-4.8}
    • 
        
  • {@code --toolchain=x86-linux-android-4.9}
    • 
-       
  • {@code --toolchain=x86-linux-android-clang3.4}
    • 
        
  • {@code --toolchain=x86-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=x86-linux-android-clang3.6}
    • 
     
   
   
     mips
     
-       
  • {@code --toolchain=mips-linux-android-4.6}
    • 
-       
  • {@code --toolchain=mips-linux-android-4.7}
    • 
        
  • {@code --toolchain=mips-linux-android-4.8}
    • 
        
  • {@code --toolchain=mips-linux-android-4.9}
    • 
-       
  • {@code --toolchain=mips-linux-android-clang3.4}
    • 
        
  • {@code --toolchain=mips-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=mips-linux-android-clang3.6}
    • 
     
   
 
@@ -249,42 +259,46 @@ values you can specify for {@code <toolchain>}:
    
     arm64
     
        
  • {@code --toolchain=aarch64-linux-android-4.9}
    • 
-       
  • {@code --toolchain=aarch64-linux-android-clang3.4}
    • 
        
  • {@code --toolchain=aarch64-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=aarch64-linux-android-clang3.6}
    • 
     
   
   
     x86_64
     
        
  • {@code --toolchain=x86_64-linux-android-4.9}
    • 
-       
  • {@code --toolchain=x86_64-linux-android-clang3.4}
    • 
        
  • {@code --toolchain=x86_64-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=x86_64-linux-android-clang3.6}
    • 
     
   
   
     mips64
     
        
  • {@code --toolchain=mips64el-linux-android-4.9}
    • 
-       
  • {@code --toolchain=mips64el-linux-android-clang3.4}
    • 
        
  • {@code --toolchain=mips64el-linux-android-clang3.5}
    • 
+       
  • {@code --toolchain=mips64el-linux-android-clang3.6}
    • 
     
   
 
 
-
    Note:  Table 4 is not an exhaustive list. Other combinations may
+
    Note:  Table 4 is not an exhaustive list. Other combinations may
 also be valid, but are unverified.
    
 
-
    You can also copy Clang/LLVM 3.3, using one of two methods: You can append {@code -clang3.3} to
+
    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:
 
 
    ---toolchain=arm-linux-androideabi-clang3.3
+--toolchain=arm-linux-androideabi-clang3.6
 
    
 
-
    Alternatively, you can add {@code -llvm-version=3.3} as a separate option on the command
+
    You can also add {@code -llvm-version=3.6} as a separate option on the command
 line.
    
 
+
    Note: Instead of specifying a specific version, you can also
+use {@code <version>}, which defaults
+to the highest available version of Clang.
    
+
 
    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.
    
@@ -304,17 +318,21 @@ platforms.
    
     64-bit MacOSX
     {@code -system=darwin-x86_64}
   
+  
+    64-bit Windows
+    {@code -system=windows-x86_64}
+  
 
 
-For more information on specifying a 32- or 64-bit instruction host toolchain, see
-ndk-build.
+For more information on specifying a 64- or 32-bit instruction host toolchain, see
+64-Bit and 32-Bit Toolchains.
 
-
    You may specify {@code stl=stlport} to copy {@code libstlport} instead of the default
+
    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++}.
    
 
-
    Similarly, you can specify {@code -stl=libc++} to copy the LLVM libc++ headers and libraries.
+
    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.
    
 
 
    You can make these settings directly, as in the following example:
    
@@ -337,13 +355,13 @@ copy of a C++ STL library, with working exceptions and RTTI support.
    
 
    Working with Clang
    
 
    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:
 
 
     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
 
    
 
 
    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.
    
 
 
    Invoking Clang
    
-
    In an ARM standalone installation built with {@code llvm-version=3.3}, invoking
+
    In an ARM standalone installation built with {@code llvm-version=3.6}, invoking
 Clang on a Unix system takes the form of a single line. For
 instance:
    
 
 
    -dirname $0 /clang31 -target armv5te-none-linux-androideabi "$@"
+`dirname $0`/clang36 -target armv5te-none-linux-androideabi "$@"
 
    
 
 
    clang++ invokes clang++31 in the same way.
    
@@ -404,7 +422,7 @@ working properly:
    
 
 
@@ -516,7 +534,7 @@ arm-linux-androideabi-g++ .... -lsupc++
 
    C++ STL support
    
 
    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: