/[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.28 - (show annotations) (download) (as text)
Sun Jul 20 00:34:37 2008 UTC (6 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.27: +17 -8 lines
File MIME type: application/xml
updated gcc upgrading and changing chost guides for bug 232193: the location of fix_libtool_files.sh has changed.

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

  ViewVC Help
Powered by ViewVC 1.1.20