/[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.8 - (show annotations) (download) (as text)
Thu Feb 9 16:15:21 2006 UTC (8 years, 2 months ago) by jkt
Branch: MAIN
Changes since 1.7: +65 -65 lines
File MIME type: application/xml
Moving the "common-pitfalls" section to the end of the document

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.7 2006/02/09 16:06:51 jkt Exp $ -->
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
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 <version>7</version>
29 <date>2006-02-09</date>
30
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 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 </p>
62
63 <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 </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 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 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 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 <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 <title>Upgrading from GCC-3.3 to 3.4 or greater</title>
146 <section>
147 <title>Introduction</title>
148 <body>
149
150 <p>
151 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 </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 <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 <p>
170 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 entire system from scratch so it will make use of new GCC features. It's up to
175 you to decide which of these two ways you will choose. In most cases, the first
176 method is sufficient.
177 </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 will also rebuild the <c>libtool</c> package to ensure that toolchain is in
189 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 <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
402 <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 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 </p>
435
436 <pre caption="Cleaning up">
437 # <i>emerge -aC "&lt;sys-devel/gcc-YOUR-NEW-GCC-VERSION"</i>
438 </pre>
439
440 </body>
441 </section>
442 </chapter>
443
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 </body>
463 </section>
464 <section>
465 <title>Frequent Error Messages</title>
466 <body>
467
468 <p>
469 If your system complains about something like <e>libtool: link:
470 `/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool
471 archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute
472 "3.3.6" with the version numbers from the error message).
473 </p>
474
475 <p>
476 If you see the <e>error: /usr/bin/gcc-config: line 632:
477 /etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try
478 deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running
479 <c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this if
480 you do not have any cross-compilers set up, though.
481 </p>
482
483 <p>
484 If a package fails during <c>emerge -e system</c> or <c>emerge -e world</c>,
485 you can resume operation with <c>emerge --resume</c>. If a package fails
486 repeatedly, skip it with <c>emerge --resume --skipfirst</c>. Don't run any
487 other instances of emerge in between or you will lose the resume information.
488 </p>
489
490 <p>
491 If you get an error message <e>spec failure: unrecognized spec option</e> while
492 upgrading your compiler, try to switch back to your default compiler, unset the
493 <c>GCC_SPECS</c> variable and upgrade GCC again:
494 </p>
495
496 <pre caption="Restoring primary specs">
497 # <i>gcc-config 1</i>
498 # <i>source /etc/profile</i>
499 # <i>unset GCC_SPECS</i>
500 # <i>emerge -uav gcc</i>
501 </pre>
502
503 </body>
504 </section>
505 </chapter>
506 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20