/[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.29 - (hide annotations) (download) (as text)
Sun Aug 3 03:35:11 2008 UTC (6 years ago) by nightmorph
Branch: MAIN
Changes since 1.28: +2 -3 lines
File MIME type: application/xml
grammar fix; no content change

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

  ViewVC Help
Powered by ViewVC 1.1.20