Gentoo GCC Upgrade Guide
This is about upgrading GCC. Downgrading GCC might have unwanted side
effects. Please refer to Troubleshooting for
some commonly reported issues.
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 GCC Upgrading Explained.
If you are upgrading GCC then you do not need to do anything except switch
compiler version and rebuild libtool:
Code Listing 1.1: Switching GCC version
# emerge -u gcc
# gcc-config -l
 i686-pc-linux-gnu-4.4.5 *
# gcc-config 2
# env-update && source /etc/profile
# emerge --oneshot libtool
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 revdep-rebuild as well:
Code Listing 1.2: Upgrading from a non-forward compatible GCC version
# revdep-rebuild --library libstdc++.so.5
There you go. Enjoy the new compiler!
GCC Upgrading Explained
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 libtool.
libtool and fix_libtool_files.sh
Earlier installments of GCC on Gentoo required you to run a specific command
called fix_libtool_files.sh. 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.
The reason we need to rebuild libtool after the upgrade of gcc
versions is because of its main purpose: libtool 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
libtool script uses various library locations that have hardcoded GCC
version information in them.
An ABI, or Application Binary Interface, 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: GCC Binary
Compatibility). 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
revdep-rebuild command against the libstdc++.so.5 library.
Code Listing 2.1: Rebuilding applications linked against libstdc++.so.5
# revdep-rebuild --library libstdc++.so.5
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 libstdc++.so
library will probably be increased.
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.
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.
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
qt-* packages are a nice example on this matter.
libstdc++.so.6: version `GLIBCXX_3.4.15' not found
During updates, you might encounter an error like the following:
Code Listing 3.1: GLIBCXX_x.y.z not found
version `GLIBCXX_3.4.11' not found
This means that you are trying to build a package with an older 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 higher (or same) GCC versions can be used when building applications
and linking libraries (compared to the GCC version used to build those
Which packages are known to need a rebuild?
The following table gives the packages that, if installed, need to be
rebuild and why.
||Rebuild needed because ...
libtool application has hardcoded paths towards GCC internal
Gentoo Guides and Resources
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.