/[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.13 - (hide annotations) (download) (as text)
Fri May 26 20:45:35 2006 UTC (8 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.12: +8 -9 lines
File MIME type: application/xml
Updated gcc upgrading guide as per Halcy0n's request

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

  ViewVC Help
Powered by ViewVC 1.1.20