1 |
jkt 05/12/08 19:21:13 |
2 |
|
3 |
Added: xml/htdocs/doc/en gcc-upgrading.xml |
4 |
Log: |
5 |
New generic GCC upgrading guide, replacement of gentoo/xml/htdocs/proj/en/base/x86/gcc-upgrading-guide.xml |
6 |
|
7 |
Revision Changes Path |
8 |
1.1 xml/htdocs/doc/en/gcc-upgrading.xml |
9 |
|
10 |
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/gcc-upgrading.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo |
11 |
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/gcc-upgrading.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo |
12 |
|
13 |
Index: gcc-upgrading.xml |
14 |
=================================================================== |
15 |
<?xml version='1.0' encoding="UTF-8"?> |
16 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.1 2005/12/08 19:21:13 jkt Exp $ --> |
17 |
|
18 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
19 |
|
20 |
<guide link="/doc/en/gcc-upgrading.xml"> |
21 |
<title>Gentoo Linux GCC Upgrade Guide</title> |
22 |
|
23 |
<author title="Author"> |
24 |
<mail link="amne@g.o">Wernfried Haas</mail> |
25 |
</author> |
26 |
<author title="Author"> |
27 |
<mail link="jkt@g.o">Jan Kundrát</mail> |
28 |
</author> |
29 |
<author title="Editor"> |
30 |
<mail link="halcy0n@g.o">Mark Loeser</mail> |
31 |
</author> |
32 |
<author title="Editor"> |
33 |
<mail link="wolf31o2@g.o">Chris Gianelloni</mail> |
34 |
</author> |
35 |
|
36 |
|
37 |
<abstract> |
38 |
This document will guide the user through the process of upgrading GCC on their |
39 |
Gentoo Linux machines. |
40 |
</abstract> |
41 |
|
42 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
43 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
44 |
<license/> |
45 |
|
46 |
<version>1</version> |
47 |
<date>2005-12-08</date> |
48 |
|
49 |
<chapter id="intro"> |
50 |
<title>Introduction</title> |
51 |
<section> |
52 |
<title>GCC Upgrading</title> |
53 |
<body> |
54 |
|
55 |
<p> |
56 |
Why should you upgrade? Well, GCC is quite similar to any other package on your |
57 |
system, just a bit more critical. You should upgrade GCC whenever a new version |
58 |
fixes some bug that annoys you, new functionality you need is introduced, or if |
59 |
you want to keep your system up-to-date. If none of the previous cases apply to |
60 |
you, you can safely postpone upgrade as long as your GCC version is supported by |
61 |
Gentoo developers. |
62 |
</p> |
63 |
|
64 |
<p> |
65 |
If you install a newer version of GCC, the system will not switch over to use it |
66 |
automatically. You'll have to explicitly request the change because the |
67 |
migration process might require some additional steps. If you decide not to |
68 |
switch, Portage will continue to use older version of your compiler until you |
69 |
change your mind, or remove the old compiler from the system. |
70 |
</p> |
71 |
|
72 |
<p> |
73 |
This guide will document the necessary steps required to perform a seamless |
74 |
upgrade of the compiler used by your Gentoo box. A specific section is dedicated |
75 |
to the <uri link="#upgrade-3.3-to-3.4">upgrade from GCC 3.3 to the 3.4 |
76 |
version</uri> and issues with <c>libstdc++</c>. |
77 |
</p> |
78 |
|
79 |
</body> |
80 |
</section> |
81 |
</chapter> |
82 |
|
83 |
<chapter id="upgrade-general"> |
84 |
<title>General Upgrade Instructions</title> |
85 |
<section> |
86 |
<title>Introduction</title> |
87 |
<body> |
88 |
|
89 |
<impo> |
90 |
If you're looking for instructions specific to upgrades from GCC-3.3 to |
91 |
GCC-3.4, please consult the <uri link="#upgrade-3.3-to-3.4">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-3.4.4" with the GCC |
115 |
version and CHOST settings you've upgraded to:)</comment> |
116 |
# <i>gcc-config i686-pc-linux-gnu-3.4.4</i> |
117 |
# <i>source /etc/profile</i> |
118 |
|
119 |
<comment>(Rebuilding libtool)</comment> |
120 |
# <i>emerge --oneshot -av libtool</i> |
121 |
</pre> |
122 |
|
123 |
<p> |
124 |
Now let's rebuild toolchain and then world so we will make use of the new |
125 |
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 older GCC version at this time. If you feel the |
135 |
need, please issue the following command (as usual, substitute |
136 |
<c>=sys-devel/gcc-3.3*</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.3*</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</title> |
149 |
<section> |
150 |
<title>Introduction</title> |
151 |
<body> |
152 |
|
153 |
<p> |
154 |
The upgrade from GCC/3.3 to 3.4 is not so seamless as the C++ ABI changed |
155 |
between these two versions so there is an issue with <c>libstdc++</c> library |
156 |
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 |
<p> |
166 |
You have two possibilities on how to upgrade your system. <uri |
167 |
link="#upgrade-3.3-to-3.4-revdep-rebuild">First method</uri> is faster and |
168 |
requires use of <c>revdep-rebuild</c> tool from package <c>gentoolkit</c> while |
169 |
the <uri link="#upgrade-3.3-to-3.4-emerge-e">second one</uri> rebuilds the |
170 |
entire system from scratch so it will make use of new GCC features. It's up to |
171 |
you to decide which of these two ways you will choose. |
172 |
</p> |
173 |
|
174 |
</body> |
175 |
</section> |
176 |
<section id="upgrade-3.3-to-3.4-revdep-rebuild"> |
177 |
<title>Using revdep-rebuild</title> |
178 |
<body> |
179 |
|
180 |
<p> |
181 |
This method requires that you first install <c>gentoolkit</c> if you have not |
182 |
already done so. Then we will upgrade GCC and switch to the new compiler. We |
183 |
will also rebuild the <c>libtool</c> package to ensurethat toolchain is in |
184 |
healthy state. |
185 |
</p> |
186 |
|
187 |
<pre caption="Installing gentoolkit and upgrading GCC"> |
188 |
# <i>emerge -an gentoolkit</i> |
189 |
# <i>emerge -uav gcc</i> |
190 |
# <i>gcc-config i686-pc-linux-gnu-3.4.4</i> |
191 |
# <i>source /etc/profile</i> |
192 |
|
193 |
<comment>(Rebuilding libtool)</comment> |
194 |
# <i>emerge --oneshot -av libtool</i> |
195 |
</pre> |
196 |
|
197 |
<note> |
198 |
This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are |
199 |
using another CHOST, please use the appropriate gcc-config line. |
200 |
</note> |
201 |
|
202 |
<p> |
203 |
Now, we want to see which packages that revdep-rebuild will want to rebuild. |
204 |
Then we will tell revdep-rebuild to actually rebuild the packages. This may take |
205 |
some time, so have some patience. |
206 |
</p> |
207 |
|
208 |
<pre caption="Using revdep-rebuild"> |
209 |
# <i>revdep-rebuild --library libstdc++.so.5 -- -p -v</i> |
210 |
# <i>revdep-rebuild --library libstdc++.so.5</i> |
211 |
</pre> |
212 |
|
213 |
<note> |
214 |
It is possible that you might have problems with non-existing package versions |
215 |
due to them being outdated or masked. If this is the case, you will want to use |
216 |
the <c>--package-names</c> option to <c>revdep-rebuild</c>. This causes packages |
217 |
to be recompiled based on the package name, rather than the exact name and |
218 |
version. |
219 |
</note> |
220 |
|
221 |
<p> |
222 |
To provide compatibility with older binary C++ applications and any packages |
223 |
that revdep-rebuild might have missed, <c>sys-libs/libstdc++-v3</c> needs to be |
224 |
merged before you unmerge GCC 3.3 from your system. |
225 |
</p> |
226 |
|
227 |
<pre caption="Installing libstdc++-v3 and cleaning up"> |
228 |
# <i>emerge --oneshot sys-libs/libstdc++-v3</i> |
229 |
# <i>emerge -aC =sys-devel/gcc-3.3*</i> |
230 |
</pre> |
231 |
|
232 |
</body> |
233 |
</section> |
234 |
<section id="upgrade-3.3-to-3.4-emerge-e"> |
235 |
<title>Using emerge -e</title> |
236 |
<body> |
237 |
|
238 |
<p> |
239 |
This method, while much slower, will rebuild your whole system to ensure that |
240 |
everything has been rebuilt with your new compiler, and therefore safer. At |
241 |
first, you will upgrade GCC and libtool and switch to your new compiler. |
242 |
</p> |
243 |
|
244 |
<pre caption="Upgrading GCC"> |
245 |
# <i>emerge -uav gcc</i> |
246 |
# <i>gcc-config i686-pc-linux-gnu-3.4.4</i> |
247 |
# <i>source /etc/profile</i> |
248 |
|
249 |
<comment>(Rebuilding libtool)</comment> |
250 |
# <i>emerge --oneshot -av libtool</i> |
251 |
</pre> |
252 |
|
253 |
<note> |
254 |
This assumes that you have <c>CHOST="i686-pc-linux-gnu"</c> set. If you are |
255 |
using another CHOST, please use the appropriate gcc-config line. |
256 |
</note> |
257 |
|
258 |
<p> |
259 |
To provide compatibility with older binary C++ applications, |
260 |
<c>sys-libs/libstdc++-v3</c> needs to be merged onto your system. |
261 |
</p> |
262 |
|
263 |
<pre caption="Installing libstdc++-v3"> |
264 |
# <i>emerge --oneshot sys-libs/libstdc++-v3</i> |
265 |
</pre> |
266 |
|
267 |
<p> |
268 |
Now we will go about first rebuilding the system target, then the world target. |
269 |
This will take a very long time, depending on the number of packages that you |
270 |
have installed, as it will rebuild your entire toolchain and supporting system |
271 |
files, followed by every package on your system, including the toolchain. This |
272 |
is necessary to ensure that all packages have been compiled with the new |
273 |
toolchain, including the toolchain itself. |
274 |
</p> |
275 |
|
276 |
<pre caption="Rebuilding system and world"> |
277 |
# <i>emerge -e system</i> |
278 |
# <i>emerge -e world</i> |
279 |
</pre> |
280 |
|
281 |
<p> |
282 |
It is also safe to remove older GCC versions at this time: |
283 |
</p> |
284 |
|
285 |
<pre caption="Cleaning up"> |
286 |
# <i>emerge -aC =sys-devel/gcc-3.3*</i> |
287 |
</pre> |
288 |
|
289 |
</body> |
290 |
</section> |
291 |
</chapter> |
292 |
|
293 |
<chapter id="common-pittfalls"> |
294 |
<title>Common Pittfalls</title> |
295 |
<section> |
296 |
<body> |
297 |
|
298 |
<p> |
299 |
It's important to disable <c>distcc</c> during upgrade. Mixing compiler versions |
300 |
on your nodes <e>will</e> cause build issues. This is not required for ccache, |
301 |
as the cache objects will be invalidated anyway. |
302 |
</p> |
303 |
|
304 |
<p> |
305 |
Always use same GCC version for your kernel and additional kernel modules. Once |
306 |
you rebuild your world with new GCC, external modules (like |
307 |
<c>app-emulation/qemu-softmmu</c>) will fail to load. Please rebuild your kernel |
308 |
with new GCC to fix that. |
309 |
</p> |
310 |
|
311 |
</body> |
312 |
</section> |
313 |
<section> |
314 |
<title>Frequent Error Messages</title> |
315 |
<body> |
316 |
|
317 |
<p> |
318 |
If your system complains about something like <e>libtool: link: |
319 |
`/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.6/libstdc++.la' is not a valid libtool |
320 |
archive</e>, please run <c>/sbin/fix_libtool_files.sh 3.3.6</c> (substitute |
321 |
"3.3.6" with the version numbers from the error message). |
322 |
</p> |
323 |
|
324 |
<p> |
325 |
If you see the <e>error: /usr/bin/gcc-config: line 632: |
326 |
/etc/env.d/gcc/i686-pc-linux-gnu-3.3.5: No such file or directory</e>, then try |
327 |
deleting <path>/etc/env.d/gcc/config-i686-pc-linux-gnu</path> and running |
328 |
<c>gcc-config</c> again, followed by <c>source /etc/profile</c>. Only do this if |
329 |
you do not have any cross-compilers set up, though. |
330 |
</p> |
331 |
|
332 |
<p> |
333 |
If a package fails during <c>emerge -e system/world</c>, you can resume |
334 |
operation with <c>emerge --resume</c>. If a package fails repeatedly, skip it |
335 |
with <c>emerge --resume --skipfirst</c>. Don't run any other instances of emerge |
336 |
in between or you will lose the resume information. |
337 |
</p> |
338 |
|
339 |
<p> |
340 |
If you get an error message <e>spec failure: unrecognized spec option</e> while |
341 |
upgrading your compiler, try to switch back to your default compiler, unset the |
342 |
<c>GCC_SPECS</c> variable and upgrade GCC again: |
343 |
</p> |
344 |
|
345 |
<pre caption="Restoring primary specs"> |
346 |
# <i>gcc-config 1</i> |
347 |
# <i>source /etc/profile</i> |
348 |
# <i>unset GCC_SPECS</i> |
349 |
# <i>emerge -uav gcc</i> |
350 |
</pre> |
351 |
|
352 |
</body> |
353 |
</section> |
354 |
|
355 |
</chapter> |
356 |
</guide> |
357 |
|
358 |
|
359 |
|
360 |
-- |
361 |
gentoo-doc-cvs@g.o mailing list |