f3497065b303d3041814c836b79197a5c26bcfbf
[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-linux-androideabi
16    b. arm-eabi  (for Android kernel)
17    c. arm-newlib-eabi   (for runnng gcc regression tests)
18    d. i[3456]86-*-linux-gnu, x86_64-*-linux-gnu (for x86 targets)
19
20 Currently we are using arm-linux-androideabi target for general Android use.
21 This target is already in gcc upstream. arm-eabi target is only used to
22 compile Android kernel. The arm-newlib-eabi target is mainly used to run
23 the gcc test suite with the 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-mpc-version=<mpc version>
51   --with-gdb-version=<gdb version>
52
53 These are used to select the desired version of a particular GNU tool
54 package.  If these options are not used during top-level configuring,
55 approriate default values will be used.
56
57 For any --with-XXX-version=YYY, a sub-directory called XXX-YYY must be
58 present in the source level directory.  For example,
59
60         --with-gcc-version=4.3.1
61
62 requires that gcc-4.3.1-android to be present and contain the source code
63 of a buildable gcc version.
64
65 To build the default arm-eabi toolchain, use the following configure options:
66
67 mkdir <toolchain object directory>
68 cd <toolchain object directory>
69 <source directory>/configure --target=arm-eabi \
70         --prefix=<toolchain install directory> \
71
72 2.3 Building a standalone toolchain.
73
74 The default is building a barebone toolchain for the Android device tree. 
75 the barebone toolchain just have binutils, gcc, and gdb.  There are not
76 target C library.  This is not convenient to use for application development.
77 It is possible to build a standalone toolchain with pre-built libraries and
78 headers.
79
80 To build a standalone toolchain, we need a set of pre-compile libraries and
81 associated headers.  There are two ways to do that.  One way is to assemble a
82 sysroot with both the library and headers.  Then when configuring the
83 toolchain add --with-sysroot=<path to sysroot>.  The toolchain expects all
84 headers and libraries to be in <sysroot>/usr/include and <sysroot>/usr/lib
85 respectively.  When using a sysroot, the toolchain remembers where to find the
86 target headers and libraries.  Note that make install will not copy the
87 headers and libraries from sysroot.
88
89 The script build-sysroot.sh can be used to assemble a simple sysroot from
90 an Android device tree.
91
92 The other way is to specify the headers and libraries with --with-headers and
93 --with-libs sperately.  If you configure your tree with a prefix.  The headers
94 and libraries will be copied to the install directory specified by the prefix.
95
96 After installation, we need to remove those installed headers in
97 <prefix dir>/lib/gcc/arm-eabi/*/include-fixed/, if the headers already exist
98 in the android tree. The script clear-header.sh can be used to identify and
99 remove these installed headers.
100
101 2.4 Enabling libstdc++-v3
102
103 For space saving, we do not provide libstdc++-v3 in the toolchain by default.
104 It is possible too build libstdc++-v3. To enable it, do
105
106         export CFLAGS_FOR_TARGET=-fexceptions
107         export CXXFLAGS_FOR_TARGET=-frtti
108
109 before configuring the toolchain, and add
110
111         --enable-libstdc__-v3
112
113 when configuring the toolchain.  The C++ library requires a working C library,
114 so you must provide a pre-compiled copy of Bionic with either --with-sysroot
115 or --with-headers and --with-libs.
116
117 2.5 Enabling shared run-time libraries.
118
119 By default, we disable shared run-time libraries.  We can also build shared
120 version of libgcc and libstdc++ by adding
121
122         --enable-shared
123
124 when configuring the toolchain.  Currently the shared libraries are not
125 used in Android and we do not provide them in the system image.  If you build
126 a toolchain with shared libraries and compile applications using them, you
127 must provide these libraries in some place where the Android dynamic linker
128 can find it.
129
130 2.6 OSX 10.5 caveats
131
132 If you build the toolchain on a system running OS X 10.5 with Xcode 3.0, the
133 resultant binaries will not be runnable on Macs running older OS X.  To enforce
134 compatibility with 10.4, defile the environment variables CC and LDFLAGS
135 as follows:
136
137 CC="gcc -isystem /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
138 LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk"
139 export CC LDFLAGS
140 <run configure>
141
142 If your 10.4 SDK is not installed at /Developer/SDKs/MacOSX10.4u.sdk, please
143 adjust the values of CC and LDFLAGS appropriately.  The top-level configure
144 script currently does not support passing CC and LDFLAGS as configure options
145 yet so they need to be passed as exported shell variables.
146
147 3. Building and Installing the toolchain
148
149 After configuring the toolchain, simply use "make".  The top-level Makefile
150 in an object directory supports these targets:
151
152         make build (default)
153         make install
154         make clean
155
156 "make install" installs the toolchain in the location specified by
157 --prefix configure option.  The installation location can also be overridden
158 by "make prefix=<install location> install".
159
160 4 Running the compiler testsuite
161
162 It is possible to run the dejagnu compiler testsuite.  To do that, you need
163 a working C library.  This can be done easily by preparing a sysroot and
164 configuring the toolchain like:
165
166 configure --with-sysroot=<your sysroot> .. <other config options>
167
168 After configuring the toolchain, build it as normal.  
169
170 Before running the test, you need to have an adb connected device available.
171 This can be either an emulator or an actual device.  Make sure that adb
172 is in the path of the shell running testsuite and there is a device.  You can
173 check all connected devices using "adb devices".   
174
175 Then go to the gcc object directory and run the tests:
176
177 cd gcc-<version>/gcc
178 EXPORT DEJAGNU=<toolchain source>/build/dejagnu/android-dejagnu.exp
179 make check
180
181 You may want to run a small subset of the testsuite first to verify your
182 set-up.  For example, you can just run the IEEE tests in the gcc testsuite by:
183
184 make check-gcc RUNTESTFLAGS="ieee.exp"
185
186 If you have more than one device connected to adb, you can use the environment
187 variable ADB_SERIAL to specify a device.  For example:
188
189 make check ADB_SERIAL=HT832GZ12345  # a real phone
190 make check ADB_SERIAL=emulator-5554 # an emulator
191
192 If ADB_SERIAL is not empty, all adb commands use -s <serial> to select
193 the appropriate device.
194
195 Sometimes, you may run into a problem with a read-only file system.  When that
196 happens, try "adb remount".  If that fails also, try "adb root" first and
197 then "adb remount".
198
199 Currently, the C++ testsuite is not fully supported.  Android by default
200 does not support exceptions and RTTI and has a very limited C++ run-time
201 library.  So we do not expect passing even a significant portion of C++
202 testsuite.  The C testsuite should work fine with Bionic.
203