    USING THE ANDROID TOOLCHAIN AS A STANDALONE COMPILER
           ======================================================

       WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
       WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING

                SUPPORT FOR THIS FEATURE IS STILL IN BETA
              AND ONLY APPLIES TO arm-linux-androideabi-4.4.3

            IF YOU ENCOUNTER A PROBLEM WITH THE METHODS DESCRIBED
                 HERE, PLEASE CONTACT THE SUPPORT FORUM AT

                         android-ndk@googlegroups.com

       WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
       WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING

    It is now possible to use the toolchain provided with the Android NDK as a
    standalone compiler. 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.

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

    This document explains how to do that:

    1/ Selecting your sysroot:
    --------------------------

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

    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=$NDK/platforms/android-<level>/arch-<arch>/

    Where <level> is the API level number, and <arch> is the architecture ("arm"
    being currently supported). For example, if you're targeting Android 2.1
    (a.k.a. Froyo), you would use:

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

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

        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:

        export CC="$NDK/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc --sysroot=$SYSROOT"

    As you can see, this is rather verbose, but it works!

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

    You can later use it directly with something like:

       export PATH=/tmp/my-android-toolchain/bin:$PATH
       export CC=arm-linux-androideabi-gcc

    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.

    Use --help for more options and details.

    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!

    4/ ABI Compatibility:
    ---------------------

    The machine code generated by the toolchain should be compatible with
    the official Android 'armeabi' ABI (see docs/CPU-ARCH-ABIS.html) by default.

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

    If you want to target the 'armeabi-v7a' ABI, you will need ensure that the
    following two flags are being used:

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

    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!

    If you want to use Neon instructions, you will need one more compiler flag:

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

    Note that this forces the use of VFPv3-D32, as per the ARM specification.

    Also, is is *required* to use the following linker flags that routes around
    a CPU bug in some Cortex-A8 implementations:

      LDFLAGS='-Wl,--fix-cortex-a8'

    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.

    5/ Warnings and Limitations:
    --------------------------

    5.1/ Windows support:
    - - - - - - - - - - -

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

    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.

    NOTE: There is no plan to support Cygwin / MSys at the moment, but
          contributions are welcome. Contact the android-ndk forum for details.

    5.2/ wchar_t support:
    - - - - - - - - - - -

    As documented, the Android platform did not really support wchar_t until
    Android 2.3. What this means in practical terms is that:

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

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

    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.

    5.3/ Exceptions, RTTI and 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).

    NOTE: You will need to explicitly link with libsupc++ if you use these
          features. To do this, use -lsupc++ when linking binaries, as in:

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

    The toolchain also comes with a working GNU libstdc++ implementation, which
    provides a working C++ Standard Template Library implementation. You will
    need to explicitly link against -lstdc++ to use it.

    Proper toolchain configuration to avoid these explicit link flags is
    planned for the future.