/[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.9 - (hide annotations) (download) (as text)
Thu Feb 9 17:40:19 2006 UTC (8 years, 7 months ago) by jkt
Branch: MAIN
Changes since 1.8: +7 -2 lines
File MIME type: application/xml
#120164, mention the need to re-run SILO

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

  ViewVC Help
Powered by ViewVC 1.1.20