/[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.17 - (hide annotations) (download) (as text)
Mon Sep 4 20:48:18 2006 UTC (8 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.16: +4 -4 lines
File MIME type: application/xml
halcy0n is retired; updated email address

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

  ViewVC Help
Powered by ViewVC 1.1.20