/[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.35 - (hide annotations) (download) (as text)
Mon Dec 9 09:24:16 2013 UTC (10 months, 1 week ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.34: +2 -2 lines
File MIME type: application/xml
Moved gcc upgrading to https://wiki.gentoo.org/wiki/Upgrading_GCC

1 jkt 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.35 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gcc-upgrading.xml,v 1.34 2013/08/24 17:00:53 swift Exp $ -->
3 jkt 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6 swift 1.35 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Upgrading_GCC">
7 vapier 1.19 <title>Gentoo GCC Upgrade Guide</title>
8 jkt 1.1
9     <author title="Author">
10 swift 1.31 <mail link="swift"/>
11 jkt 1.1 </author>
12    
13     <abstract>
14 nightmorph 1.29 This document will guide the user through the process of upgrading GCC.
15 jkt 1.1 </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 swift 1.34 <version>27</version>
22     <date>2013-08-24</date>
23 jkt 1.1
24 swift 1.31 <chapter id="quickstart">
25     <title>Quickstart</title>
26     <section>
27 jkt 1.1 <title>Introduction</title>
28     <body>
29    
30     <p>
31 swift 1.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 jkt 1.1 </p>
35    
36     <p>
37 swift 1.31 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 jkt 1.1 </p>
41    
42     </body>
43     </section>
44     <section>
45 swift 1.31 <title>Short Version</title>
46 jkt 1.1 <body>
47    
48     <p>
49 swift 1.31 If you are upgrading GCC then you do not need to do anything except switch
50     compiler version and rebuild libtool:
51 jkt 1.1 </p>
52    
53 swift 1.31 <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 jkt 1.1
59 swift 1.31 # <i>gcc-config 2</i>
60 nightmorph 1.25 # <i>env-update &amp;&amp; source /etc/profile</i>
61 swift 1.31 # <i>emerge --oneshot libtool</i>
62 jkt 1.1 </pre>
63    
64     <p>
65 swift 1.31 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 jkt 1.1 </p>
68    
69 swift 1.31 <pre caption="Upgrading from a non-forward compatible GCC version">
70     # <i>revdep-rebuild --library libstdc++.so.5</i>
71 jkt 1.1 </pre>
72    
73     <p>
74 swift 1.31 There you go. Enjoy the new compiler!
75 jkt 1.1 </p>
76    
77     </body>
78     </section>
79     </chapter>
80    
81 swift 1.31 <chapter id="explanation">
82     <title>GCC Upgrading Explained</title>
83 jkt 1.1 <section>
84     <title>Introduction</title>
85     <body>
86    
87     <p>
88 swift 1.31 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 jkt 1.1 </p>
93    
94     </body>
95     </section>
96 swift 1.31 <section>
97     <title>libtool and fix_libtool_files.sh</title>
98 jkt 1.1 <body>
99    
100 swift 1.31 <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 jkt 1.22 </p>
106    
107     <p>
108 swift 1.31 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 jkt 1.1 </p>
116    
117     </body>
118     </section>
119 swift 1.31 <section>
120     <title>ABI Changes</title>
121 jkt 1.1 <body>
122    
123     <p>
124 swift 1.31 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 jkt 1.1 </p>
134    
135 swift 1.31 <pre caption="Rebuilding applications linked against libstdc++.so.5">
136 jkt 1.1 # <i>revdep-rebuild --library libstdc++.so.5</i>
137     </pre>
138    
139     <p>
140 swift 1.31 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 jkt 1.1 </p>
147    
148     </body>
149     </section>
150 neysx 1.6 <section>
151 swift 1.31 <title>Rebuilding Everything</title>
152 neysx 1.6 <body>
153    
154     <p>
155 swift 1.31 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 neysx 1.6 </p>
160    
161     <p>
162 swift 1.31 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 neysx 1.6 </p>
168    
169     <p>
170 swift 1.31 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 neysx 1.6 </p>
176    
177     </body>
178     </section>
179 swift 1.31 </chapter>
180 neysx 1.6
181 swift 1.31 <chapter id="troubleshooting">
182     <title>Troubleshooting</title>
183     <section>
184     <title>libstdc++.so.6: version `GLIBCXX_3.4.15' not found</title>
185 neysx 1.6 <body>
186    
187     <p>
188 swift 1.31 During updates, you might encounter an error like the following:
189 neysx 1.6 </p>
190    
191 swift 1.31 <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 neysx 1.6 </pre>
195    
196     <p>
197 swift 1.31 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 neysx 1.6 </p>
204    
205     </body>
206     </section>
207 swift 1.32 <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     </table>
229    
230     </body>
231     </section>
232 jkt 1.1 </chapter>
233 jkt 1.8
234 swift 1.31 <chapter>
235     <title>Resources</title>
236 jkt 1.8 <section>
237 swift 1.31 <title>Gentoo Guides and Resources</title>
238 jkt 1.8 <body>
239    
240 swift 1.31 <ul>
241     <li>
242 swift 1.34 <uri link="https://wiki.gentoo.org/wiki/Upgrade_GCC_up_to_4.1">GCC Upgrading up to 4.1</uri>,
243 swift 1.31 the previous version of this document
244     </li>
245     </ul>
246 jkt 1.8
247     </body>
248     </section>
249     </chapter>
250 jkt 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20