/[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.29 - (show annotations) (download) (as text)
Sun Aug 3 03:35:11 2008 UTC (5 years, 8 months ago) by nightmorph
Branch: MAIN
Changes since 1.28: +2 -3 lines
File MIME type: application/xml
grammar fix; no content change

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

  ViewVC Help
Powered by ViewVC 1.1.20