/[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.1 - (hide annotations) (download) (as text)
Thu Dec 8 19:21:13 2005 UTC (8 years, 9 months ago) by jkt
Branch: MAIN
File MIME type: application/xml
New generic GCC upgrading guide, replacement of gentoo/xml/htdocs/proj/en/base/x86/gcc-upgrading-guide.xml

1 jkt 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!-- $Header$ -->
3    
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     <author title="Editor">
19     <mail link="wolf31o2@gentoo.org">Chris Gianelloni</mail>
20     </author>
21    
22    
23     <abstract>
24     This document will guide the user through the process of upgrading GCC on their
25     Gentoo Linux machines.
26     </abstract>
27    
28     <!-- The content of this document is licensed under the CC-BY-SA license -->
29     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
30     <license/>
31    
32     <version>1</version>
33     <date>2005-12-08</date>
34    
35     <chapter id="intro">
36     <title>Introduction</title>
37     <section>
38     <title>GCC Upgrading</title>
39     <body>
40    
41     <p>
42     Why should you upgrade? Well, GCC is quite similar to any other package on your
43     system, just a bit more critical. You should upgrade GCC whenever a new version
44     fixes some bug that annoys you, new functionality you need is introduced, or if
45     you want to keep your system up-to-date. If none of the previous cases apply to
46     you, you can safely postpone upgrade as long as your GCC version is supported by
47     Gentoo developers.
48     </p>
49    
50     <p>
51     If you install a newer version of GCC, the system will not switch over to use it
52     automatically. You'll have to explicitly request the change because the
53     migration process might require some additional steps. If you decide not to
54     switch, Portage will continue to use older version of your compiler until you
55     change your mind, or remove the old compiler from the system.
56     </p>
57    
58     <p>
59     This guide will document the necessary steps required to perform a seamless
60     upgrade of the compiler used by your Gentoo box. A specific section is dedicated
61     to the <uri link="#upgrade-3.3-to-3.4">upgrade from GCC 3.3 to the 3.4
62     version</uri> and issues with <c>libstdc++</c>.
63     </p>
64    
65     </body>
66     </section>
67     </chapter>
68    
69     <chapter id="upgrade-general">
70     <title>General Upgrade Instructions</title>
71     <section>
72     <title>Introduction</title>
73     <body>
74    
75     <impo>
76     If you're looking for instructions specific to upgrades from GCC-3.3 to
77     GCC-3.4, please consult the <uri link="#upgrade-3.3-to-3.4">dedicated
78     section</uri>.
79     </impo>
80    
81     <p>
82     Generally speaking, upgrades to <e>bug fix releases</e>, like from 3.3.5 to
83     3.3.6, should be quite safe -- just emerge new version, switch your system to
84     use it and rebuild the only affected package, <c>libtool</c>. However, some GCC
85     upgrades break binary compatibility; in such cases a rebuild of the affected
86     packages (or even whole toolchain and system) might be required.
87     </p>
88    
89     <p>
90     When we spoke about the need to switch your compiler to the newer version by
91     hand, we said it won't happen automatically. However, there is one exception --
92     upgrades to bug fix releases, like from 3.3.5 to 3.3.6 in case you don't use the
93     "multislot" feature allowing them to coexist on one system. Multislot is
94     disabled by default as the majority of users won't benefit from it.
95     </p>
96    
97     <pre caption="Upgrading GCC">
98     # <i>emerge -uav gcc</i>
99    
100     <comment>(Please substitute "i686-pc-linux-gnu-3.4.4" with the GCC
101     version and CHOST settings you've upgraded to:)</comment>
102     # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
103     # <i>source /etc/profile</i>
104    
105     <comment>(Rebuilding libtool)</comment>
106     # <i>emerge --oneshot -av libtool</i>
107     </pre>
108    
109     <p>
110     Now let's rebuild toolchain and then world so we will make use of the new
111     compiler.
112     </p>
113    
114     <pre caption="Rebuilding system">
115     # <i>emerge -eav system</i>
116     # <i>emerge -eav world</i>
117     </pre>
118    
119     <p>
120     It is safe to remove older GCC version at this time. If you feel the
121     need, please issue the following command (as usual, substitute
122     <c>=sys-devel/gcc-3.3*</c> with the version you want to uninstall):
123     </p>
124    
125     <pre caption="Removing older GCC version">
126     # <i>emerge -aC =sys-devel/gcc-3.3*</i>
127     </pre>
128    
129     </body>
130     </section>
131     </chapter>
132    
133     <chapter id="upgrade-3.3-to-3.4">
134     <title>Upgrading from GCC-3.3 to 3.4</title>
135     <section>
136     <title>Introduction</title>
137     <body>
138    
139     <p>
140     The upgrade from GCC/3.3 to 3.4 is not so seamless as the C++ ABI changed
141     between these two versions so there is an issue with <c>libstdc++</c> library
142     which must be taken care of as well.
143     </p>
144    
145     </body>
146     </section>
147     <section id="upgrade-3.3-to-3.4-choices">
148     <title>The Choices</title>
149     <body>
150    
151     <p>
152     You have two possibilities on how to upgrade your system. <uri
153     link="#upgrade-3.3-to-3.4-revdep-rebuild">First method</uri> is faster and
154     requires use of <c>revdep-rebuild</c> tool from package <c>gentoolkit</c> while
155     the <uri link="#upgrade-3.3-to-3.4-emerge-e">second one</uri> rebuilds the
156     entire system from scratch so it will make use of new GCC features. It's up to
157     you to decide which of these two ways you will choose.
158     </p>
159    
160     </body>
161     </section>
162     <section id="upgrade-3.3-to-3.4-revdep-rebuild">
163     <title>Using revdep-rebuild</title>
164     <body>
165    
166     <p>
167     This method requires that you first install <c>gentoolkit</c> if you have not
168     already done so. Then we will upgrade GCC and switch to the new compiler. We
169     will also rebuild the <c>libtool</c> package to ensurethat toolchain is in
170     healthy state.
171     </p>
172    
173     <pre caption="Installing gentoolkit and upgrading GCC">
174     # <i>emerge -an gentoolkit</i>
175     # <i>emerge -uav gcc</i>
176     # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
177     # <i>source /etc/profile</i>
178    
179     <comment>(Rebuilding libtool)</comment>
180     # <i>emerge --oneshot -av libtool</i>
181     </pre>
182    
183     <note>
184     This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are
185     using another CHOST, please use the appropriate gcc-config line.
186     </note>
187    
188     <p>
189     Now, we want to see which packages that revdep-rebuild will want to rebuild.
190     Then we will tell revdep-rebuild to actually rebuild the packages. This may take
191     some time, so have some patience.
192     </p>
193    
194     <pre caption="Using revdep-rebuild">
195     # <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i>
196     # <i>revdep-rebuild --library libstdc++.so.5</i>
197     </pre>
198    
199     <note>
200     It is possible that you might have problems with non-existing package versions
201     due to them being outdated or masked. If this is the case, you will want to use
202     the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages
203     to be recompiled based on the package name, rather than the exact name and
204     version.
205     </note>
206    
207     <p>
208     To provide compatibility with older binary C++ applications and any packages
209     that revdep-rebuild might have missed, <c>sys-libs/libstdc++-v3</c> needs to be
210     merged before you unmerge GCC 3.3 from your system.
211     </p>
212    
213     <pre caption="Installing libstdc++-v3 and cleaning up">
214     # <i>emerge --oneshot sys-libs/libstdc++-v3</i>
215     # <i>emerge -aC =sys-devel/gcc-3.3*</i>
216     </pre>
217    
218     </body>
219     </section>
220     <section id="upgrade-3.3-to-3.4-emerge-e">
221     <title>Using emerge -e</title>
222     <body>
223    
224     <p>
225     This method, while much slower, will rebuild your whole system to ensure that
226     everything has been rebuilt with your new compiler, and therefore safer. At
227     first, you will upgrade GCC and libtool and switch to your new compiler.
228     </p>
229    
230     <pre caption="Upgrading GCC">
231     # <i>emerge -uav gcc</i>
232     # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
233     # <i>source /etc/profile</i>
234    
235     <comment>(Rebuilding libtool)</comment>
236     # <i>emerge --oneshot -av libtool</i>
237     </pre>
238    
239     <note>
240     This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are
241     using another CHOST, please use the appropriate gcc-config line.
242     </note>
243    
244     <p>
245     To provide compatibility with older binary C++ applications,
246     <c>sys-libs/libstdc++-v3</c> needs to be merged onto your system.
247     </p>
248    
249     <pre caption="Installing libstdc++-v3">
250     # <i>emerge --oneshot sys-libs/libstdc++-v3</i>
251     </pre>
252    
253     <p>
254     Now we will go about first rebuilding the system target, then the world target.
255     This will take a very long time, depending on the number of packages that you
256     have installed, as it will rebuild your entire toolchain and supporting system
257     files, followed by every package on your system, including the toolchain. This
258     is necessary to ensure that all packages have been compiled with the new
259     toolchain, including the toolchain itself.
260     </p>
261    
262     <pre caption="Rebuilding system and world">
263     # <i>emerge -e system</i>
264     # <i>emerge -e world</i>
265     </pre>
266    
267     <p>
268     It is also safe to remove older GCC versions at this time:
269     </p>
270    
271     <pre caption="Cleaning up">
272     # <i>emerge -aC =sys-devel/gcc-3.3*</i>
273     </pre>
274    
275     </body>
276     </section>
277     </chapter>
278    
279     <chapter id="common-pittfalls">
280     <title>Common Pittfalls</title>
281     <section>
282     <body>
283    
284     <p>
285     It's important to disable <c>distcc</c> during upgrade. Mixing compiler versions
286     on your nodes <e>will</e> cause build issues. This is not required for ccache,
287     as the cache objects will be invalidated anyway.
288     </p>
289    
290     <p>
291     Always use same GCC version for your kernel and additional kernel modules. Once
292     you rebuild your world with new GCC, external modules (like
293     <c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your kernel
294     with new GCC to fix that.
295     </p>
296    
297     </body>
298     </section>
299     <section>
300     <title>Frequent Error Messages</title>
301     <body>
302    
303     <p>
304     If your system complains about something like <e>libtool: link:
305     `/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool
306     archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute
307     "3.3.6" with the version numbers from the error message).
308     </p>
309    
310     <p>
311     If you see the <e>error: /usr/bin/gcc-config: line 632:
312     /etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try
313     deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running
314     <c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this if
315     you do not have any cross-compilers set up, though.
316     </p>
317    
318     <p>
319     If a package fails during <c>emerge -e system/world</c>, you can resume
320     operation with <c>emerge --resume</c>. If a package fails repeatedly, skip it
321     with <c>emerge --resume --skipfirst</c>. Don't run any other instances of emerge
322     in between or you will lose the resume information.
323     </p>
324    
325     <p>
326     If you get an error message <e>spec failure: unrecognized spec option</e> while
327     upgrading your compiler, try to switch back to your default compiler, unset the
328     <c>GCC_SPECS</c> variable and upgrade GCC again:
329     </p>
330    
331     <pre caption="Restoring primary specs">
332     # <i>gcc-config 1</i>
333     # <i>source /etc/profile</i>
334     # <i>unset GCC_SPECS</i>
335     # <i>emerge -uav gcc</i>
336     </pre>
337    
338     </body>
339     </section>
340    
341     </chapter>
342     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20