doc/en/gcc-upgrading.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.31 2011/10/13 15:11:55 swift Exp $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide>
<title>Gentoo GCC Upgrade Guide</title>

<author title="Author">
  <mail link="swift"/>
</author>

<abstract>
This document will guide the user through the process of upgrading GCC.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>25</version>
<date>2011-10-15</date>

<chapter id="quickstart">
<title>Quickstart</title>
<section>
<title>Introduction</title>
<body>

<p>
This is about <e>upgrading</e> GCC. Downgrading GCC might have unwanted side
effects. Please refer to <uri link="#troubleshooting">Troubleshooting</uri> for
some commonly reported issues.
</p>

<p>
The next section gives a quick primer into GCC upgrades (and how easy they are).
If you want to read the lengthy reasoning behind GCC upgrades, please continue
with <uri link="#explanation">GCC Upgrading Explained</uri>.
</p>

</body>
</section>
<section>
<title>Short Version</title>
<body>

<p>
If you are upgrading GCC then you do not need to do anything except switch
compiler version and rebuild libtool:
</p>

<pre caption="Switching GCC version">
# <i>emerge -u gcc</i>
# <i>gcc-config -l</i>
[1] i686-pc-linux-gnu-4.4.5 *
[2] i686-pc-linux-gnu-4.5.3

# <i>gcc-config 2</i>
# <i>env-update &amp;&amp; source /etc/profile</i>
# <i>emerge --oneshot libtool</i>
</pre>

<p>
If you upgrade GCC from a version earlier than 3.4.0 (for the 3.x series) or
4.1, you will need to run <c>revdep-rebuild</c> as well:
</p>

<pre caption="Upgrading from a non-forward compatible GCC version">
# <i>revdep-rebuild --library libstdc++.so.5</i>
</pre>

<p>
There you go. Enjoy the new compiler!
</p>

</body>
</section>
</chapter>

<chapter id="explanation">
<title>GCC Upgrading Explained</title>
<section>
<title>Introduction</title>
<body>

<p>
GCC upgrading has always been mystified, with suggestions ranging from "You do
not need to do anything" up to "You will need to rebuild your entire system
twice". Most of this FUD comes from the confusion surrounding ABI
incompatibility. But first a quick pointer towards <c>libtool</c>.
</p>

</body>
</section>
<section>
<title>libtool and fix_libtool_files.sh</title>
<body>

<p>
Earlier installments of GCC on Gentoo required you to run a specific command
called <c>fix_libtool_files.sh</c>. Some time ago, the execution of this
command has been integrated in the package deployments itself (through the
toolchain eclass) so there is no need for users to call this themselves anymore.
</p>

<p>
The reason we need to rebuild libtool after the upgrade of gcc
versions is because of its main purpose: <e>libtool</e> is a toolset that
aggregates platform-specific code in a generic interface, allowing applications
to build against shared libraries without needing to deal with the platform
specific aspects of shared libraries. To fulfill its function properly, the 
<c>libtool</c> script uses various library locations that have hardcoded GCC
version information in them.
</p>

</body>
</section>
<section>
<title>ABI Changes</title>
<body>

<p>
An ABI, or <e>Application Binary Interface</e>, is a set of conventions used by
all tools that deal with binary representation of programs, including compilers,
assemblers, linkers and language runtime support (source: <uri
link="http://gcc.gnu.org/onlinedocs/gcc/Compatibility.html">GCC Binary
Compatibility</uri>). When the ABI used for binary applications and libraries is
changed, you will risk getting linker errors or malfunctioning programs unless
you rebuild all libraries that use C++ code. Yes, C++, since most
incompatibilities occur within the C++ ABI. This is also why we use the
<c>revdep-rebuild</c> command against the <path>libstdc++.so.5</path> library.
</p>

<pre caption="Rebuilding applications linked against libstdc++.so.5">
# <i>revdep-rebuild --library libstdc++.so.5</i>
</pre>

<p>
So why is this only needed up to GCC 3.4.0/4.1 ? That's because from that
version onwards, GCC uses a forward compatible ABI, which removes the need for
rebuilding applications and libraries. Of course, guarantees can never be given
indefinitely, but when an incompatibility occurs again, we'll definitely
document it here ;-) In that case, the version of the <path>libstdc++.so</path>
library will probably be increased.
</p>

</body>
</section>
<section>
<title>Rebuilding Everything</title>
<body>

<p>
Some people swear that they need to rebuild every single package on their system
when a new GCC version is made available. Of course, that doesn't make sense,
since there are many applications that are not using GCC for their build and
install process anyhow, so they would never be affected by such changes.
</p>

<p>
That however doesn't mean they are completely incorrect: newer GCC versions
often include better support for the processors' instruction set, which might
influence the performance of some applications in a positive way. Although it is
expected that this improvement is generally only marginally, in some cases
(especially CPU intensive applications) this might yield notable improvements.
</p>

<p>
There are also known cases where packages need to be built with the same
compiler. Although these packages are usually bumped by Gentoo simultaneously
(so that they are always built with the same GCC version) cherry-picking
reinstalls on these packages might prove to be troublesome. The various
<path>qt-*</path> packages are a nice example on this matter.
</p>

</body>
</section>
</chapter>

<chapter id="troubleshooting">
<title>Troubleshooting</title>
<section>
<title>libstdc++.so.6: version `GLIBCXX_3.4.15' not found</title>
<body>

<p>
During updates, you might encounter an error like the following:
</p>

<pre caption="GLIBCXX_x.y.z not found">
cmake_bootstrap_28021_test: /usr/lib/gcc/i486-pc-linux-gnu/4.1.2/libstdc++.so.6:
version `GLIBCXX_3.4.11' not found 
</pre>

<p>
This means that you are trying to build a package with an <e>older</e> GCC
version than with which some depending libraries were built. Remember when we
told that the C++ ABI if forward-compatible? That is true, but it ensures only
that <e>higher</e> (or same) GCC versions can be used when building applications
and linking libraries (compared to the GCC version used to build those
libraries).
</p>

</body>
</section>
<section>
<title>Which packages are known to need a rebuild?</title>
<body>

<p>
The following table gives the packages that, <e>if installed</e>, need to be
rebuild and why.
</p>

<table>
<tr>
  <th>Package</th>
  <th>Rebuild needed because ...</th>
</tr>
<tr>
  <ti>sys-devel/libtool</ti>
  <ti>
    libtool application has hardcoded paths towards GCC internal
    libraries
  </ti>
</tr>
<tr>
  <ti>dev-lang/ghc</ti>
  <ti>
    ghc application has hardcoded paths towards GCC internal libraries
  </ti>
</tr>
</table>

</body>
</section>
</chapter>

<chapter>
<title>Resources</title>
<section>
<title>Gentoo Guides and Resources</title>
<body>

<ul>
  <li>
    <uri link="gcc-upgrading-upto-4.1.xml">GCC Upgrading up to 4.1</uri>,
    the previous version of this document
  </li>
</ul>

</body>
</section>
</chapter>
</guide>
1	<?xml version='1.0' encoding="UTF-8"?>
2	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.31 2011/10/13 15:11:55 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>25</version>
22	<date>2011-10-15</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 && 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	<section>
208	<title>Which packages are known to need a rebuild?</title>
209	<body>
210
211	<p>
212	The following table gives the packages that, <e>if installed</e>, need to be
213	rebuild and why.
214	</p>
215
216	<table>
217	<tr>
218	<th>Package</th>
219	<th>Rebuild needed because ...</th>
220	</tr>
221	<tr>
222	<ti>sys-devel/libtool</ti>
223	<ti>
224	libtool application has hardcoded paths towards GCC internal
225	libraries
226	</ti>
227	</tr>
228	<tr>
229	<ti>dev-lang/ghc</ti>
230	<ti>
231	ghc application has hardcoded paths towards GCC internal libraries
232	</ti>
233	</tr>
234	</table>
235
236	</body>
237	</section>
238	</chapter>
239
240	<chapter>
241	<title>Resources</title>
242	<section>
243	<title>Gentoo Guides and Resources</title>
244	<body>
245
246	<ul>
247	<li>
248	<uri link="gcc-upgrading-upto-4.1.xml">GCC Upgrading up to 4.1</uri>,
249	the previous version of this document
250	</li>
251	</ul>
252
253	</body>
254	</section>
255	</chapter>
256	</guide>