/[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.27 - (show annotations) (download) (as text)
Mon May 19 21:02:24 2008 UTC (5 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.26: +4 -4 lines
File MIME type: application/xml
Coding style

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

  ViewVC Help
Powered by ViewVC 1.1.20