/[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.28 - (hide annotations) (download) (as text)
Sun Jul 20 00:34:37 2008 UTC (6 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.27: +17 -8 lines
File MIME type: application/xml
updated gcc upgrading and changing chost guides for bug 232193: the location of fix_libtool_files.sh has changed.

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

  ViewVC Help
Powered by ViewVC 1.1.20