/[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.14 - (hide annotations) (download) (as text)
Thu Aug 31 00:08:57 2006 UTC (7 years, 7 months ago) by nightmorph
Branch: MAIN
Changes since 1.13: +37 -21 lines
File MIME type: application/xml
Updated gcc guide for bug 145014, thanks to amne for the updates

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

  ViewVC Help
Powered by ViewVC 1.1.20