check in build scripts for prebuilt toolchains in Eclair.
[android/toolchain/build.git] / README
1 This is the top-level of the new Android GNU toolchain.  It is designed so
2 that tools in the GNU toolchain and their different versions can be
3 dropped into the Androind toolchain easily.
4
5 1. Supported platforms.
6
7 The Android tool-chain supports the following hosts:
8
9    a. i686-linux-gnu            (32-bit x86 Linux)
10    b. x86_64-linux-gnu          (64-bit x86 Linux)
11    c. i686-apple-darwin*        (OS X 10.4 and 10.5)
12
13 The Android toolchain supports the following targets:
14
15    a. arm-eabi
16    b. arm-newlib-eabi   (for runnng gcc regression tests)
17    c. i[3456]86-*-linux-gnu, x86_64-*-linux-gnu (for x86 targets)
18
19 Currently we are using a modified arm-eabi target for Android.  To facilitate
20 integrating our changes back to the FSF code bases for different tools, we
21 may adopt an Android specific target arm-android-eabi some time in the future.
22 The arm-newlib-eabi target is mainly used to run the gcc test suite with the
23 gnu ARM emulator.
24
25 2. Configuring the toolchain
26
27 2.1 Pre-requesites
28
29 You need to have version 4.4 or higher of the 'makeinfo' program that comes
30 from the 'texinfo' package installed on your machine, even if you use
31 --disable-docs.
32
33 Otherwise the build will later fail with a 'makeinfo is missing...' style
34 message.
35
36 You can get it by simply installing the 'texinfo' package with your favorite
37 package manager, or from its sources.
38
39 2.2 General Information
40
41 The top-level configure file accepts the usual configure options supported
42 by GNU autoconf generated configure file. In addition it supports the
43 following options:
44
45   --with-gcc-version=<gcc version>
46   --with-binutils-version=<binutul version>
47   --with-newlib-version=<newlib version>
48   --with-gmp-version=<gmp version>
49   --with-mpfr-version=<mpfr version>
50   --with-gdb-version=<gdb version>
51
52 These are used to select the desired version of a particular GNU tool
53 package.  If these options are not used during top-level configuring,
54 approriate default values will be used.
55
56 For any --with-XXX-version=YYY, a sub-directory called XXX-YYY must be
57 present in the source level directory.  For example,
58
59         --with-gcc-version=4.3.1
60
61 requires that gcc-4.3.1-android to be present and contain the source code
62 of a buildable gcc version.
63
64 To build the default arm-eabi toolchain, use the following configure options:
65
66 mkdir <toolchain object directory>
67 cd <toolchain object directory>
68 <source directory>/configure --target=arm-eabi \
69         --prefix=<toolchain install directory> \
70
71 2.3 Building a standalone toolchain.
72
73 The default is building a barebone toolchain for the Android device tree. 
74 the barebone toolchain just have binutils, gcc, and gdb.  There are not
75 target C library.  This is not convenient to use for application development.
76 It is possible to build a standalone toolchain with pre-built libraries and
77 headers.
78
79 To build a standalone toolchain, we need a set of pre-compile libraries and
80 associated headers.  There are two ways to do that.  One way is to assemble a
81 sysroot with both the library and headers.  Then when configuring the
82 toolchain add --with-sysroot=<path to sysroot>.  The toolchain expects all
83 headers and libraries to be in <sysroot>/usr/include and <sysroot>/usr/lib
84 respectively.  When using a sysroot, the toolchain remembers where to find the
85 target headers and libraries.  Note that make install will not copy the
86 headers and libraries from sysroot.
87
88 The script build-sysroot.sh can be used to assemble a simple sysroot from
89 an Android device tree.
90
91 The other way is to specify the headers and libraries with --with-headers and
92 --with-libs sperately.  If you configure your tree with a prefix.  The headers
93 and libraries will be copied to the install directory specified by the prefix.
94
95 After installation, we need to remove those installed headers in
96 <prefix dir>/lib/gcc/arm-eabi/*/include-fixed/, if the headers already exist
97 in the android tree. The script clear-header.sh can be used to identify and
98 remove these installed headers.
99
100 2.4 Enabling libstdc++-v3
101
102 For space saving, we do not provide libstdc++-v3 in the toolchain by default.
103 It is possible too build libstdc++-v3.  The enable it, add
104
105         --enable-libstdc__-v3
106
107 when configuring the toolchain.  The C++ library requires a working C library,
108 so you must provide a pre-compiled copy of Bionic with either --with-sysroot
109 or --with-headers and --with-libs.
110
111 2.5 Enabling shared run-time libraries.
112
113 By default, we disable shared run-time libraries.  We can also build shared
114 version of libgcc and libstdc++ by adding
115
116         --enable-shared
117
118 when configuring the toolchain.  Currently the shared libraries are not
119 used in Android and we do not provide them in the system image.  If you build
120 a toolchain with shared libraries and compile applications using them, you
121 must provide these libraries in some place where the Android dynamic linker
122 can find it.
123
124 2.6 OSX 10.5 caveats
125
126 If you build the toolchain on a system running OS X 10.5 with Xcode 3.0, the
127 resultant binaries will not be runnable on Macs running older OS X.  To enforce
128 compatibility with 10.4, defile the environment variables CC and LDFLAGS
129 as follows:
130
131 CC="gcc -isystem /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
132 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk"
133 export CC LDFLAGS
134 <run configure>
135
136 If your 10.4 SDK is not installed at /Developer/SDKs/MacOSX10.4u.sdk, please
137 adjust the values of CC and LDFLAGS appropriately.  The top-level configure
138 script currently does not support passing CC and LDFLAGS as configure options
139 yet so they need to be passed as exported shell variables.
140
141 3. Building and Installing the toolchain
142
143 After configuring the toolchain, simply use "make".  The top-level Makefile
144 in an object directory supports these targets:
145
146         make build (default)
147         make install
148         make clean
149
150 "make install" installs the toolchain in the location specified by
151 --prefix configure option.  The installation location can also be overridden
152 by "make prefix=<install location> install".
153
154 4 Running the compiler testsuite
155
156 It is possible to run the dejagnu compiler testsuite.  To do that, you need
157 a working C library.  This can be done easily by preparing a sysroot and
158 configuring the toolchain like:
159
160 configure --with-sysroot=<your sysroot> .. <other config options>
161
162 After configuring the toolchain, build it as normal.  
163
164 Before running the test, you need to have an adb connected device available.
165 This can be either an emulator or an actual device.  Make sure that adb
166 is in the path of the shell running testsuite and there is a device.  You can
167 check all connected devices using "adb devices".   
168
169 Then go to the gcc object directory and run the tests:
170
171 cd gcc-<version>/gcc
172 EXPORT DEJAGNU=<toolchain source>/build/dejagnu/android-dejagnu.exp
173 make check
174
175 You may want to run a small subset of the testsuite first to verify your
176 set-up.  For example, you can just run the IEEE tests in the gcc testsuite by:
177
178 make check-gcc RUNTESTFLAGS="ieee.exp"
179
180 If you have more than one device connected to adb, you can use the environment
181 variable ADB_SERIAL to specify a device.  For example:
182
183 make check ADB_SERIAL=HT832GZ12345  # a real phone
184 make check ADB_SERIAL=emulator-5554 # an emulator
185
186 If ADB_SERIAL is not empty, all adb commands use -s <serial> to select
187 the appropriate device.
188
189 Sometimes, you may run into a problem with a read-only file system.  When that
190 happens, try "adb remount".  If that fails also, try "adb root" first and
191 then "adb remount".
192
193 Currently, the C++ testsuite is not fully supported.  Android by default
194 does not support exceptions and RTTI and has a very limited C++ run-time
195 library.  So we do not expect passing even a significant portion of C++
196 testsuite.  The C testsuite should work fine with Bionic.
197