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