/[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.5 - (hide annotations) (download) (as text)
Mon Jan 30 15:32:52 2006 UTC (8 years, 9 months ago) by jkt
Branch: MAIN
Changes since 1.4: +10 -3 lines
File MIME type: application/xml
#120164: add a warning about migrating from 3.3 to 3.4 on SPARC

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

  ViewVC Help
Powered by ViewVC 1.1.20