Describe standalone toolchain support.
+ provide a tool to make customized Android toolchain installs/packages
+ cleanup arm-linux-androideabi-4.4.3/setup.mk from un-needed definitions
Change-Id: I06bedd402f45fe90c786e1bc8020fedcb5902a73
diff --git a/build/tools/make-standalone-toolchain.sh b/build/tools/make-standalone-toolchain.sh
new file mode 100755
index 0000000..3440bbc
--- /dev/null
+++ b/build/tools/make-standalone-toolchain.sh
@@ -0,0 +1,168 @@
+# Copyright (C) 2010 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Create a standalone toolchain package for Android.
+
+. `dirname $0`/prebuilt-common.sh
+
+PROGRAM_PARAMETERS=""
+PROGRAM_DESCRIPTION=\
+"Generate a customized Android toolchain installation that includes
+a working sysroot. The result is something that can more easily be
+used as a standalone cross-compiler, e.g. to run configure and
+make scripts."
+
+# $1: Source directory
+# $2: Destination directory
+copy_directory () {
+ if [ ! -d "$1" ] ; then
+ dump "Error: Trying to copy from non-existing directory: $1"
+ exit 1
+ fi
+ mkdir -p "$2"
+ if [ $? != 0 ] ; then
+ dump "Error: Could not create target directory: $2"
+ exit 1
+ fi
+ (cd "$1" && tar cf - *) | (tar xpf - -C "$2")
+ if [ $? != 0 ] ; then
+ dump "Error: Could not copy files from '$1' to '$2'"
+ exit 1
+ fi
+}
+
+force_32bit_binaries
+
+# For now, this is the only toolchain that works reliably.
+TOOLCHAIN_NAME=arm-linux-androideabi-4.4.3
+register_var_option "--toolchain=<name>" TOOLCHAIN_NAME "Specify toolchain name"
+
+NDK_DIR=`dirname $0`
+NDK_DIR=`dirname $NDK_DIR`
+NDK_DIR=`dirname $NDK_DIR`
+register_var_option "--ndk-dir=<path>" NDK_DIR "Take source files from NDK at <path>"
+
+SYSTEM=$HOST_TAG
+register_var_option "--system=<name>" SYSTEM "Specify host system"
+
+PACKAGE_DIR=/tmp/ndk
+register_var_option "--package-dir=<path>" PACKAGE_DIR "Place package file in <path>"
+
+INSTALL_DIR=
+register_var_option "--install-dir=<path>" OUT_DIR "Don't create package, install files to <path> instead."
+
+PLATFORM=android-3
+register_var_option "--platform=<name>" PLATFORM "Specify target Android platform/API level."
+
+extract_parameters "$@"
+
+# Check NDK_DIR
+if [ ! -d "$NDK_DIR/build/core" ] ; then
+ echo "Invalid source NDK directory: $NDK_DIR"
+ echo "Please use --ndk-dir=<path> to specify the path of an installed NDK."
+ exit 1
+fi
+
+# Check PLATFORM
+if [ ! -d "$NDK_DIR/platforms/$PLATFORM" ] ; then
+ echo "Invalid platform name: $PLATFORM"
+ echo "Please use --platform=<name> with one of:" `(cd "$NDK_DIR/platforms" && ls)`
+ exit 1
+fi
+
+# Check toolchain name
+TOOLCHAIN_PATH="$NDK_DIR/toolchains/$TOOLCHAIN_NAME"
+if [ ! -d "$TOOLCHAIN_PATH" ] ; then
+ echo "Invalid toolchain name: $TOOLCHAIN_NAME"
+ echo "Please use --toolchain=<name> with the name of a toolchain supported by the source NDK."
+ echo "Try one of: " `(cd "$NDK_DIR/toolchains" && ls)`
+ exit 1
+fi
+
+# Extract architecture from platform name
+case "$TOOLCHAIN_NAME" in
+ arm-*)
+ ARCH=arm
+ ;;
+ x86-*)
+ ARCH=x86
+ ;;
+ *)
+ echo "Unsupported toolchain name: $TOOLCHAIN_NAME"
+ echo "Name must start with arm- or x86- !"
+ exit 1
+ ;;
+esac
+
+# Check that there are any platform files for it!
+(cd $NDK_DIR/platforms && ls -d */arch-${ARCH} >/dev/null 2>&1 )
+if [ $? != 0 ] ; then
+ echo "Platform $PLATFORM doesn't have any files for this architecture: $ARCH"
+ echo "Either use --platform=<name> or --toolchain=<name> to select a different"
+ echo "platform or arch-dependent toolchain name (respectively)!"
+ exit 1
+fi
+
+# Compute source sysroot
+SRC_SYSROOT="$NDK_DIR/platforms/$PLATFORM/arch-$ARCH"
+if [ ! -d "$SRC_SYSROOT" ] ; then
+ echo "No platform files ($PLATFORM) for this architecture: $ARCH"
+ exit 1
+fi
+
+# Check that we have any prebuilts here
+if [ ! -d "$TOOLCHAIN_PATH/prebuilt" ] ; then
+ echo "Toolchain is missing prebuilt files: $TOOLCHAIN_NAME"
+ echo "You must point to a valid NDK release package!"
+ exit 1
+fi
+
+if [ ! -d "$TOOLCHAIN_PATH/prebuilt/$SYSTEM" ] ; then
+ echo "Host system '$SYSTEM' is not supported by the source NDK!"
+ echo "Try --system=<name> with one of: " `(cd $TOOLCHAIN_PATH/prebuilt && ls) | grep -v gdbserver`
+ exit 1
+fi
+
+TOOLCHAIN_PATH="$TOOLCHAIN_PATH/prebuilt/$SYSTEM"
+
+# Create temporary directory
+TMPDIR=`random_temp_directory`/$TOOLCHAIN_NAME
+
+dump "Copying prebuilt binaries..."
+# Now copy the toolchain prebuilt binaries
+run copy_directory "$TOOLCHAIN_PATH" "$TMPDIR"
+
+dump "Copying sysroot headers and libraries..."
+# Copy the sysroot under $TMPDIR/sysroot. The toolchain was built to
+# expect the sysroot files to be placed there!
+run copy_directory "$SRC_SYSROOT" "$TMPDIR/sysroot"
+
+# Install or Package
+if [ -n "$INSTALL_DIR" ] ; then
+ dump "Copying files to: $INSTALL_DIR"
+ run copy_directory "$TMPDIR" "$INSTALL_DIR"
+else
+ PACKAGE_FILE="$PACKAGE_DIR/$TOOLCHAIN_NAME.tar.bz2"
+ dump "Creating package file: $PACKAGE_FILE"
+ (cd "`dirname $TMPDIR`" && run tar cjf "$PACKAGE_FILE" "$TOOLCHAIN_NAME")
+ if [ $? != 0 ] ; then
+ dump "Error: Could not create tarball from $TMPDIR"
+ exit 1
+ fi
+fi
+dump "Cleaning up..."
+run rm -rf $TMPDIR
+
+dump "Done."
diff --git a/docs/CHANGES.TXT b/docs/CHANGES.TXT
index d48ccb8..127782e 100644
--- a/docs/CHANGES.TXT
+++ b/docs/CHANGES.TXT
@@ -116,11 +116,20 @@
LOCAL_FILTER_ASM in docs/ANDROID-MK.TXT for more details. This can be useful
for certain kinds of obfuscation tasks.
-- Switched to GCC 4.4.3. The binaries for GCC 4.4.0 are still available and
- can be used with NDK_TOOLCHAIN=arm-eabi-4.4.0 defined in your environment.
- The binaries and support files for arm-eabi-4.2.1 were removed.
+- This NDK comes with a new toolchain (named arm-linux-androideabi-4.4.3)
+ which provides many benefits, including:
- IMPORTANT: The new toolchain is called arm-linux-androideabi-4.4.3
+ - Better code generation than the previous one (gcc-4.4.0)
+ - On Windows, the binaries do not depend on Cygwin anymore.
+ - The ability to use it as a stand-alone cross-compiler
+ (see docs/STANDALONE-TOOLCHAIN.TXT for all details).
+
+ The binaries for gcc-4.4.0 are still provided for backwards compatibility.
+ Use NDK_TOOLCHAIN=arm-eabi-4.4.0 in your environment to force its usage.
+ Note that it is now deprecated and will be removed in a future NDK release.
+
+ The binaries for the already-deprecated gcc-4.2.1 have been removed.
+
- The 'cpufeatures' library has been updated to provide better architecture
and features detection (including a work-around for buggy ARMv6 kernels
diff --git a/docs/STANDALONE-TOOLCHAIN.TXT b/docs/STANDALONE-TOOLCHAIN.TXT
new file mode 100644
index 0000000..cddb1ca
--- /dev/null
+++ b/docs/STANDALONE-TOOLCHAIN.TXT
@@ -0,0 +1,175 @@
+ 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.TXT, 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 targetting 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 targetting 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 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.TXT) 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 & 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 and RTTI:
+- - - - - - - - - - - - -
+
+The toolchain binaries currently do *not* support C++ exceptions and RTTI.
+Support for these features is planned for a future NDK release.
diff --git a/toolchains/arm-linux-androideabi-4.4.3/setup.mk b/toolchains/arm-linux-androideabi-4.4.3/setup.mk
index a4ba245..052253d 100644
--- a/toolchains/arm-linux-androideabi-4.4.3/setup.mk
+++ b/toolchains/arm-linux-androideabi-4.4.3/setup.mk
@@ -25,11 +25,9 @@
TARGET_CFLAGS := \
-fpic \
- -mthumb-interwork \
-ffunction-sections \
-funwind-tables \
-fstack-protector \
- -fno-short-enums \
-D__ARM_ARCH_5__ -D__ARM_ARCH_5T__ \
-D__ARM_ARCH_5E__ -D__ARM_ARCH_5TE__ \
