/[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.4 - (show annotations) (download) (as text)
Wed Dec 14 20:03:44 2005 UTC (8 years, 7 months ago) by jkt
Branch: MAIN
Changes since 1.3: +2 -5 lines
File MIME type: application/xml
Removing wolf31o2 per his request

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.3 2005/12/12 15:41:26 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
20 <abstract>
21 This document will guide the user through the process of upgrading GCC on their
22 Gentoo Linux machines.
23 </abstract>
24
25 <!-- The content of this document is licensed under the CC-BY-SA license -->
26 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
27 <license/>
28
29 <version>3</version>
30 <date>2005-12-08</date>
31
32 <chapter id="intro">
33 <title>Introduction</title>
34 <section>
35 <title>GCC Upgrading</title>
36 <body>
37
38 <p>
39 Why should you upgrade? Well, GCC is quite similar to any other package on your
40 system, just a bit more critical. You should upgrade GCC whenever a new version
41 fixes some bug that annoys you, new functionality you need is introduced, or if
42 you want to keep your system up-to-date. If none of the previous cases apply to
43 you, you can safely postpone upgrade as long as your GCC version is supported by
44 Gentoo developers.
45 </p>
46
47 <p>
48 If you install a newer version of GCC, the system will not switch over to use it
49 automatically. You'll have to explicitly request the change because the
50 migration process might require some additional steps. If you decide not to
51 switch, Portage will continue to use older version of your compiler until you
52 change your mind, or remove the old compiler from the system.
53 </p>
54
55 <p>
56 This guide will document the necessary steps required to perform a seamless
57 upgrade of the compiler used by your Gentoo box. A specific section is dedicated
58 to the <uri link="#upgrade-3.3-to-3.4">upgrade from GCC 3.3 to the 3.4
59 version</uri> and issues with <c>libstdc++</c>.
60 </p>
61
62 </body>
63 </section>
64 </chapter>
65
66 <chapter id="upgrade-general">
67 <title>General Upgrade Instructions</title>
68 <section>
69 <title>Introduction</title>
70 <body>
71
72 <impo>
73 If you're looking for instructions specific to upgrades from GCC-3.3 to
74 GCC-3.4, please consult the <uri link="#upgrade-3.3-to-3.4">dedicated
75 section</uri>.
76 </impo>
77
78 <p>
79 Generally speaking, upgrades to <e>bug fix releases</e>, like from 3.3.5 to
80 3.3.6, should be quite safe -- just emerge new version, switch your system to
81 use it and rebuild the only affected package, <c>libtool</c>. However, some GCC
82 upgrades break binary compatibility; in such cases a rebuild of the affected
83 packages (or even whole toolchain and system) might be required.
84 </p>
85
86 <p>
87 When we spoke about the need to switch your compiler to the newer version by
88 hand, we said it won't happen automatically. However, there is one exception --
89 upgrades to bug fix releases, like from 3.3.5 to 3.3.6 in case you don't use the
90 "multislot" feature allowing them to coexist on one system. Multislot is
91 disabled by default as the majority of users won't benefit from it.
92 </p>
93
94 <pre caption="Upgrading GCC">
95 # <i>emerge -uav gcc</i>
96
97 <comment>(Please substitute "i686-pc-linux-gnu-3.4.4" with the GCC
98 version and CHOST settings you've upgraded to:)</comment>
99 # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
100 # <i>source /etc/profile</i>
101
102 <comment>(Rebuilding libtool)</comment>
103 # <i>emerge --oneshot -av libtool</i>
104 </pre>
105
106 <p>
107 Now let's rebuild toolchain and then world so we will make use of the new
108 compiler.
109 </p>
110
111 <pre caption="Rebuilding system">
112 # <i>emerge -eav system</i>
113 # <i>emerge -eav world</i>
114 </pre>
115
116 <p>
117 It is safe to remove older GCC version at this time. If you feel the
118 need, please issue the following command (as usual, substitute
119 <c>=sys-devel/gcc-3.3*</c> with the version you want to uninstall):
120 </p>
121
122 <pre caption="Removing older GCC version">
123 # <i>emerge -aC =sys-devel/gcc-3.3*</i>
124 </pre>
125
126 </body>
127 </section>
128 </chapter>
129
130 <chapter id="upgrade-3.3-to-3.4">
131 <title>Upgrading from GCC-3.3 to 3.4</title>
132 <section>
133 <title>Introduction</title>
134 <body>
135
136 <p>
137 The upgrade from GCC/3.3 to 3.4 is not so seamless as the C++ ABI changed
138 between these two versions so there is an issue with <c>libstdc++</c> library
139 which must be taken care of as well.
140 </p>
141
142 </body>
143 </section>
144 <section id="upgrade-3.3-to-3.4-choices">
145 <title>The Choices</title>
146 <body>
147
148 <p>
149 You have two possibilities on how to upgrade your system. <uri
150 link="#upgrade-3.3-to-3.4-revdep-rebuild">First method</uri> is faster and
151 requires use of <c>revdep-rebuild</c> tool from package <c>gentoolkit</c> while
152 the <uri link="#upgrade-3.3-to-3.4-emerge-e">second one</uri> rebuilds the
153 entire system from scratch so it will make use of new GCC features. It's up to
154 you to decide which of these two ways you will choose.
155 </p>
156
157 </body>
158 </section>
159 <section id="upgrade-3.3-to-3.4-revdep-rebuild">
160 <title>Using revdep-rebuild</title>
161 <body>
162
163 <p>
164 This method requires that you first install <c>gentoolkit</c> if you have not
165 already done so. Then we will upgrade GCC and switch to the new compiler. We
166 will also rebuild the <c>libtool</c> package to ensure that toolchain is in
167 healthy state.
168 </p>
169
170 <pre caption="Installing gentoolkit and upgrading GCC">
171 # <i>emerge -an gentoolkit</i>
172 # <i>emerge -uav gcc</i>
173 # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
174 # <i>source /etc/profile</i>
175
176 <comment>(Rebuilding libtool)</comment>
177 # <i>emerge --oneshot -av libtool</i>
178 </pre>
179
180 <note>
181 This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are
182 using another CHOST, please use the appropriate gcc-config line.
183 </note>
184
185 <p>
186 Now, we want to see which packages that revdep-rebuild will want to rebuild.
187 Then we will tell revdep-rebuild to actually rebuild the packages. This may take
188 some time, so have some patience.
189 </p>
190
191 <pre caption="Using revdep-rebuild">
192 # <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i>
193 # <i>revdep-rebuild --library libstdc++.so.5</i>
194 </pre>
195
196 <note>
197 It is possible that you might have problems with non-existing package versions
198 due to them being outdated or masked. If this is the case, you will want to use
199 the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages
200 to be recompiled based on the package name, rather than the exact name and
201 version.
202 </note>
203
204 <p>
205 To provide compatibility with older binary C++ applications and any packages
206 that revdep-rebuild might have missed, <c>sys-libs/libstdc++-v3</c> needs to be
207 merged before you unmerge GCC 3.3 from your system.
208 </p>
209
210 <pre caption="Installing libstdc++-v3 and cleaning up">
211 # <i>emerge --oneshot sys-libs/libstdc++-v3</i>
212 # <i>emerge -aC =sys-devel/gcc-3.3*</i>
213 </pre>
214
215 </body>
216 </section>
217 <section id="upgrade-3.3-to-3.4-emerge-e">
218 <title>Using emerge -e</title>
219 <body>
220
221 <p>
222 This method, while much slower, will rebuild your whole system to ensure that
223 everything has been rebuilt with your new compiler, and therefore safer. At
224 first, you will upgrade GCC and libtool and switch to your new compiler.
225 </p>
226
227 <pre caption="Upgrading GCC">
228 # <i>emerge -uav gcc</i>
229 # <i>gcc-config i686-pc-linux-gnu-3.4.4</i>
230 # <i>source /etc/profile</i>
231
232 <comment>(Rebuilding libtool)</comment>
233 # <i>emerge --oneshot -av libtool</i>
234 </pre>
235
236 <note>
237 This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are
238 using another CHOST, please use the appropriate gcc-config line.
239 </note>
240
241 <p>
242 To provide compatibility with older binary C++ applications,
243 <c>sys-libs/libstdc++-v3</c> needs to be merged onto your system.
244 </p>
245
246 <pre caption="Installing libstdc++-v3">
247 # <i>emerge --oneshot sys-libs/libstdc++-v3</i>
248 </pre>
249
250 <p>
251 Now we will go about first rebuilding the system target, then the world target.
252 This will take a very long time, depending on the number of packages that you
253 have installed, as it will rebuild your entire toolchain and supporting system
254 files, followed by every package on your system, including the toolchain. This
255 is necessary to ensure that all packages have been compiled with the new
256 toolchain, including the toolchain itself.
257 </p>
258
259 <pre caption="Rebuilding system and world">
260 # <i>emerge -e system</i>
261 # <i>emerge -e world</i>
262 </pre>
263
264 <p>
265 It is also safe to remove older GCC versions at this time:
266 </p>
267
268 <pre caption="Cleaning up">
269 # <i>emerge -aC =sys-devel/gcc-3.3*</i>
270 </pre>
271
272 </body>
273 </section>
274 </chapter>
275
276 <chapter id="common-pitfalls">
277 <title>Common Pitfalls</title>
278 <section>
279 <body>
280
281 <p>
282 It's important to disable <c>distcc</c> during upgrade. Mixing compiler versions
283 on your nodes <e>will</e> cause build issues. This is not required for ccache,
284 as the cache objects will be invalidated anyway.
285 </p>
286
287 <p>
288 Always use same GCC version for your kernel and additional kernel modules. Once
289 you rebuild your world with new GCC, external modules (like
290 <c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your kernel
291 with new GCC to fix that.
292 </p>
293
294 </body>
295 </section>
296 <section>
297 <title>Frequent Error Messages</title>
298 <body>
299
300 <p>
301 If your system complains about something like <e>libtool: link:
302 `/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool
303 archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute
304 "3.3.6" with the version numbers from the error message).
305 </p>
306
307 <p>
308 If you see the <e>error: /usr/bin/gcc-config: line 632:
309 /etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try
310 deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running
311 <c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this if
312 you do not have any cross-compilers set up, though.
313 </p>
314
315 <p>
316 If a package fails during <c>emerge -e system/world</c>, you can resume
317 operation with <c>emerge --resume</c>. If a package fails repeatedly, skip it
318 with <c>emerge --resume --skipfirst</c>. Don't run any other instances of emerge
319 in between or you will lose the resume information.
320 </p>
321
322 <p>
323 If you get an error message <e>spec failure: unrecognized spec option</e> while
324 upgrading your compiler, try to switch back to your default compiler, unset the
325 <c>GCC_SPECS</c> variable and upgrade GCC again:
326 </p>
327
328 <pre caption="Restoring primary specs">
329 # <i>gcc-config 1</i>
330 # <i>source /etc/profile</i>
331 # <i>unset GCC_SPECS</i>
332 # <i>emerge -uav gcc</i>
333 </pre>
334
335 </body>
336 </section>
337
338 </chapter>
339 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20