1 <html><body><pre>USING THE ANDROID TOOLCHAIN AS A STANDALONE COMPILER 2 ====================================================== 3 4 It is now possible to use the toolchains provided with the Android NDK as 5 standalone compilers. This can be useful if you already have your own build 6 system, and only need to ability to invoke the cross-compiler to add support 7 to Android for it. 8 9 A typical use case if invoking the 'configure' script of an open-source 10 library that expects a cross-compiler in the CC environment variable. 11 12 13 This document explains how to do that: 14 15 1/ Selecting your toolchain: 16 ---------------------------- 17 18 Before anything else, you need to decide whether your standalone toolchain 19 is going to target ARM-based devices, or x86-based one. Each architecture 20 corresponds to a different toolchain name: 21 22 * arm-linux-androideabi-4.4.3 => targetting ARM-based Android devices 23 * x86-4.4.3 => targetting x86-based Android devices 24 25 2/ Selecting your sysroot: 26 -------------------------- 27 28 The second thing you need to know is which Android native API level you want 29 to target. Each one of them provides a different various APIs, which are 30 documented under doc/STABLE-APIS.html, and correspond to the sub-directories 31 of $NDK/platforms. 32 33 This allows you to define the path to your 'sysroot', a GCC term for a 34 directory containing the system headers and libraries of your target. 35 Usually, this will be something like: 36 37 SYSROOT=$NDK/platforms/android-<level>/arch-<arch>/ 38 39 Where <level> is the API level number, and <arch> is the architecture 40 ("arm" and "x86" are the supported values). For example, if you're targeting 41 Android 2.2 (a.k.a. Froyo), you would use: 42 43 SYSROOT=$NDK/platforms/android-8/arch-arm 44 45 IMPORTANT: Note that only android-9 is supported for the x86 architecture. 46 47 2/ Invoking the compiler (the hard way): 48 ---------------------------------------- 49 50 Invoke the compiler using the --sysroot option to indicate where the system 51 files for the platform you're targeting are located. For example, do: 52 53 export CC="$NDK/toolchains/<name>/prebuilt/<system>/bin/<prefix>gcc --sysroot=$SYSROOT" 54 $CC -o foo.o -c foo.c 55 56 Where <name> is the toolchain's name, <system> is the host tag for your system, 57 and <prefix> is a toolchain-specific prefix. For example, if you are on Linux 58 using the NDK r5 toolchain, you would use: 59 60 export CC="$NDK/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc --sysroot=$SYSROOT" 61 62 As you can see, this is rather verbose, but it works! 63 64 IMPORTANT NOTE: 65 66 Using the NDK toolchain directly has a serious limitation: 67 You won't be able to use any C++ STL (either STLport or 68 the GNU libstdc++) with it. Also no exceptions and no RTTI. 69 70 71 3/ Invoking the compiler (the easy way): 72 ---------------------------------------- 73 74 The NDK allows you to create a "customized" toolchain installation to make 75 life easier. For example, consider the following command: 76 77 $NDK/build/tools/make-standalone-toolchain.sh --platform=android-5 --install-dir=/tmp/my-android-toolchain 78 79 This will create a directory named /tmp/my-android-toolchain containing a 80 copy of the android-5/arch-arm sysroot, and of the toolchain binaries. 81 82 Note that by default, the ARM-based toolchain will be selected by the script. 83 Use the '--arch=x86' option to specify the x86-based one, or alternatively 84 '--toolchain=<name>'. 85 86 You can later use it directly with something like: 87 88 export PATH=/tmp/my-android-toolchain/bin:$PATH 89 export CC=arm-linux-androideabi-gcc 90 91 Note that without the --install-dir option, make-standalone-toolchain.sh will 92 create a tarball in /tmp/ndk/<toolchain-name>.tar.bz2. This allows you to 93 archive and redistribute the binaries easily. 94 95 Another important benefit is that this standalone toolchain will contain a 96 working copy of the GNU libstdc++, with working exceptions and RTTI support 97 (as long as you link against libstdc++ or libsupc++) 98 99 Use --help for more options and details. 100 101 IMPORTANT: The toolchain binaries do not depend or contain host-specific paths, 102 in other words, they can be installed in any location, or even 103 moved if you need to. 104 105 NOTE: You can still use the --sysroot option with the new toolchain, but it 106 is now simply optional! 107 108 109 4/ ABI Compatibility: 110 --------------------- 111 112 The machine code generated by the ARM toolchain should be compatible with 113 the official Android 'armeabi' ABI (see docs/CPU-ARCH-ABIS.html) by default. 114 115 It is recommended to use the -mthumb compiler flag to force the generation 116 of 16-bit Thumb-1 instructions (the default being 32-bit ARM ones). 117 118 If you want to target the 'armeabi-v7a' ABI, you will need ensure that the 119 following two flags are being used: 120 121 CFLAGS='-march=armv7-a -mfloat-abi=softfp' 122 123 Note: The first flag enables Thumb-2 instructions, and the second one 124 enables H/W FPU instructions while ensuring that floating-point 125 parameters are passed in core registers, which is critical for 126 ABI compatibility. Do *not* use these flags separately! 127 128 If you want to use Neon instructions, you will need one more compiler flag: 129 130 CFLAGS='-march=armv7-a -mfloat-abi=softfp -mfpu=neon' 131 132 Note that this forces the use of VFPv3-D32, as per the ARM specification. 133 134 Also, is is *required* to use the following linker flags that routes around 135 a CPU bug in some Cortex-A8 implementations: 136 137 LDFLAGS='-Wl,--fix-cortex-a8' 138 139 If none of the above makes sense to you, it's probably better not to use 140 the standalone toolchain, and stick to the NDK build system instead, which 141 will handle all the details for you. 142 143 You don't have to use any specific compiler flag when targetting the x86 ABI. 144 145 5/ Warnings and Limitations: 146 -------------------------- 147 148 5.1/ Windows support: 149 - - - - - - - - - - - 150 151 The Windows binaries do *not* depend on Cygwin. The good news is that they 152 are thus faster, the bad news is that they do not understand the Cygwin 153 path specification like /cygdrive/c/foo/bar (instead of C:/foo/bar). 154 155 The NDK build system ensures that all paths passed to the compiler from Cygwin 156 are automatically translated, and deals with other horrors for you. If you have 157 a custom build system, you may need to deal with the problem yourself. 158 159 NOTE: There is no plan to support Cygwin / MSys at the moment, but 160 contributions are welcome. Contact the android-ndk forum for details. 161 162 163 5.2/ wchar_t support: 164 - - - - - - - - - - - 165 166 As documented, the Android platform did not really support wchar_t until 167 Android 2.3. What this means in practical terms is that: 168 169 - If you target platform android-9 or higher, the size of wchar_t is 170 4 bytes, and most wide-char functions are available in the C library 171 (with the exception of multi-byte encoding/decoding functions and 172 wsprintf/wsscanf). 173 174 - If you target any prior API level, the size of wchar_t will be 1 byte 175 and none of the wide-char functions will work anyway. 176 177 We recommend any developer to get rid of any dependencies on the wchar_t type 178 and switch to better representations. The support provided in Android is only 179 there to help you migrate existing code. 180 181 182 5.3/ Exceptions, RTTI and STL: 183 - - - - - - - - - - - - - - - 184 185 The toolchain binaries *do* support C++ exceptions and RTTI by default. 186 They are enabled by default, so use -fno-exceptions and -fno-rtti if you 187 want to disable them when building sources with them (e.g. to generate 188 smaller machine code). 189 190 NOTE: You will need to explicitly link with libsupc++ if you use these 191 features. To do this, use -lsupc++ when linking binaries, as in: 192 193 arm-linux-androideabi-g++ .... -lsupc++ 194 195 196 The toolchain also comes with a working GNU libstdc++ implementation, which 197 provides a working C++ Standard Template Library implementation. You will 198 need to explicitly link against -lstdc++ to use it. 199 200 Proper toolchain configuration to avoid these explicit link flags is 201 planned for the future. 202 203 </pre></body></html>
