/[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.14 - (show annotations) (download) (as text)
Thu Aug 31 00:08:57 2006 UTC (8 years ago) by nightmorph
Branch: MAIN
Changes since 1.13: +37 -21 lines
File MIME type: application/xml
Updated gcc guide for bug 145014, thanks to amne for the updates

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

  ViewVC Help
Powered by ViewVC 1.1.20