/[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.31 - (show annotations) (download) (as text)
Thu Oct 13 15:11:55 2011 UTC (2 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.30: +105 -405 lines
File MIME type: application/xml
Updating GCC upgrading guide with comments and feedback from gentoo-dev@g.o. Fixes bugs #385069 and bug #384045

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.30 2011/09/04 17:53:40 swift Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6 <guide>
7 <title>Gentoo GCC Upgrade Guide</title>
8
9 <author title="Author">
10 <mail link="swift"/>
11 </author>
12
13 <abstract>
14 This document will guide the user through the process of upgrading GCC.
15 </abstract>
16
17 <!-- The content of this document is licensed under the CC-BY-SA license -->
18 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
19 <license/>
20
21 <version>24</version>
22 <date>2011-10-13</date>
23
24 <chapter id="quickstart">
25 <title>Quickstart</title>
26 <section>
27 <title>Introduction</title>
28 <body>
29
30 <p>
31 This is about <e>upgrading</e> GCC. Downgrading GCC might have unwanted side
32 effects. Please refer to <uri link="#troubleshooting">Troubleshooting</uri> for
33 some commonly reported issues.
34 </p>
35
36 <p>
37 The next section gives a quick primer into GCC upgrades (and how easy they are).
38 If you want to read the lengthy reasoning behind GCC upgrades, please continue
39 with <uri link="#explanation">GCC Upgrading Explained</uri>.
40 </p>
41
42 </body>
43 </section>
44 <section>
45 <title>Short Version</title>
46 <body>
47
48 <p>
49 If you are upgrading GCC then you do not need to do anything except switch
50 compiler version and rebuild libtool:
51 </p>
52
53 <pre caption="Switching GCC version">
54 # <i>emerge -u gcc</i>
55 # <i>gcc-config -l</i>
56 [1] i686-pc-linux-gnu-4.4.5 *
57 [2] i686-pc-linux-gnu-4.5.3
58
59 # <i>gcc-config 2</i>
60 # <i>env-update &amp;&amp; source /etc/profile</i>
61 # <i>emerge --oneshot libtool</i>
62 </pre>
63
64 <p>
65 If you upgrade GCC from a version earlier than 3.4.0 (for the 3.x series) or
66 4.1, you will need to run <c>revdep-rebuild</c> as well:
67 </p>
68
69 <pre caption="Upgrading from a non-forward compatible GCC version">
70 # <i>revdep-rebuild --library libstdc++.so.5</i>
71 </pre>
72
73 <p>
74 There you go. Enjoy the new compiler!
75 </p>
76
77 </body>
78 </section>
79 </chapter>
80
81 <chapter id="explanation">
82 <title>GCC Upgrading Explained</title>
83 <section>
84 <title>Introduction</title>
85 <body>
86
87 <p>
88 GCC upgrading has always been mystified, with suggestions ranging from "You do
89 not need to do anything" up to "You will need to rebuild your entire system
90 twice". Most of this FUD comes from the confusion surrounding ABI
91 incompatibility. But first a quick pointer towards <c>libtool</c>.
92 </p>
93
94 </body>
95 </section>
96 <section>
97 <title>libtool and fix_libtool_files.sh</title>
98 <body>
99
100 <p>
101 Earlier installments of GCC on Gentoo required you to run a specific command
102 called <c>fix_libtool_files.sh</c>. Some time ago, the execution of this
103 command has been integrated in the package deployments itself (through the
104 toolchain eclass) so there is no need for users to call this themselves anymore.
105 </p>
106
107 <p>
108 The reason we need to rebuild libtool after the upgrade of gcc
109 versions is because of its main purpose: <e>libtool</e> is a toolset that
110 aggregates platform-specific code in a generic interface, allowing applications
111 to build against shared libraries without needing to deal with the platform
112 specific aspects of shared libraries. To fulfill its function properly, the
113 <c>libtool</c> script uses various library locations that have hardcoded GCC
114 version information in them.
115 </p>
116
117 </body>
118 </section>
119 <section>
120 <title>ABI Changes</title>
121 <body>
122
123 <p>
124 An ABI, or <e>Application Binary Interface</e>, is a set of conventions used by
125 all tools that deal with binary representation of programs, including compilers,
126 assemblers, linkers and language runtime support (source: <uri
127 link="http://gcc.gnu.org/onlinedocs/gcc/Compatibility.html">GCC Binary
128 Compatibility</uri>). When the ABI used for binary applications and libraries is
129 changed, you will risk getting linker errors or malfunctioning programs unless
130 you rebuild all libraries that use C++ code. Yes, C++, since most
131 incompatibilities occur within the C++ ABI. This is also why we use the
132 <c>revdep-rebuild</c> command against the <path>libstdc++.so.5</path> library.
133 </p>
134
135 <pre caption="Rebuilding applications linked against libstdc++.so.5">
136 # <i>revdep-rebuild --library libstdc++.so.5</i>
137 </pre>
138
139 <p>
140 So why is this only needed up to GCC 3.4.0/4.1 ? That's because from that
141 version onwards, GCC uses a forward compatible ABI, which removes the need for
142 rebuilding applications and libraries. Of course, guarantees can never be given
143 indefinitely, but when an incompatibility occurs again, we'll definitely
144 document it here ;-) In that case, the version of the <path>libstdc++.so</path>
145 library will probably be increased.
146 </p>
147
148 </body>
149 </section>
150 <section>
151 <title>Rebuilding Everything</title>
152 <body>
153
154 <p>
155 Some people swear that they need to rebuild every single package on their system
156 when a new GCC version is made available. Of course, that doesn't make sense,
157 since there are many applications that are not using GCC for their build and
158 install process anyhow, so they would never be affected by such changes.
159 </p>
160
161 <p>
162 That however doesn't mean they are completely incorrect: newer GCC versions
163 often include better support for the processors' instruction set, which might
164 influence the performance of some applications in a positive way. Although it is
165 expected that this improvement is generally only marginally, in some cases
166 (especially CPU intensive applications) this might yield notable improvements.
167 </p>
168
169 <p>
170 There are also known cases where packages need to be built with the same
171 compiler. Although these packages are usually bumped by Gentoo simultaneously
172 (so that they are always built with the same GCC version) cherry-picking
173 reinstalls on these packages might prove to be troublesome. The various
174 <path>qt-*</path> packages are a nice example on this matter.
175 </p>
176
177 </body>
178 </section>
179 </chapter>
180
181 <chapter id="troubleshooting">
182 <title>Troubleshooting</title>
183 <section>
184 <title>libstdc++.so.6: version `GLIBCXX_3.4.15' not found</title>
185 <body>
186
187 <p>
188 During updates, you might encounter an error like the following:
189 </p>
190
191 <pre caption="GLIBCXX_x.y.z not found">
192 cmake_bootstrap_28021_test: /usr/lib/gcc/i486-pc-linux-gnu/4.1.2/libstdc++.so.6:
193 version `GLIBCXX_3.4.11' not found
194 </pre>
195
196 <p>
197 This means that you are trying to build a package with an <e>older</e> GCC
198 version than with which some depending libraries were built. Remember when we
199 told that the C++ ABI if forward-compatible? That is true, but it ensures only
200 that <e>higher</e> (or same) GCC versions can be used when building applications
201 and linking libraries (compared to the GCC version used to build those
202 libraries).
203 </p>
204
205 </body>
206 </section>
207 </chapter>
208
209 <chapter>
210 <title>Resources</title>
211 <section>
212 <title>Gentoo Guides and Resources</title>
213 <body>
214
215 <ul>
216 <li>
217 <uri link="gcc-upgrading-upto-4.1.xml">GCC Upgrading up to 4.1</uri>,
218 the previous version of this document
219 </li>
220 </ul>
221
222 </body>
223 </section>
224 </chapter>
225 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20