yann@1
|
1 |
File.........: overview.txt
|
yann@197
|
2 |
Content......: Overview of how crosstool-NG works.
|
yann@92
|
3 |
Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
|
yann@192
|
4 |
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
|
yann@92
|
5 |
|
yann@1
|
6 |
________________
|
yann@1
|
7 |
/
|
yann@1
|
8 |
Introduction /
|
yann@1
|
9 |
_____________/
|
yann@1
|
10 |
|
yann@1
|
11 |
crosstool-NG aims at building toolchains. Toolchains are an essential component
|
yann@1
|
12 |
in a software development project. It will compile, assemble and link the code
|
yann@1
|
13 |
that is being developped. Some pieces of the toolchain will eventually end up
|
yann@1
|
14 |
in the resulting binary/ies: static libraries are but an example.
|
yann@1
|
15 |
|
yann@1
|
16 |
So, a toolchain is a very sensitive piece of software, as any bug in one of the
|
yann@1
|
17 |
components, or a poorly configured component, can lead to execution problems,
|
yann@1
|
18 |
ranging from poor performance, to applications ending unexpectedly, to
|
yann@1
|
19 |
mis-behaving software (which more than often is hard to detect), to hardware
|
yann@1
|
20 |
damage, or even to human risks (which is more than regretable).
|
yann@1
|
21 |
|
yann@1
|
22 |
Toolchains are made of different piece of software, each being quite complex
|
yann@1
|
23 |
and requiring specially crafted options to build and work seamlessly. This
|
yann@1
|
24 |
is usually not that easy, even in the not-so-trivial case of native toolchains.
|
yann@1
|
25 |
The work reaches a higher degree of complexity when it comes to cross-
|
yann@40
|
26 |
compilation, where it can become quite a nightmare...
|
yann@1
|
27 |
|
yann@40
|
28 |
Some cross-toolchains exist on the internet, and can be used for general
|
yann@1
|
29 |
development, but they have a number of limitations:
|
yann@1
|
30 |
- they can be general purpose, in that they are configured for the majority:
|
yann@1
|
31 |
no optimisation for your specific target,
|
yann@1
|
32 |
- they can be prepared for a specific target and thus are not easy to use,
|
yann@1
|
33 |
nor optimised for, or even supporting your target,
|
yann@1
|
34 |
- they often are using ageing components (compiler, C library, etc...) not
|
yann@1
|
35 |
supporting special features of your shiny new processor;
|
yann@1
|
36 |
On the other side, these toolchain offer some advantages:
|
yann@1
|
37 |
- they are ready to use and quite easy to install and setup,
|
yann@1
|
38 |
- they are proven if used by a wide community.
|
yann@1
|
39 |
|
yann@1
|
40 |
But once you want to get all the juice out of your specific hardware, you will
|
yann@197
|
41 |
want to build your own toolchain. This is where crosstool-NG comes into play.
|
yann@1
|
42 |
|
yann@1
|
43 |
There are also a number of tools that builds toolchains for specific needs,
|
yann@1
|
44 |
which is not really scalable. Examples are:
|
yann@1
|
45 |
- buildroot (buildroot.uclibc.org) whose main puprpose is to build root file
|
yann@1
|
46 |
systems, hence the name. But once you have your toolchain with buildroot,
|
yann@1
|
47 |
part of it is installed in the root-to-be, so if you want to build a whole
|
yann@1
|
48 |
new root, you either have to save the existing one as a template and
|
yann@1
|
49 |
restore it later, or restart again from scratch. This is not convenient,
|
yann@1
|
50 |
- ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
|
yann@1
|
51 |
similar to buildroot,
|
yann@1
|
52 |
- other projects (openembeded.org for example), which is again used to
|
yann@1
|
53 |
build root file systems.
|
yann@1
|
54 |
|
yann@1
|
55 |
crosstool-NG is really targetted at building toolchains, and only toolchains.
|
yann@1
|
56 |
It is then up to you to use it the way you want.
|
yann@1
|
57 |
|
yann@1
|
58 |
___________
|
yann@1
|
59 |
/
|
yann@1
|
60 |
History /
|
yann@1
|
61 |
________/
|
yann@1
|
62 |
|
yann@1
|
63 |
crosstool was first 'conceived' by Dan Kegel, which offered it to the community,
|
yann@1
|
64 |
as a set of scripts, a repository of patches, and some pre-configured, general
|
yann@1
|
65 |
purpose setup files to be used to configure crosstool. This is available at
|
yann@203
|
66 |
http://www.kegel.com/crosstool, and the subversion repository is hosted on
|
yann@203
|
67 |
google at http://code.google.com/p/crosstool/.
|
yann@1
|
68 |
|
yann@1
|
69 |
At the time of writing, crosstool only supports building with one C library,
|
yann@1
|
70 |
namely glibc, and one C compiler, gcc; it is cripled with historical support
|
yann@92
|
71 |
for legacy components, and is some kind of a mess to upgrade. Also, submited
|
yann@203
|
72 |
patches take a loooong time before they are integrated mainline.
|
yann@1
|
73 |
|
yann@1
|
74 |
I once managed to add support for uClibc-based toolchains, but it did not make
|
yann@1
|
75 |
into mainline, mostly because I don't have time to port the patch forward to
|
yann@1
|
76 |
the new versions, due in part to the big effort it was taking.
|
yann@1
|
77 |
|
yann@1
|
78 |
So I decided to clean up crosstool in the state it was, re-order the things
|
yann@1
|
79 |
in place, and add appropriate support for what I needed, that is uClibc
|
yann@203
|
80 |
support. That was a disaster, as inclusion into mainline is slow as hell,
|
yann@203
|
81 |
and the changes were so numerous.
|
yann@1
|
82 |
|
yann@1
|
83 |
The only option left to me was rewrite crosstool from scratch. I decided to go
|
yann@197
|
84 |
this way, and name the new implementation crosstool-NG, standing for crosstool
|
yann@197
|
85 |
Next Generation, as many other comunity projects do, and as a wink at the TV
|
yann@197
|
86 |
series "Star Trek: The Next Generation". ;-)
|
yann@1
|
87 |
|
yann@294
|
88 |
|
yann@294
|
89 |
___________________________
|
yann@294
|
90 |
/
|
yann@294
|
91 |
Installing crosstool-NG /
|
yann@294
|
92 |
________________________/
|
yann@294
|
93 |
|
yann@294
|
94 |
There are two ways you can use crosstool-NG:
|
yann@294
|
95 |
- build and install it, then get rid of the sources like you'd do for most
|
yann@294
|
96 |
programs,
|
yann@294
|
97 |
- or only build it and run from the source directory.
|
yann@294
|
98 |
|
yann@294
|
99 |
The former should be used if you got crosstool-NG from a packaged tarball, see
|
yann@294
|
100 |
"Install method", below, while the latter is most usefull for developpers that
|
yann@294
|
101 |
checked the code out from SVN, and want to submit patches, see "The Hacker's
|
yann@294
|
102 |
way", below.
|
yann@294
|
103 |
|
yann@294
|
104 |
Install method |
|
yann@294
|
105 |
---------------+
|
yann@294
|
106 |
|
yann@294
|
107 |
If you go for the install, then you just follow the classical, but yet easy
|
yann@294
|
108 |
./configure way:
|
yann@294
|
109 |
./configure --prefix=/some/place
|
yann@294
|
110 |
make
|
yann@294
|
111 |
make install
|
yann@294
|
112 |
export PATH="${PATH}:/some/place/bin"
|
yann@294
|
113 |
|
yann@294
|
114 |
You can then get rid of crosstool-NG source. Next create a directory to serve
|
yann@294
|
115 |
as a working place, cd in there and run:
|
yann@294
|
116 |
ct-ng help
|
yann@294
|
117 |
|
yann@294
|
118 |
See below for complete usage.
|
yann@294
|
119 |
|
yann@294
|
120 |
The Hacker's way |
|
yann@294
|
121 |
-----------------+
|
yann@294
|
122 |
|
yann@294
|
123 |
If you go the hacker's way, then the usage is a bit different, although very
|
yann@294
|
124 |
simple:
|
yann@294
|
125 |
./configure --local
|
yann@294
|
126 |
make
|
yann@294
|
127 |
|
yann@294
|
128 |
Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
|
yann@294
|
129 |
Stay in the directory holding the sources, and run:
|
yann@294
|
130 |
./ct-ng help
|
yann@294
|
131 |
|
yann@294
|
132 |
See below for complete usage.
|
yann@294
|
133 |
|
yann@294
|
134 |
Now, provided you checked-out the code, you can send me your interesting changes
|
yann@294
|
135 |
by running:
|
yann@294
|
136 |
svn diff
|
yann@294
|
137 |
|
yann@294
|
138 |
and mailing me the result! :-P
|
yann@294
|
139 |
|
yann@168
|
140 |
____________________________
|
yann@168
|
141 |
/
|
yann@168
|
142 |
Configuring crosstool-NG /
|
yann@168
|
143 |
_________________________/
|
yann@168
|
144 |
|
yann@277
|
145 |
crosstool-NG is configured by a configurator presenting a menu-stuctured set of
|
yann@277
|
146 |
options. These options let you specify the way you want your toolchain built,
|
yann@277
|
147 |
where you want it installed, what architecture and specific processor it
|
yann@277
|
148 |
will support, the version of the components you want to use, etc... The
|
yann@277
|
149 |
value for those options are then stored in a configuration file.
|
yann@277
|
150 |
|
yann@277
|
151 |
The configurator works the same way you configure your Linux kernel.It is
|
yann@277
|
152 |
assumed you now how to handle this.
|
yann@168
|
153 |
|
yann@168
|
154 |
To enter the menu, type:
|
yann@192
|
155 |
ct-ng menuconfig
|
yann@168
|
156 |
|
yann@203
|
157 |
Almost every config item has a help entry. Read them carefully.
|
yann@168
|
158 |
|
yann@168
|
159 |
String and number options can refer to environment variables. In such a case,
|
yann@192
|
160 |
you must use the shell syntax: ${VAR}. You shall neither single- nor double-
|
yann@294
|
161 |
quote the string/number options.
|
yann@168
|
162 |
|
yann@192
|
163 |
There are three environment variables that are computed by crosstool-NG, and
|
yann@168
|
164 |
that you can use:
|
yann@168
|
165 |
|
yann@168
|
166 |
CT_TARGET:
|
yann@335
|
167 |
It represents the target tuple you are building for. You can use it for
|
yann@168
|
168 |
example in the installation/prefix directory, such as:
|
yann@168
|
169 |
/opt/x-tools/${CT_TARGET}
|
yann@168
|
170 |
|
yann@168
|
171 |
CT_TOP_DIR:
|
yann@182
|
172 |
The top directory where crosstool-NG is running. You shouldn't need it in
|
yann@182
|
173 |
most cases. There is one case where you may need it: if you have local
|
yann@182
|
174 |
patches and you store them in your running directory, you can refer to them
|
yann@168
|
175 |
by using CT_TOP_DIR, such as:
|
yann@168
|
176 |
${CT_TOP_DIR}/patches.myproject
|
yann@168
|
177 |
|
yann@168
|
178 |
CT_VERSION:
|
yann@192
|
179 |
The version of crosstool-NG you are using. Not much use for you, but it's
|
yann@168
|
180 |
there if you need it.
|
yann@168
|
181 |
|
yann@168
|
182 |
|
yann@168
|
183 |
Interesting config options |
|
yann@168
|
184 |
---------------------------*
|
yann@168
|
185 |
|
yann@168
|
186 |
CT_LOCAL_TARBALLS_DIR:
|
yann@277
|
187 |
If you already have some tarballs in a direcotry, enter it here. That will
|
yann@197
|
188 |
speed up the retrieving phase, where crosstool-NG would otherwise download
|
yann@168
|
189 |
those tarballs.
|
yann@168
|
190 |
|
yann@168
|
191 |
CT_PREFIX_DIR:
|
yann@168
|
192 |
This is where the toolchain will be installed in (and for now, where it
|
yann@335
|
193 |
will run from). Common use it to add the target tuple in the directory
|
yann@277
|
194 |
path, such as (see above):
|
yann@277
|
195 |
/opt/x-tools/${CT_TARGET}
|
yann@168
|
196 |
|
yann@168
|
197 |
CT_TARGET_VENDOR:
|
yann@168
|
198 |
An identifier for your toolchain, will take place in the vendor part of the
|
yann@335
|
199 |
target tuple. It shall *not* contain spaces or dashes. Usually, keep it
|
yann@168
|
200 |
to a one-word string, or use underscores to separate words if you need.
|
yann@168
|
201 |
Avoid dots, commas, and special characters.
|
yann@168
|
202 |
|
yann@168
|
203 |
CT_TARGET_ALIAS:
|
yann@168
|
204 |
An alias for the toolchian. It will be used as a prefix to the toolchain
|
yann@168
|
205 |
tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
|
yann@168
|
206 |
|
yann@246
|
207 |
Also, if you think you don't see enough versions, you can try to enable one of
|
yann@246
|
208 |
those:
|
yann@246
|
209 |
|
yann@246
|
210 |
CT_OBSOLETE:
|
yann@246
|
211 |
Show obsolete versions or tools. Most of the time, you don't want to base
|
yann@246
|
212 |
your toolchain on too old a version (of gcc, for example). But at times, it
|
yann@246
|
213 |
can come handy to use such an old version for regression tests. Those old
|
yann@294
|
214 |
versions are hidden behind CT_OBSOLETE.
|
yann@246
|
215 |
|
yann@246
|
216 |
CT_EXPERIMENTAL:
|
yann@246
|
217 |
Show experimental versions or tools. Again, you might not want to base your
|
yann@246
|
218 |
toolchain on too recent tools (eg. gcc) for production. But if you need a
|
yann@246
|
219 |
feature present only in a recent version, or a new tool, you can find them
|
yann@246
|
220 |
hidden behind CT_EXPERIMENTAL.
|
yann@246
|
221 |
|
yann@246
|
222 |
CT_BROKEN:
|
yann@246
|
223 |
Show broken versions or tools. Some usefull tools are currently broken: they
|
yann@246
|
224 |
won't compile, run, or worse, cause defects when running. But if you are
|
yann@246
|
225 |
brave enough, you can try and debug them. They are hidden behind CT_BROKEN,
|
yann@294
|
226 |
which itself is hidden behind EXPERIMENTAL.
|
yann@246
|
227 |
|
yann@276
|
228 |
Re-building an existing toolchain |
|
yann@276
|
229 |
----------------------------------+
|
yann@276
|
230 |
|
yann@276
|
231 |
If you have an existing toolchain, you can re-use the options used to build it
|
yann@276
|
232 |
to create a new toolchain. That needs a very little bit of effort on your side
|
yann@276
|
233 |
but is quite easy. The options to build a toolchain are saved in the build log
|
yann@276
|
234 |
file that is saved within the toolchain. crosstool-NG can extract those options
|
yann@276
|
235 |
to recreate a new configuration:
|
yann@276
|
236 |
ct-ng extractconfig </path/to/your/build.log
|
yann@276
|
237 |
|
yann@276
|
238 |
will extract those options, prompt you for the new ones, which you can later
|
yann@276
|
239 |
edit with menuconfig.
|
yann@276
|
240 |
|
yann@276
|
241 |
Of course, if your build log was compressed, you'd have to use something like:
|
yann@276
|
242 |
bzcat /path/to/your/build.log.bz2 |ct-ng extractconfig
|
yann@276
|
243 |
|
yann@168
|
244 |
________________________
|
yann@168
|
245 |
/
|
yann@168
|
246 |
Running crosstool-NG /
|
yann@168
|
247 |
_____________________/
|
yann@1
|
248 |
|
yann@168
|
249 |
To build the toolchain, simply type:
|
yann@203
|
250 |
ct-ng build
|
yann@135
|
251 |
|
yann@135
|
252 |
This will use the above configuration to retrieve, extract and patch the
|
yann@135
|
253 |
components, build, install and eventually test your newly built toolchain.
|
yann@1
|
254 |
|
yann@1
|
255 |
You are then free to add the toolchain /bin directory in your PATH to use
|
yann@1
|
256 |
it at will.
|
yann@1
|
257 |
|
yann@135
|
258 |
In any case, you can get some terse help. Just type:
|
yann@192
|
259 |
ct-ng help
|
yann@203
|
260 |
or:
|
yann@203
|
261 |
man 1 ct-ng
|
yann@135
|
262 |
|
yann@135
|
263 |
|
yann@135
|
264 |
Stoping and restarting a build |
|
yann@135
|
265 |
-------------------------------*
|
yann@135
|
266 |
|
yann@135
|
267 |
If you want to stop the build after a step you are debugging, you can pass the
|
yann@135
|
268 |
variable STOP to make:
|
yann@192
|
269 |
ct-ng STOP=some_step
|
yann@135
|
270 |
|
yann@135
|
271 |
Conversely, if you want to restart a build at a specific step you are
|
yann@135
|
272 |
debugging, you can pass the RESTART variable to make:
|
yann@192
|
273 |
ct-ng RESTART=some_step
|
yann@135
|
274 |
|
yann@136
|
275 |
Alternatively, you can call make with the name of a step to just do that step:
|
yann@192
|
276 |
ct-ng libc_headers
|
yann@136
|
277 |
is equivalent to:
|
yann@192
|
278 |
ct-ng RESTART=libs_headers STOP=libc_headers
|
yann@136
|
279 |
|
yann@304
|
280 |
The shortcuts +step_name and step_name+ allow to respectively stop or restart
|
yann@136
|
281 |
at that step. Thus:
|
yann@304
|
282 |
ct-ng +libc_headers and: ct-ng libc_headers+
|
yann@136
|
283 |
are equivalent to:
|
yann@192
|
284 |
ct-ng STOP=libc_headers and: ct-ng RESTART=libc_headers
|
yann@136
|
285 |
|
yann@181
|
286 |
To obtain the list of acceptable steps, please call:
|
yann@192
|
287 |
ct-ng liststeps
|
yann@181
|
288 |
|
yann@168
|
289 |
Note that in order to restart a build, you'll have to say 'Y' to the config
|
yann@168
|
290 |
option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
|
yann@168
|
291 |
that far.
|
yann@92
|
292 |
|
yann@92
|
293 |
|
yann@168
|
294 |
Testing all toolchains at once |
|
yann@168
|
295 |
-------------------------------*
|
yann@92
|
296 |
|
yann@168
|
297 |
You can test-build all samples; simply call:
|
yann@192
|
298 |
ct-ng regtest
|
yann@40
|
299 |
|
yann@335
|
300 |
|
yann@335
|
301 |
Overriding the number of // jobs |
|
yann@335
|
302 |
---------------------------------*
|
yann@335
|
303 |
|
yann@335
|
304 |
If you want to override the number of jobs to run in // (the -j option to
|
yann@335
|
305 |
make), you can either re-enter the menuconfig, or simply add it on the command
|
yann@335
|
306 |
line, as such:
|
yann@335
|
307 |
ct-ng build.4
|
yann@335
|
308 |
|
yann@335
|
309 |
which tells crosstool-NG to override the number of // jobs to 4.
|
yann@335
|
310 |
|
yann@335
|
311 |
You can see the actions that support overriding the number of // jobs in
|
yann@335
|
312 |
the help menu. Those are the ones with [.#] after them (eg. build[.#] or
|
yann@335
|
313 |
regtest[.#], and so on...).
|
yann@335
|
314 |
|
yann@227
|
315 |
_______________________
|
yann@227
|
316 |
/
|
yann@227
|
317 |
Using the toolchain /
|
yann@227
|
318 |
____________________/
|
yann@227
|
319 |
|
yann@227
|
320 |
Using the toolchain is as simple as adding the toolchain's bin directory in
|
yann@227
|
321 |
your PATH, such as:
|
yann@227
|
322 |
export PATH="${PATH}:/your/toolchain/path/bin"
|
yann@227
|
323 |
|
yann@335
|
324 |
and then using the target tuple to tell the build systems to use your
|
yann@227
|
325 |
toolchain:
|
yann@335
|
326 |
./configure --target=your-target-tuple
|
yann@294
|
327 |
or
|
yann@335
|
328 |
make CC=your-target-tuple-gcc
|
yann@294
|
329 |
or
|
yann@335
|
330 |
make CROSS_COMPILE=your-target-tuple-
|
yann@294
|
331 |
and so on...
|
yann@227
|
332 |
|
yann@227
|
333 |
When your root directory is ready, it is still missing some important bits: the
|
yann@227
|
334 |
toolchain's libraries. To populate your root directory with those libs, just
|
yann@227
|
335 |
run:
|
yann@335
|
336 |
your-target-tuple-populate -s /your/root -d /your/root-populated
|
yann@227
|
337 |
|
yann@227
|
338 |
This will copy /your/root into /your/root-populated, and put the needed and only
|
yann@227
|
339 |
the needed libraries there. Thus you don't polute /your/root with any cruft that
|
yann@227
|
340 |
would no longer be needed should you have to remove stuff. /your/root always
|
yann@227
|
341 |
contains only those things you install in it.
|
yann@227
|
342 |
|
yann@227
|
343 |
You can then use /your/root-populated to build up your file system image, a
|
yann@227
|
344 |
tarball, or to NFS-mount it from your target, or whatever you need.
|
yann@227
|
345 |
|
yann@294
|
346 |
populate accepts the following options:
|
yann@294
|
347 |
|
yann@294
|
348 |
-s [src_dir]
|
yann@294
|
349 |
Use 'src_dir' as the 'source', un-populated root directory
|
yann@294
|
350 |
|
yann@294
|
351 |
-d [dst_dir]
|
yann@294
|
352 |
Put the 'destination', populated root directory in 'dst_dir'
|
yann@294
|
353 |
|
yann@294
|
354 |
-f
|
yann@294
|
355 |
Remove 'dst_dir' if it previously existed
|
yann@294
|
356 |
|
yann@294
|
357 |
-v
|
yann@294
|
358 |
Be verbose, and tell what's going on (you can see exactly where libs are
|
yann@294
|
359 |
coming from).
|
yann@294
|
360 |
|
yann@294
|
361 |
-h
|
yann@294
|
362 |
Print the help
|
yann@294
|
363 |
|
yann@40
|
364 |
___________________
|
yann@40
|
365 |
/
|
yann@40
|
366 |
Toolchain types /
|
yann@40
|
367 |
________________/
|
yann@40
|
368 |
|
yann@40
|
369 |
There are four kinds of toolchains you could encounter.
|
yann@40
|
370 |
|
yann@40
|
371 |
First off, you must understand the following: when it comes to compilers there
|
yann@40
|
372 |
are up to four machines involved:
|
yann@40
|
373 |
1) the machine configuring the toolchain components: the config machine
|
yann@40
|
374 |
2) the machine building the toolchain components: the build machine
|
yann@40
|
375 |
3) the machine running the toolchain: the host machine
|
yann@203
|
376 |
4) the machine the toolchain is generating code for: the target machine
|
yann@40
|
377 |
|
yann@40
|
378 |
We can most of the time assume that the config machine and the build machine
|
yann@40
|
379 |
are the same. Most of the time, this will be true. The only time it isn't
|
yann@40
|
380 |
is if you're using distributed compilation (such as distcc). Let's forget
|
yann@40
|
381 |
this for the sake of simplicity.
|
yann@40
|
382 |
|
yann@40
|
383 |
So we're left with three machines:
|
yann@40
|
384 |
- build
|
yann@40
|
385 |
- host
|
yann@40
|
386 |
- target
|
yann@40
|
387 |
|
yann@40
|
388 |
Any toolchain will involve those three machines. You can be as pretty sure of
|
yann@40
|
389 |
this as "2 and 2 are 4". Here is how they come into play:
|
yann@40
|
390 |
|
yann@40
|
391 |
1) build == host == target
|
yann@40
|
392 |
This is a plain native toolchain, targetting the exact same machine as the
|
yann@40
|
393 |
one it is built on, and running again on this exact same machine. You have
|
yann@40
|
394 |
to build such a toolchain when you want to use an updated component, such
|
yann@40
|
395 |
as a newer gcc for example.
|
yann@197
|
396 |
crosstool-NG calls it "native".
|
yann@40
|
397 |
|
yann@40
|
398 |
2) build == host != target
|
yann@40
|
399 |
This is a classic cross-toolchain, which is expected to be run on the same
|
yann@40
|
400 |
machine it is compiled on, and generate code to run on a second machine,
|
yann@40
|
401 |
the target.
|
yann@197
|
402 |
crosstool-NG calls it "cross".
|
yann@40
|
403 |
|
yann@40
|
404 |
3) build != host == target
|
yann@40
|
405 |
Such a toolchain is also a native toolchain, as it targets the same machine
|
yann@40
|
406 |
as it runs on. But it is build on another machine. You want such a
|
yann@40
|
407 |
toolchain when porting to a new architecture, or if the build machine is
|
yann@40
|
408 |
much faster than the host machine.
|
yann@197
|
409 |
crosstool-NG calls it "cross-native".
|
yann@40
|
410 |
|
yann@40
|
411 |
4) build != host != target
|
yann@92
|
412 |
This one is called a canadian-toolchain (*), and is tricky. The three
|
yann@40
|
413 |
machines in play are different. You might want such a toolchain if you
|
yann@40
|
414 |
have a fast build machine, but the users will use it on another machine,
|
yann@40
|
415 |
and will produce code to run on a third machine.
|
yann@197
|
416 |
crosstool-NG calls it "canadian".
|
yann@40
|
417 |
|
yann@197
|
418 |
crosstool-NG can build all these kinds of toolchains (or is aiming at it,
|
yann@197
|
419 |
anyway!)
|
yann@40
|
420 |
|
yann@40
|
421 |
(*) The term Canadian Cross came about because at the time that these issues
|
yann@40
|
422 |
were all being hashed out, Canada had three national political parties.
|
yann@40
|
423 |
http://en.wikipedia.org/wiki/Cross_compiler
|
yann@40
|
424 |
|
yann@1
|
425 |
_____________
|
yann@1
|
426 |
/
|
yann@1
|
427 |
Internals /
|
yann@1
|
428 |
__________/
|
yann@1
|
429 |
|
yann@92
|
430 |
Internally, crosstool-NG is script-based. To ease usage, the frontend is
|
yann@92
|
431 |
Makefile-based.
|
yann@92
|
432 |
|
yann@92
|
433 |
Makefile front-end |
|
yann@92
|
434 |
-------------------*
|
yann@92
|
435 |
|
yann@203
|
436 |
The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
|
yann@203
|
437 |
script with an action will act exactly as if the Makefile was in the current
|
yann@203
|
438 |
working directory and make was called with the action as rule. Thus:
|
yann@203
|
439 |
ct-ng menuconfig
|
yann@294
|
440 |
|
yann@203
|
441 |
is equivalent to having the Makefile in CWD, and calling:
|
yann@203
|
442 |
make menuconfig
|
yann@203
|
443 |
|
yann@203
|
444 |
Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
|
yann@203
|
445 |
traditional command.
|
yann@203
|
446 |
|
yann@203
|
447 |
ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
|
yann@203
|
448 |
at configuration time with ./configure.
|
yann@203
|
449 |
|
yann@203
|
450 |
ct-ng also search for config files, sub-tools, samples, scripts and patches in
|
yann@203
|
451 |
that library directory.
|
yann@92
|
452 |
|
yann@294
|
453 |
Because of a stupid make behavior/bug I was unable to track down, implicit make
|
yann@294
|
454 |
rules are disabled: installing with --local would triger those rules, and mconf
|
yann@294
|
455 |
was unbuildable.
|
yann@294
|
456 |
|
yann@182
|
457 |
Kconfig parser |
|
yann@182
|
458 |
---------------*
|
yann@92
|
459 |
|
yann@92
|
460 |
The kconfig language is a hacked version, vampirised from the toybox project
|
yann@182
|
461 |
by Rob LANDLEY (http://www.landley.net/code/toybox/), itself coming from the
|
yann@294
|
462 |
Linux kernel (http://www.kernel.org/), and (heavily) adapted to my needs.
|
yann@92
|
463 |
|
yann@203
|
464 |
The kconfig parsers (conf and mconf) are not installed pre-built, but as
|
yann@203
|
465 |
source files. Thus you can have the directory where crosstool-NG is installed,
|
yann@203
|
466 |
exported (via NFS or whatever) and have clients with different architectures
|
yann@203
|
467 |
use the same crosstool-NG installation, and most notably, the same set of
|
yann@203
|
468 |
patches.
|
yann@203
|
469 |
|
yann@381
|
470 |
Architecture-specific |
|
yann@381
|
471 |
----------------------*
|
yann@381
|
472 |
|
yann@381
|
473 |
An architecture is defined by:
|
yann@381
|
474 |
|
yann@381
|
475 |
- a human-readable name, in lower case letters, with numbers as appropriate.
|
yann@381
|
476 |
The underscore is allowed. Eg.: arm, x86_64
|
yann@381
|
477 |
- a boolean kconfig option named after the architecture (in capital letters
|
yann@381
|
478 |
if possible) prefixed with "ARCH_". Eg.: ARCH_ARM, ARCH_x86_64
|
yann@381
|
479 |
- a directory in "arch/" named after the architecture, with the same letters
|
yann@381
|
480 |
as above. Eg.: arch/arm, arch/x86_64
|
yann@381
|
481 |
This directory contains:
|
yann@381
|
482 |
- a configuration file in kconfig syntax, named "config.in", which may be
|
yann@381
|
483 |
empty. Eg.: arch/arm/config.in
|
yann@381
|
484 |
- a function script in bash-3.0 syntax, named "functions", which shall
|
yann@381
|
485 |
follow the API defined below. Eg.: arch/arm/functions
|
yann@381
|
486 |
|
yann@381
|
487 |
The "functions" file API:
|
yann@383
|
488 |
> the function "CT_DoArchValues"
|
yann@381
|
489 |
+ parameters: none
|
yann@381
|
490 |
+ environment:
|
yann@381
|
491 |
- all variables from the ".config" file,
|
yann@381
|
492 |
- the two variables "target_endian_eb" and "target_endian_el" which are
|
yann@383
|
493 |
the endianness suffixes
|
yann@381
|
494 |
+ return value: 0 upon success, !0 upon failure
|
yann@381
|
495 |
+ provides:
|
yann@391
|
496 |
- mandatory
|
yann@383
|
497 |
- the environment variable CT_TARGET_ARCH
|
yann@389
|
498 |
- contains:
|
yann@389
|
499 |
the architecture part of the target tuple.
|
yann@389
|
500 |
Eg.: "armeb" for big endian ARM
|
yann@389
|
501 |
"i386" for an i386
|
yann@389
|
502 |
+ provides:
|
yann@391
|
503 |
- optional
|
yann@389
|
504 |
- the environment variable CT_TARGET_SYS
|
yann@383
|
505 |
- contain:
|
yann@383
|
506 |
the sytem part of the target tuple.
|
yann@383
|
507 |
Eg.: "gnu" for glibc on most architectures
|
yann@383
|
508 |
"gnueabi" for glibc on an ARM EABI
|
yann@383
|
509 |
- defaults to:
|
yann@383
|
510 |
- for glibc-based toolchain: "gnu"
|
yann@383
|
511 |
- for uClibc-based toolchain: "uclibc"
|
yann@383
|
512 |
+ provides:
|
yann@383
|
513 |
- optional
|
yann@391
|
514 |
- the environment variable CT_KERNEL_ARCH
|
yann@383
|
515 |
- contains:
|
yann@391
|
516 |
the architecture name as understandable by the Linux kernel build
|
yann@391
|
517 |
system.
|
yann@391
|
518 |
Eg.: "arm" for an ARM
|
yann@391
|
519 |
"powerpc" for a PowerPC
|
yann@391
|
520 |
"i386" for an x86
|
yann@383
|
521 |
- defaults to:
|
yann@391
|
522 |
${CT_ARCH}
|
yann@391
|
523 |
+ provides:
|
yann@391
|
524 |
- optional
|
yann@391
|
525 |
- the environment variables to configure the cross-gcc
|
yann@391
|
526 |
- CT_ARCH_WITH_ARCH
|
yann@391
|
527 |
- CT_ARCH_WITH_ABI
|
yann@391
|
528 |
- CT_ARCH_WITH_CPU
|
yann@391
|
529 |
- CT_ARCH_WITH_TUNE
|
yann@391
|
530 |
- CT_ARCH_WITH_FPU
|
yann@391
|
531 |
- CT_ARCH_WITH_FLOAT
|
yann@391
|
532 |
- contain (defaults):
|
yann@391
|
533 |
- CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
|
yann@391
|
534 |
- CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ARCH}" )
|
yann@391
|
535 |
- CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_ARCH}" )
|
yann@391
|
536 |
- CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_ARCH}" )
|
yann@391
|
537 |
- CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_ARCH}" )
|
yann@391
|
538 |
- CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
|
yann@391
|
539 |
+ provides:
|
yann@391
|
540 |
- optional
|
yann@391
|
541 |
- the environment variables to pass to the cross-gcc to build target binaries
|
yann@391
|
542 |
- CT_ARCH_ARCH_CFLAG
|
yann@391
|
543 |
- CT_ARCH_ABI_CFLAG
|
yann@391
|
544 |
- CT_ARCH_CPU_CFLAG
|
yann@391
|
545 |
- CT_ARCH_TUNE_CFLAG
|
yann@391
|
546 |
- CT_ARCH_FPU_CFLAG
|
yann@391
|
547 |
- CT_ARCH_FLOAT_CFLAG
|
yann@391
|
548 |
- CT_ARCH_ENDIAN_CFLAG
|
yann@391
|
549 |
- contain (defaults):
|
yann@391
|
550 |
- CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
|
yann@391
|
551 |
- CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_AABI}" )
|
yann@391
|
552 |
- CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
|
yann@391
|
553 |
- CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
|
yann@391
|
554 |
- CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
|
yann@391
|
555 |
- CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
|
yann@391
|
556 |
- CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
|
yann@391
|
557 |
- default to:
|
yann@391
|
558 |
see above.
|
yann@391
|
559 |
|
yann@381
|
560 |
|
yann@203
|
561 |
Build scripts |
|
yann@203
|
562 |
--------------*
|
yann@203
|
563 |
|
yann@203
|
564 |
To Be Written later...
|