1 |
<?xml version='1.0' encoding="UTF-8"?> |
2 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.23 2006/09/13 23:20:10 jkt Exp $ --> |
3 |
|
4 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
5 |
|
6 |
<guide link="/doc/en/gcc-upgrading.xml"> |
7 |
<title>Gentoo GCC Upgrade Guide</title> |
8 |
|
9 |
<author title="Author"> |
10 |
<mail link="amne@gentoo.org">Wernfried Haas</mail> |
11 |
</author> |
12 |
<author title="Author"> |
13 |
<mail link="jkt@gentoo.org">Jan Kundrát</mail> |
14 |
</author> |
15 |
<author title="Editor"> |
16 |
<mail link="mark@halcy0n.com">Mark Loeser</mail> |
17 |
</author> |
18 |
|
19 |
<abstract> |
20 |
This document will guide the user through the process of upgrading GCC on their |
21 |
Gentoo machines. |
22 |
</abstract> |
23 |
|
24 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
25 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
26 |
<license/> |
27 |
|
28 |
<version>20</version> |
29 |
<date>2006-09-13</date> |
30 |
|
31 |
<chapter id="intro"> |
32 |
<title>Introduction</title> |
33 |
<section> |
34 |
<title>GCC Upgrading</title> |
35 |
<body> |
36 |
|
37 |
<p> |
38 |
Why should you upgrade? Well, GCC is quite similar to any other package on your |
39 |
system, just a bit more critical. You should upgrade GCC whenever a new version |
40 |
fixes some bug that annoys you, new functionality you need is introduced, or if |
41 |
you want to keep your system up-to-date. If none of the previous cases apply to |
42 |
you, you can safely postpone upgrade as long as your GCC version is supported by |
43 |
Gentoo developers. |
44 |
</p> |
45 |
|
46 |
<p> |
47 |
If you install a new major version of GCC (such as 3.3.6 to 3.4.5), the system |
48 |
will not switch over to use it automatically. You'll have to explicitly request |
49 |
the change because the migration process might require some additional steps. |
50 |
If you decide not to switch, Portage will continue to use older version of your |
51 |
compiler until you change your mind, or remove the old compiler from the system. |
52 |
Non-major gcc upgrades are switched automatically for you (such as 3.4.5 to |
53 |
3.4.6). |
54 |
</p> |
55 |
|
56 |
<p> |
57 |
This guide will document the necessary steps required to perform a seamless |
58 |
upgrade of the compiler used by your Gentoo box. A specific section is |
59 |
dedicated to the <uri link="#upgrade-3.3-to-3.4">upgrade from GCC 3.3 to 3.4</uri> |
60 |
and issues with <c>libstdc++</c>. A second specific |
61 |
section is for users <uri link="#first-install">first installing</uri> Gentoo |
62 |
using a stage3 tarball, after a new GCC major/minor version has been released. |
63 |
</p> |
64 |
|
65 |
<warn> |
66 |
It should be noted that upgrading from GCC-3.4 (or 3.3) to GCC-4.1 or greater |
67 |
still requires you to follow the <uri link="#upgrade-general">general upgrading |
68 |
instructions</uri>, as GCC-3.4 and GCC-4.1 use slightly different ABIs. |
69 |
</warn> |
70 |
|
71 |
</body> |
72 |
</section> |
73 |
</chapter> |
74 |
|
75 |
<chapter id="upgrade-general"> |
76 |
<title>General Upgrade Instructions</title> |
77 |
<section> |
78 |
<title>Introduction</title> |
79 |
<body> |
80 |
|
81 |
<impo> |
82 |
If you're looking for instructions specific to upgrades from GCC-3.3 to GCC-3.4, |
83 |
please consult the <uri link="#upgrade-3.3-to-3.4">dedicated |
84 |
section</uri>. |
85 |
</impo> |
86 |
|
87 |
<impo> |
88 |
If you're looking for instructions specific to upgrades in GCC for new |
89 |
installs, please consult the <uri link="#first-install">dedicated |
90 |
section</uri>. |
91 |
</impo> |
92 |
|
93 |
<p> |
94 |
Generally speaking, upgrades to <e>bug fix releases</e>, like from 3.3.5 to |
95 |
3.3.6, should be quite safe -- just emerge new version, switch your system to |
96 |
use it and rebuild the only affected package, <c>libtool</c>. However, some GCC |
97 |
upgrades break binary compatibility; in such cases a rebuild of the affected |
98 |
packages (or even whole toolchain and system) might be required. |
99 |
</p> |
100 |
|
101 |
<p> |
102 |
When we spoke about the need to switch your compiler to the newer version by |
103 |
hand, we said it won't happen automatically. However, there is one exception -- |
104 |
upgrades to bug fix releases, like from 3.3.5 to 3.3.6 in case you don't use the |
105 |
"multislot" feature allowing them to coexist on one system. Multislot is |
106 |
disabled by default as the majority of users won't benefit from it. |
107 |
</p> |
108 |
|
109 |
<pre caption="Upgrading GCC"> |
110 |
# <i>emerge -uav gcc</i> |
111 |
|
112 |
<comment>(Please substitute "i686-pc-linux-gnu-4.1.1" with the GCC |
113 |
version and CHOST settings you've upgraded to:)</comment> |
114 |
# <i>gcc-config i686-pc-linux-gnu-4.1.1</i> |
115 |
# <i>source /etc/profile</i> |
116 |
|
117 |
<comment>If you upgraded from gcc 3 to 4 (e.g. from 3.4.6 to 4.1.1 in this |
118 |
example) you will have to run fix_libtool_files.sh manually</comment> |
119 |
# <i>fix_libtool_files.sh 3.4.6</i> |
120 |
|
121 |
<comment>(Rebuilding libtool)</comment> |
122 |
# <i>emerge --oneshot -av libtool</i> |
123 |
</pre> |
124 |
|
125 |
<p> |
126 |
To be completely safe that your system is in a sane state, you <e>must</e> |
127 |
rebuild the toolchain and then world to make use of the new compiler. |
128 |
</p> |
129 |
|
130 |
<pre caption="Rebuilding system"> |
131 |
# <i>emerge -eav system</i> |
132 |
# <i>emerge -eav world</i> |
133 |
</pre> |
134 |
|
135 |
<p> |
136 |
It is safe to remove the older GCC version at this time. If you feel the need, |
137 |
please issue the following command (as usual, substitute |
138 |
<c>=sys-devel/gcc-3.4*</c> with the version you want to uninstall): |
139 |
</p> |
140 |
|
141 |
<pre caption="Removing older GCC version"> |
142 |
# <i>emerge -aC =sys-devel/gcc-3.4*</i> |
143 |
</pre> |
144 |
|
145 |
<impo> |
146 |
Please note that the GCC 4.1 and newer can't compile a 2.4 kernel. Don't remove |
147 |
your old GCC version if you want to use an older kernel. |
148 |
</impo> |
149 |
|
150 |
<impo> <!-- FIXME: do we really want to keep it here? --> |
151 |
In case you're upgrading from GCC-3.3, you should run <c>emerge --oneshot |
152 |
sys-libs/libstdc++-v3</c> to provide compatibility with older binary C++ |
153 |
applications. |
154 |
</impo> |
155 |
|
156 |
</body> |
157 |
</section> |
158 |
</chapter> |
159 |
|
160 |
<chapter id="upgrade-3.3-to-3.4"> |
161 |
<title>Upgrading from GCC-3.3 to 3.4</title> |
162 |
<section> |
163 |
<title>Introduction</title> |
164 |
<body> |
165 |
|
166 |
<p> |
167 |
The upgrade from GCC-3.3 to 3.4 is not seamless as the C++ ABI |
168 |
changed between these two versions. There is an issue with the <c>libstdc++</c> |
169 |
library which must be taken care of, as well. |
170 |
</p> |
171 |
|
172 |
</body> |
173 |
</section> |
174 |
<section id="upgrade-3.3-to-3.4-choices"> |
175 |
<title>The Choices</title> |
176 |
<body> |
177 |
|
178 |
<impo> |
179 |
If you upgrade from gcc 3.4 to 4.1, please consult the <uri |
180 |
link="#upgrade-general">General Update instructions</uri>. |
181 |
</impo> |
182 |
|
183 |
<impo> |
184 |
If you're upgrading on a SPARC machine, you will have to take the way of |
185 |
<uri link="#upgrade-3.3-to-3.4-emerge-e">complete system rebuild</uri> due to |
186 |
some internal <uri link="http://gcc.gnu.org/gcc-3.4/sparc-abi.html">ABI |
187 |
changes</uri> in GCC's parameter passing. |
188 |
</impo> |
189 |
|
190 |
<p> |
191 |
If you upgrade from gcc 3.3 to 3.4, you have two possibilities on how to |
192 |
upgrade your system. The <uri link="#upgrade-3.3-to-3.4-revdep-rebuild">first |
193 |
method</uri> is faster and requires use of the <c>revdep-rebuild</c> tool from |
194 |
package <c>gentoolkit</c> while the <uri |
195 |
link="#upgrade-3.3-to-3.4-emerge-e">second one</uri> rebuilds the entire |
196 |
system from scratch so it will make use of new GCC features. It's up to you to |
197 |
decide which of these two ways you will choose. In most cases, the first |
198 |
method is sufficient. |
199 |
</p> |
200 |
|
201 |
<p> |
202 |
If you upgrade from gcc 3.3 to 4.1, do not use the method based on |
203 |
revdep-rebuild, but do a <uri link="#upgrade-3.3-to-3.4-emerge-e">complete |
204 |
system rebuild</uri>. |
205 |
</p> |
206 |
|
207 |
</body> |
208 |
</section> |
209 |
<section id="upgrade-3.3-to-3.4-revdep-rebuild"> |
210 |
<title>Using revdep-rebuild</title> |
211 |
<body> |
212 |
|
213 |
<p> |
214 |
This method requires that you first install <c>gentoolkit</c> if you have not |
215 |
already done so. Then we will upgrade GCC and switch to the new compiler. We |
216 |
will also rebuild the <c>libtool</c> package to ensure that toolchain is in |
217 |
healthy state. |
218 |
</p> |
219 |
|
220 |
<pre caption="Installing gentoolkit and upgrading GCC"> |
221 |
# <i>emerge -an gentoolkit</i> |
222 |
# <i>emerge -uav gcc</i> |
223 |
<comment>(Please substitute "i686-pc-linux-gnu-3.4.5" with the GCC |
224 |
version and CHOST settings you've upgraded to:)</comment> |
225 |
# <i>gcc-config i686-pc-linux-gnu-3.4.5</i> |
226 |
# <i>source /etc/profile</i> |
227 |
|
228 |
<comment>(Rebuilding libtool)</comment> |
229 |
# <i>emerge --oneshot -av libtool</i> |
230 |
</pre> |
231 |
|
232 |
<p> |
233 |
Now, we want to see which packages that revdep-rebuild will want to rebuild. |
234 |
Then we will tell revdep-rebuild to actually rebuild the packages. This may take |
235 |
some time, so have some patience. |
236 |
</p> |
237 |
|
238 |
<pre caption="Using revdep-rebuild"> |
239 |
# <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i> |
240 |
# <i>revdep-rebuild --library libstdc++.so.5</i> |
241 |
</pre> |
242 |
|
243 |
<note> |
244 |
It is possible that you might have problems with non-existing package versions |
245 |
due to them being outdated or masked. If this is the case, you will want to use |
246 |
the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages |
247 |
to be recompiled based on the package name, rather than the exact name and |
248 |
version. |
249 |
</note> |
250 |
|
251 |
<p> |
252 |
To provide compatibility with older binary C++ applications and any packages |
253 |
that revdep-rebuild might have missed, <c>sys-libs/libstdc++-v3</c> needs to be |
254 |
merged before you unmerge GCC 3.3 from your system. |
255 |
</p> |
256 |
|
257 |
<pre caption="Installing libstdc++-v3 and cleaning up"> |
258 |
# <i>emerge --oneshot sys-libs/libstdc++-v3</i> |
259 |
# <i>emerge -aC =sys-devel/gcc-3.3*</i> |
260 |
</pre> |
261 |
|
262 |
</body> |
263 |
</section> |
264 |
<section id="upgrade-3.3-to-3.4-emerge-e"> |
265 |
<title>Using emerge -e</title> |
266 |
<body> |
267 |
|
268 |
<p> |
269 |
This method, while much slower, will rebuild your whole system to ensure that |
270 |
everything has been rebuilt with your new compiler, and therefore safer. At |
271 |
first, you will upgrade GCC and libtool and switch to your new compiler. |
272 |
</p> |
273 |
|
274 |
<pre caption="Upgrading GCC"> |
275 |
# <i>emerge -uav gcc</i> |
276 |
<comment>(Please substitute "i686-pc-linux-gnu-3.4.5" with the GCC |
277 |
version and CHOST settings you've upgraded to:)</comment> |
278 |
# <i>gcc-config i686-pc-linux-gnu-3.4.5</i> |
279 |
# <i>source /etc/profile</i> |
280 |
|
281 |
<comment>If you upgraded from gcc 3 to 4 (e.g. from 3.3.6 to 4.1.1 in this |
282 |
example) you will have to run fix_libtool_files.sh manually</comment> |
283 |
# <i>fix_libtool_files.sh 3.3.6</i> |
284 |
|
285 |
<comment>(Rebuilding libtool)</comment> |
286 |
# <i>emerge --oneshot -av libtool</i> |
287 |
</pre> |
288 |
|
289 |
<p> |
290 |
To provide compatibility with older binary C++ applications, |
291 |
<c>sys-libs/libstdc++-v3</c> needs to be merged onto your system. |
292 |
</p> |
293 |
|
294 |
<pre caption="Installing libstdc++-v3"> |
295 |
# <i>emerge --oneshot sys-libs/libstdc++-v3</i> |
296 |
</pre> |
297 |
|
298 |
<p> |
299 |
Now we will go about first rebuilding the system target, then the world target. |
300 |
This will take a very long time, depending on the number of packages that you |
301 |
have installed, as it will rebuild your entire toolchain and supporting system |
302 |
files, followed by every package on your system, including the toolchain. This |
303 |
is necessary to ensure that all packages have been compiled with the new |
304 |
toolchain, including the toolchain itself. |
305 |
</p> |
306 |
|
307 |
<pre caption="Rebuilding system and world"> |
308 |
# <i>emerge -e system</i> |
309 |
# <i>emerge -e world</i> |
310 |
</pre> |
311 |
|
312 |
<p> |
313 |
It is also safe to remove older GCC versions at this time: |
314 |
</p> |
315 |
|
316 |
<pre caption="Cleaning up"> |
317 |
# <i>emerge -aC =sys-devel/gcc-3.3*</i> |
318 |
</pre> |
319 |
|
320 |
</body> |
321 |
</section> |
322 |
</chapter> |
323 |
|
324 |
<chapter id="first-install"> |
325 |
<title>Upgrading to GCC on a First Install</title> |
326 |
<section> |
327 |
<title>Introduction</title> |
328 |
<body> |
329 |
|
330 |
<p> |
331 |
A GCC upgrade on a system after installation from a stage3 tarball is a simple |
332 |
affair. One advantage users of new installations have is they do not have a |
333 |
plethora of software installed that links against the older version of GCC. |
334 |
The following example is for a GCC-3.3 to 3.4 upgrade. Certain parts |
335 |
will be different if upgrading from other versions of GCC. For example, the |
336 |
library names used for <c>revdep-rebuild</c> below are GCC 3.3 specific, as |
337 |
well as the need to install <c>libstdc++-v3</c>. |
338 |
</p> |
339 |
|
340 |
<p> |
341 |
If a user has not made any customizations to their system yet, then there are |
342 |
very few steps to get their system upgraded to a new GCC version. As with the |
343 |
GCC-3.3 to 3.4 upgrade, the user has a couple options. However, unlike the |
344 |
GCC-3.3 to 3.4 upgrade, this one is less complicated as there are fewer |
345 |
differences between the methods. The <uri |
346 |
link="#first-install-revdep-rebuild">first method</uri> is faster and makes use |
347 |
of the <c>revdep-rebuild</c> tool from <c>gentoolkit</c>, similar to the above |
348 |
procedure. Using revdep-rebuild causes only packages which actually link |
349 |
against GCC libraries to be rebuilt, while the <uri |
350 |
link="#first-install-emerge-e">second method</uri> causes your entire new |
351 |
install to be recompiled with the new GCC version and takes much longer. This |
352 |
second method is never required and only documented for completeness. |
353 |
</p> |
354 |
|
355 |
<p> |
356 |
These first steps are common between both methods, and should be completed by |
357 |
everyone. |
358 |
</p> |
359 |
|
360 |
<pre caption="Upgrading GCC"> |
361 |
# <i>emerge -uav gcc</i> |
362 |
<comment>(Please substitute "i686-pc-linux-gnu-3.4.5" with the GCC |
363 |
version and CHOST settings you've upgraded to:)</comment> |
364 |
# <i>gcc-config i686-pc-linux-gnu-3.4.5</i> |
365 |
# <i>source /etc/profile</i> |
366 |
|
367 |
<comment>(Rebuilding libtool)</comment> |
368 |
# <i>emerge --oneshot -av libtool</i> |
369 |
</pre> |
370 |
|
371 |
<p> |
372 |
To provide compatibility with older binary C++ applications, |
373 |
<c>sys-libs/libstdc++-v3</c> needs to be merged onto your system. |
374 |
</p> |
375 |
|
376 |
<pre caption="Installing libstdc++-v3"> |
377 |
# <i>emerge --oneshot sys-libs/libstdc++-v3</i> |
378 |
</pre> |
379 |
|
380 |
</body> |
381 |
</section> |
382 |
|
383 |
<section id="first-install-revdep-rebuild"> |
384 |
<title>Using revdep-rebuild</title> |
385 |
<body> |
386 |
|
387 |
<p> |
388 |
This method requires that you first install <c>gentoolkit</c> if you have not |
389 |
already done so. We will then run <c>revdep-rebuild</c> to actually scan the |
390 |
installed packages for ones we need to rebuild, then rebuild them. |
391 |
</p> |
392 |
|
393 |
<pre caption="Installing gentoolkit and running revdep-rebuild"> |
394 |
# <i>emerge -an gentoolkit</i> |
395 |
# <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i> |
396 |
# <i>revdep-rebuild --library libstdc++.so.5</i> |
397 |
</pre> |
398 |
|
399 |
<note> |
400 |
It is possible that you might have problems with non-existing package versions |
401 |
due to them being outdated or masked. If this is the case, you will want to use |
402 |
the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages |
403 |
to be recompiled based on the package name, rather than the exact name and |
404 |
version. |
405 |
</note> |
406 |
|
407 |
</body> |
408 |
</section> |
409 |
<section id="first-install-emerge-e"> |
410 |
<title>Using emerge -e</title> |
411 |
<body> |
412 |
|
413 |
<p> |
414 |
This method, while much slower, will rebuild the system target to ensure that |
415 |
everything has been rebuilt with your new compiler. This is not necessary, but |
416 |
is valid if you are also making changes to CFLAGS or other make.conf variables |
417 |
that will affect the system compile. |
418 |
</p> |
419 |
|
420 |
<p> |
421 |
Since we are performing these actions after an initial installation, we do not |
422 |
need to recompile the <c>world</c> target as we would when doing an upgrade on |
423 |
an already installed system. However, you may choose to perform a world update |
424 |
in place of the system update, to ensure that all packages are updated. |
425 |
</p> |
426 |
|
427 |
<pre caption="Rebuilding system"> |
428 |
# <i>emerge -e system</i> |
429 |
</pre> |
430 |
|
431 |
</body> |
432 |
</section> |
433 |
<section id="first-install-cleaning-up"> |
434 |
<title>Cleaning up</title> |
435 |
<body> |
436 |
|
437 |
<p> |
438 |
It is also safe to remove older GCC versions at this time. Please substitute |
439 |
<c>YOUR-NEW-GCC-VERSION</c> with the actual version you've upgraded to: |
440 |
</p> |
441 |
|
442 |
<pre caption="Cleaning up"> |
443 |
# <i>emerge -aC "<sys-devel/gcc-YOUR-NEW-GCC-VERSION"</i> |
444 |
</pre> |
445 |
|
446 |
</body> |
447 |
</section> |
448 |
</chapter> |
449 |
|
450 |
<chapter id="common-pitfalls"> |
451 |
<title>Common Pitfalls</title> |
452 |
<section> |
453 |
<body> |
454 |
|
455 |
<p> |
456 |
It's important to disable <c>distcc</c> during upgrade. Mixing compiler versions |
457 |
on your nodes <e>will</e> cause build issues. This is not required for ccache, |
458 |
as the cache objects will be invalidated anyway. |
459 |
</p> |
460 |
|
461 |
<p> |
462 |
Always use same GCC version for your kernel and additional kernel modules. Once |
463 |
you rebuild your world with new GCC, external modules (like |
464 |
<c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your |
465 |
kernel with the new GCC to fix that. |
466 |
</p> |
467 |
|
468 |
<p> |
469 |
If you're upgrading on a SPARC machine, make sure to rerun <c>silo -f</c> after |
470 |
re-emerging world to avoid possible issues. |
471 |
</p> |
472 |
|
473 |
</body> |
474 |
</section> |
475 |
<section> |
476 |
<title>Frequent Error Messages</title> |
477 |
<body> |
478 |
|
479 |
<p> |
480 |
If your system complains about something like <e>libtool: link: |
481 |
`/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool |
482 |
archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute |
483 |
"3.3.6" with the version numbers from the error message). |
484 |
</p> |
485 |
|
486 |
<p> |
487 |
If you see <e>error: /usr/bin/gcc-config: line 632: |
488 |
/etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try |
489 |
deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running |
490 |
<c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this |
491 |
if you do not have any cross-compilers set up, though. |
492 |
</p> |
493 |
|
494 |
<p> |
495 |
If a package fails during <c>emerge -e system</c> or <c>emerge -e world</c>, |
496 |
you can resume operation with <c>emerge --resume</c>. If a package fails |
497 |
repeatedly, skip it with <c>emerge --resume --skipfirst</c>. Don't run any |
498 |
other instances of emerge in between or you will lose the resume information. |
499 |
</p> |
500 |
|
501 |
<p> |
502 |
If you get an error message <e>spec failure: unrecognized spec option</e> while |
503 |
upgrading your compiler, try to switch back to your default compiler, unset the |
504 |
<c>GCC_SPECS</c> variable and upgrade GCC again: |
505 |
</p> |
506 |
|
507 |
<pre caption="Restoring primary specs"> |
508 |
# <i>gcc-config 1</i> |
509 |
# <i>source /etc/profile</i> |
510 |
# <i>unset GCC_SPECS</i> |
511 |
# <i>emerge -uav gcc</i> |
512 |
</pre> |
513 |
|
514 |
</body> |
515 |
</section> |
516 |
</chapter> |
517 |
</guide> |