#android-ndk-r8d 使用 独立 编译 工具链 官方文档 中英文 对照

USING THE ANDROID TOOLCHAIN AS A STANDALONE COMPILER
使用ANDROID作为一个独立的编译器工具链
======================================================

It is now possible to use the toolchains provided with the Android NDK as
standalone compilers. This can be useful if you already have your own build
system, and only need to ability to invoke the cross-compiler to add support
to Android for it.

现在可以使用Android NDK 作为独立编译器。如果你拥有自己的编译系统这会很有用

，仅仅需要有调用支持Android交叉编译器的能力。

 

A typical use case if invoking the 'configure' script of an open-source
library that expects a cross-compiler in the CC environment variable.

一个典型用例，如果调用需要交叉编译器调用开源库'configure'脚本（预设CC环境变量）。

This document explains how to do that:
该文档解释了如何做:

1/ Selecting your toolchain:
选择你的工具链:
----------------------------

Before anything else, you need to decide whether your standalone toolchain
is going to target ARM-based devices, x86-based, or MIPS-based one.
Each architecture corresponds to a different toolchain name.  For example:
做任何东西之前,你需要决定你的独立的工具链是基于arm的设备,基于x86的,或基于mips的哪一个。
每个架构对应一个不同的工具链的名字。例如:

  * arm-linux-androideabi-4.6   => targeting ARM-based Android devices
  * x86-4.6                     => targeting x86-based Android devices
  * mipsel-linux-android-4.6    => targeting MIPS-based Android devices

2/ Selecting your sysroot:
选择目录切换为sysroot:
--------------------------

The second thing you need to know is which Android native API level you want
to target. Each one of them provides a different various APIs, which are
documented under doc/STABLE-APIS.html, and correspond to the sub-directories
of $NDK/platforms.
第二件事你需要知道的是,你需要知道安卓原生API的级别。每一个都提供了一个不同的各种api,
这是记录在doc/STABLE-APIS.html和对应 $NDK/platforms的子目录中

This allows you to define the path to your 'sysroot', a GCC term for a
directory containing the system headers and libraries of your target.
Usually, this will be something like:
定义'sysroot'包含目标系统头文件和库。通常，如下：
   SYSROOT=$NDK/platforms/android-<level>/arch-<arch>/

Where <level> is the API level number, and <arch> is the architecture
("arm", "x86", and "mips" are the supported values). For example, if you're
targeting Android 2.2 (a.k.a. Froyo), you would use:
<level>是API 级别 号，<arch>是架构（支持arm，x86，mips）。

例如：如果目标android是2.2，如下：
   SYSROOT=$NDK/platforms/android-8/arch-arm

IMPORTANT: Note that X86 and MIPS architectures are only supported at android-9 and later.
重要：注意X86和MIPS架构只在android-9或更新支持。
3/ Invoking the compiler (the hard way):
调用编译器（最困难一步）
----------------------------------------

Invoke the compiler using the --sysroot option to indicate where the system
files for the platform you're targeting are located. For example, do:
使用--sysroot选项来指出系统文件位置在哪。例如：
    export CC="$NDK/toolchains/<name>/prebuilt/<system>/bin/<prefix>gcc --sysroot=$SYSROOT"
    $CC -o foo.o -c foo.c

Where <name> is the toolchain's name, <system> is the host tag for your system,
and <prefix> is a toolchain-specific prefix. For example, if you are on Linux
using the NDK r5 toolchain, you would use:
 <name>是工具链的名字，<system>是系统主机标志，<prefix>是工具链特定前缀，例如在linux下使用NDK r5工具链，如下：
    export CC="$NDK/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc --sysroot=$SYSROOT"

As you can see, this is rather verbose, but it works!
可见，这是很繁琐，但是有效！
IMPORTANT NOTE:
重要事项：
    Using the NDK toolchain directly has a serious limitation:
    You won't be able to use any C++ STL (either STLport or
    the GNU libstdc++) with it. Also no exceptions and no RTTI.
  直接使用NDK的工具链（非独立版工具链）有严重的限制：
  你不能使用任何C++ STL（STLport或GNU libstdc++）。也没有异常和运行时类型检查。

4/ Invoking the compiler (the easy way):
调用编译器（最简单一步）：
----------------------------------------

The NDK allows you to create a "customized" toolchain installation to make
life easier. For example, consider the following command:
NDK允许您创建一个“定制”工具链安装。例如,参考下面的命令:
  $NDK/build/tools/make-standalone-toolchain.sh --platform=android-5 --install-dir=/tmp/my-android-toolchain

This will create a directory named /tmp/my-android-toolchain containing a
copy of the android-5/arch-arm sysroot, and of the toolchain binaries.
这将建立一个路径/tmp/my-android-toolchain，包含复制的 android-5/arch-arm sysroot 工具链 文件。

Note that by default, the ARM-based GCC 4.6 toolchain will be selected by the script.
Use the '--arch=x86' option to specify the x86 GCC 4.6, or add '--arch=mips' option
to specify the MIPS GCC 4.6, or alternatively
'--toolchain=<name>'.  For example:
注意默认使用ARM GCC 4.6 工具链。使用'--arch=x86'设定x86 GCC 4.6，

或'--arch=mips'设定MIPS GCC 4.6，或者'--toolchain=<name>'来设。例如

  --toolchain=x86-4.4.3                  # select x86 GCC 4.4.3 compiler
  --toolchain=arm-linux-androideabi-4.7  # select ARM GCC 4.7 compiler
  --toolchain=mipsel-linux-android-4.6   # select MIPS GCC 4.6 compiler, same as --arch=mips

If you wish, add '--llvm-version=3.1' to also copy clang/llvm 3.1, or
use --toolchain with '-clang3.1' suffix.  For example:
'--llvm-version=3.1'可以复制clang/llvm 3.1或使用--toolchain with '-clang3.1'后缀，例如：

  --toolchain=arm-linux-androideabi-clang3.1  # same as --arch=arm --llvm-version=3.1

You can later use it directly with something like:
稍后可用类似如下（导入环境变量）：

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

Note that without the --install-dir option, make-standalone-toolchain.sh will
create a tarball in /tmp/ndk/<toolchain-name>.tar.bz2. This allows you to
archive and redistribute the binaries easily.
注意未使用--install-dir，make-standalone-toolchain.sh会打包在/tmp/ndk/<toolchain-name>.tar.bz2。
使你可以很容易重新发布文件。

Another important benefit is that this standalone toolchain will contain a
working copy of the GNU libstdc++, with working exceptions and RTTI support
(as long as you link against libstdc++ or libsupc++)
另一个很便利的地方：独立工具链包含GNU libstdc++（支持异常和RTTI机制），只要你链接到它。

Use --help for more options and details.
--help查看更多选项和信息。

IMPORTANT: The toolchain binaries do not depend or contain host-specific paths,
           in other words, they can be installed in any location, or even
           moved if you need to.
重要:工具链的二进制文件不依赖或包含特定于主机的路径,
 　　换句话说,他们可以安装在任何位置,甚至如果你需要移动。
 
NOTE: You can still use the --sysroot option with the new toolchain, but it
      is now simply optional!
注意:你仍然可以使用--sysroot选项在新的工具链,但它现在只是可选的!

5/ About Clang
关于Clang
---------------------

Clang/clang++ uses the same assembler, linker, headers, libraries and GNU
libstdc++ in the same standalone package.  Clang/clang++ are actually scripts
with "-target" set to the specified architecture at creation.  For example, in
ARM standalone package, clang is a one-liner:
Clang/clang++使用同样的编译器，链接器，头文件，库文件和GNU libstdc++在独立的包中。
Clang/clang++是个脚本，创建时使用-target指定到特定架构。
例如：在ARM独立包，clang是个单行：

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

clang++ is another:
clang++是另一行：

   `dirname $0`/clang++31 -target armv5te-none-linux-androideabi "$@"

Note that for arm, clang will change target based on the presence of
subsequent option "-march=armv7-a" and/or "-mthumb".  ie.
注意arm，使用-march=armv7-a -mthumb clang将改变-target

  1/ With "-march=armv7-a", -target becomes armv7-none-linux-androideabi
  2/ With "-mthumb", -target becomes thumb-none-linux-androideabi
  3/ With both, -target becomes thumbv7-none-linux-androideabi

You may override with your own -target if you wish.
你可以重写-target。

Extra efforts have been made to make clang/clang++ easier drop-in
replacements for gcc/g++ in Makefile.  When in doubt, use the following
common techniques to check:

做额外的工作替换gcc/g++在Makefile里。怀疑时，使用下面检查：

  1/ Add option "-v" to dump commands compiler driver issues
    -v打印命令编译器驱动问题
  2/ Add option "-###" to dump command line options, including those
     implicitly predefined.
    -### 打印选项命令行，包含隐式预定义的
  3/ Use "-x c /dev/null -dM -E" to dump predefined preprocessor definitions
   - x c /dev/null -dM -E 打印预定义的预处理器定义
  4/ Add option "-save-temps" and compare the preprocessed files *.i or *.ii
  -save-temps比较预处理文件 *.i *.ii

See http://clang.llvm.org/, especially the GCC compatibility section.

6/ ABI Compatibility:
应用二进制接口兼容性：
---------------------

The machine code generated by the ARM toolchain should be compatible with
the official Android 'armeabi' ABI (see docs/CPU-ARCH-ABIS.html) by default.
ARM工具链生成的代码应该默认兼容官方Android 'armeabi'的应用二进制接口(参照/CPU-ARCH-ABIS.html)

It is recommended to use the -mthumb compiler flag to force the generation
of 16-bit Thumb-1 instructions (the default being 32-bit ARM ones).
推荐使用-mthumb 编译器标识来强制生成16位Thumb-1指令（默认是32位ARM的指令）

If you want to target the 'armeabi-v7a' ABI, you will need ensure that the
following flags are being used:
如果你的目标是'armeabi-v7a'的应用二进制接口，你需要确保使用如下标志：

  CFLAGS='-march=armv7-a -mfloat-abi=softfp -mfpu=vfpv3-d16'

Note: The first flag enables Thumb-2 instructions, and the second one
      enables H/W FPU instructions while ensuring that floating-point
      parameters are passed in core registers, which is critical for
      ABI compatibility. Do *not* use these flags separately!
注意：第一个标志启用Thumb-2指令，第二个启用H/W浮点处理器指令功能，
确保用核心寄存器传递浮点参数，它对于ABI兼容性来说是关键。不要分开使用这些开关！

If you want to use Neon instructions, you will need to change the -mfpu
compiler flag:
如果你想使用Neon指令（ARM的单指令多数据技术），你需要再增多一个编译器开关：

  CFLAGS='-march=armv7-a -mfloat-abi=softfp -mfpu=neon'

Note that this forces the use of VFPv3-D32, as per the ARM specification.
注意它强制使用VFPv3-D32（注：VFPv3是vector floating point v3的缩写，
即向量浮点第三版，D32应该是指32个双精度浮点寄存器），根据ARM规范。

Also, make sure the following two flags are provided to linker:
还有，确保下链接器使用以下两个标志。

  LDFLAGS='-march=armv7-a -Wl,--fix-cortex-a8'

Note: The first flag instructs linker to pick libgcc.a, libgcov.a and
      crt*.o tailored for armv7-a.  The 2nd flag is *required* to route
      around a CPU bug in some Cortex-A8 implementations:
注意：第一个标志连接器选择特别为armv7-a设计的libgcc.a libgcov.a和crt*.o。
      第二个标志是绕过一些Cortex-A8 CPU bug的实现所需。

If none of the above makes sense to you, it's probably better not to use
the standalone toolchain, and stick to the NDK build system instead, which
will handle all the details for you.
如果上面的东西对你不起作用，最好不要使用独立工具链，还是坚持使用NDK构建系统，
它将为你处理所有细节。

You don't have to use any specific compiler flag when targeting the x86 ABI
or the MIPS ABI.
当目标是x86 ABI或MIPS ABI时，你不需要使用人任何特殊编译器标志。

7/ Warnings and Limitations:
警告和限制：
--------------------------

7.1/ Windows support:
Windows支持：
- - - - - - - - - - -

The Windows binaries do *not* depend on Cygwin. The good news is that they
are thus faster, the bad news is that they do not understand the Cygwin
path specification like /cygdrive/c/foo/bar (instead of C:/foo/bar).
Windows二进制文件不依赖于Cygwin。好消息是它们会跑得更快，
而坏消息是它们不理解Cygwin的目录格式，像/cygdrive/c/foo/bar（但可以理解C:/foo/bar）

The NDK build system ensures that all paths passed to the compiler from Cygwin
are automatically translated, and deals with other horrors for you. If you have
a custom build system, you may need to deal with the problem yourself.
NDK构建系统确保从Cygwin中传递的所有路径被自动翻译，为你处理其它威胁。
如果你拥有一个定制构建系统，你可能需要自己处理问题。

NOTE: There is no plan to support Cygwin / MSys at the moment, but
      contributions are welcome. Contact the android-ndk forum for details.
注意：现在没计划支持Cygwin / MSys，但欢迎贡献。详细请联系android-ndk论坛

7.2/ wchar_t support:
wchar_t支持：
- - - - - - - - - - -

As documented, the Android platform did not really support wchar_t until
Android 2.3. What this means in practical terms is that:
正如文档所写的，Android平台在Android 2.3之前没有真正支持wchar_t。
用实际的术语说，这意味着：
 

  - If you target platform android-9 or higher, the size of wchar_t is
    4 bytes, and most wide-char functions are available in the C library
    (with the exception of multi-byte encoding/decoding functions and
     wsprintf/wsscanf).
  - 如果你的目标平台是android-9或更高，wchar_t的大小是4字节，则在C库中大多数
    宽字符函数可用（例外的是多字节的编码解码函数和wsprintf/wsscanf）

  - If you target any prior API level, the size of wchar_t will be 1 byte
    and none of the wide-char functions will work anyway.
  - 如果你的目标是较早的API级别，wchar_t的大小将是1字节，任何宽字符函数都不可工作。

We recommend any developer to get rid of any dependencies on the wchar_t type
and switch to better representations. The support provided in Android is only
there to help you migrate existing code.
我们建议所有开发者避免对wchar_t类型的依赖，而是转向更好的表示。
在Android中提供的支持只出现在帮助你迁移现存代码的地方。

7.3/ Exceptions, RTTI and STL:
异常、运行时类型识别和STL（标准模板库）：
- - - - - - - - - - - - - - -

The toolchain binaries *do* support C++ exceptions and RTTI by default.
They are enabled by default, so use -fno-exceptions and -fno-rtti if you
want to disable them when building sources with them (e.g. to generate
smaller machine code).
工具链二进制文件默认支持C++异常和RTTI（运行时类型识别）。
它们默认是打开的，所以如果你想在构建使用它们的代码时关闭它们，
请使用-fno-exceptions和-fno-rtti（例如，为了生成更小的机器代码）。

NOTE: You will need to explicitly link with libsupc++ if you use these
      features. To do this, use -lsupc++ when linking binaries, as in:
注意：你将需要显式地用libsupc++链接，如果你使用这些特性。
为了做到这点，当链接二进制文件时使用-lsupc++，
像这样：（注：这里要小心，是libsupc++不是libstdc++！）

    arm-linux-androideabi-g++ .... -lsupc++

7.4/ C++ STL support:

C++标准模板库支持：
- - - - - - - - - - -

The standalone toolchain also comes with a copy of the GNU libstdc++
library, which provides an implementation of the C++ Standard Template
Library. To use it, you however need to link with the proper library:
工具链还带有一个可用的GNU libstdc++实现，它提供一个工作的C++标准模板库实现。
你将需要显式地用-lstdc++链接以使用它。

  * Use -lstdc++ to link against the _static_ library version. This ensures
    that all required C++ STL code is included into your final binary. This
    is ideal if you are only generating a single shared library or executable.
    使用-lstdc++ 来链接静态库版本。这确保了所需C++STL代码包含进你的最终二进制文件。
    这是一个生成单独共享库或执行文件的办法。
    This is the recommended way to do it.
    这是推荐的方式。

  * Use -lgnustl_shared to link against the _shared_ library version. This
    is required if you have several related shared libraries or executables
    that need to run in the same address space at runtime (some global variables
    need to be defined uniquely, which is not possible if you link the static
    libstdc++ against each one of your executables).
    使用-lgnustl_shared来链接静态库版本。如果你有几个相关的需要运行时在同样的地址空间
    的共享库或执行文件，这是必须的。
   （一些全局变量需要唯一的定义，不适用于每一个可执行文件链接静态的libstdc++）
   
    If you use this option, you need to ensure that libgnustl_shared.so is
    also copied to your device for your code to load properly. The file is
    at:
    如果你使用此选项，你需要确保libgnustl_shared.so拷贝到你设备上以便载入。文件在：

      $TOOLCHAIN/arm-linux-androideabi/lib/  for ARM toolchains.
      $TOOLCHAIN/i686-linux-android/lib/     for x86 ones.
      $TOOLCHAIN/mipsel-linux-android/lib/   for MIPS toolchains.

    IMPORTANT: The GNU libstdc++ is licensed under the GPLv3 with a
               linking exception. See the following URL for details:
 重要：GNU libstdc++ 授权在GPLv3，有一个例外，查看如下URL来详细描述：
          http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt01ch01s02.html

    If you cannot comply with its requirements, i.e. you cannot redistribute
    the shared library, do not use it in your project.
    如果你不能干遵守它的要求，你不能发布这个共享库，不能使用在你的工程中。

The reason the shared version of GNU libstdc++ is not called libstdc++.so is
because this would conflict at runtime with the system's own minimal C++
runtime, which is /system/lib/libstdc++.so. This enforces a new name for the
GNU ELF library. This is not a problem for the static library.
共享版GNU libstdc++不被叫做libstdc++.so的原因是这将会在运行时和最小C++运行时库
（/system/lib/libstdc++.so）冲突。这强制了一个GNU ELF库的新名字。对于静态库这不是个问题。