/[gentoo]/xml/htdocs/doc/en/gcc-upgrading.xml
Gentoo

Contents of /xml/htdocs/doc/en/gcc-upgrading.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.26 - (hide annotations) (download) (as text)
Mon Apr 2 23:13:45 2007 UTC (7 years, 8 months ago) by jkt
Branch: MAIN
Changes since 1.25: +5 -5 lines
File MIME type: application/xml
Kernels 2.4.34+ can be compiled by gcc-4.1. Reported by Gilles Espinasse <g.esp@free.fr>, forwarded by halcy0n.

1 jkt 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 jkt 1.26 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.25 2006/10/06 17:41:37 nightmorph Exp $ -->
3 jkt 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6     <guide link="/doc/en/gcc-upgrading.xml">
7 vapier 1.19 <title>Gentoo GCC Upgrade Guide</title>
8 jkt 1.1
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 rane 1.20 <mail link="mark@halcy0n.com">Mark Loeser</mail>
17 jkt 1.1 </author>
18    
19     <abstract>
20     This document will guide the user through the process of upgrading GCC on their
21 vapier 1.19 Gentoo machines.
22 jkt 1.1 </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 jkt 1.26 <version>22</version>
29     <date>2007-04-03</date>
30 jkt 1.1
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 vapier 1.15 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 jkt 1.1 </p>
55    
56     <p>
57     This guide will document the necessary steps required to perform a seamless
58 neysx 1.6 upgrade of the compiler used by your Gentoo box. A specific section is
59 jkt 1.21 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 neysx 1.6 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 jkt 1.1 </p>
64    
65 nightmorph 1.13 <warn>
66 jkt 1.23 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 jkt 1.18 instructions</uri>, as GCC-3.4 and GCC-4.1 use slightly different ABIs.
69 nightmorph 1.13 </warn>
70 neysx 1.6
71 jkt 1.1 </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 jkt 1.21 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 neysx 1.6 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 jkt 1.1 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 nightmorph 1.14 <comment>(Please substitute "i686-pc-linux-gnu-4.1.1" with the GCC
113 jkt 1.1 version and CHOST settings you've upgraded to:)</comment>
114 nightmorph 1.14 # <i>gcc-config i686-pc-linux-gnu-4.1.1</i>
115 nightmorph 1.25 # <i>env-update &amp;&amp; source /etc/profile</i>
116 jkt 1.1
117 nightmorph 1.14 <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 jkt 1.1 <comment>(Rebuilding libtool)</comment>
122     # <i>emerge --oneshot -av libtool</i>
123     </pre>
124    
125     <p>
126 nightmorph 1.14 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 jkt 1.1 </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 neysx 1.6 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 nightmorph 1.14 <c>=sys-devel/gcc-3.4*</c> with the version you want to uninstall):
139 jkt 1.1 </p>
140    
141     <pre caption="Removing older GCC version">
142 nightmorph 1.14 # <i>emerge -aC =sys-devel/gcc-3.4*</i>
143 jkt 1.1 </pre>
144    
145 jkt 1.18 <impo>
146 jkt 1.26 Please note that the GCC 4.1 and newer can compile only kernels newer than
147     2.4.34. Don't remove your old GCC version if you want to use an older kernel.
148 jkt 1.18 </impo>
149    
150 jkt 1.23 <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 jkt 1.24 sys-libs/libstdc++-v3</c> to provide compatibility with older binary C++
153 jkt 1.23 applications.
154     </impo>
155    
156 jkt 1.1 </body>
157     </section>
158     </chapter>
159    
160     <chapter id="upgrade-3.3-to-3.4">
161 jkt 1.21 <title>Upgrading from GCC-3.3 to 3.4</title>
162 jkt 1.1 <section>
163     <title>Introduction</title>
164     <body>
165    
166     <p>
167 jkt 1.23 The upgrade from GCC-3.3 to 3.4 is not seamless as the C++ ABI
168 neysx 1.6 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 jkt 1.1 </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 jkt 1.5 <impo>
179 jkt 1.18 If you upgrade from gcc 3.4 to 4.1, please consult the <uri
180     link="#upgrade-general">General Update instructions</uri>.
181 nightmorph 1.14 </impo>
182    
183     <impo>
184 jkt 1.5 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 jkt 1.1 <p>
191 nightmorph 1.14 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 jkt 1.22 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 nightmorph 1.14 revdep-rebuild, but do a <uri link="#upgrade-3.3-to-3.4-emerge-e">complete
204     system rebuild</uri>.
205 jkt 1.1 </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 jkt 1.3 will also rebuild the <c>libtool</c> package to ensure that toolchain is in
217 jkt 1.1 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 vanquirius 1.11 <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 jkt 1.1 # <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 vanquirius 1.11 <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 jkt 1.1 # <i>source /etc/profile</i>
280    
281 nightmorph 1.14 <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 jkt 1.1 <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 neysx 1.6 <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 jkt 1.21 The following example is for a GCC-3.3 to 3.4 upgrade. Certain parts
335 neysx 1.6 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 vanquirius 1.11 <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 neysx 1.6 # <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 jkt 1.10 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 neysx 1.6 </p>
426    
427     <pre caption="Rebuilding system">
428     # <i>emerge -e system</i>
429     </pre>
430    
431 jkt 1.10 </body>
432     </section>
433     <section id="first-install-cleaning-up">
434     <title>Cleaning up</title>
435     <body>
436    
437 neysx 1.6 <p>
438 jkt 1.7 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 neysx 1.6 </p>
441    
442     <pre caption="Cleaning up">
443 jkt 1.7 # <i>emerge -aC "&lt;sys-devel/gcc-YOUR-NEW-GCC-VERSION"</i>
444 neysx 1.6 </pre>
445    
446     </body>
447     </section>
448 jkt 1.1 </chapter>
449 jkt 1.8
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 nightmorph 1.14 <c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your
465     kernel with the new GCC to fix that.
466 jkt 1.8 </p>
467    
468 jkt 1.9 <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 jkt 1.8 </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 nightmorph 1.14 If you see <e>error: /usr/bin/gcc-config: line 632:
488 jkt 1.8 /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 nightmorph 1.14 <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 jkt 1.8 </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 jkt 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20