Upgrading GCC

This document Article description::guides users through the process of upgrading to modern versions of GCC.

Please note that downgrading GCC might have unwanted side effects. Refer to the troubleshooting section for some commonly reported issues.

Short version
This section is a quick primer on GCC upgrades (and how easy they are). More details are given in the next section, GCC upgrading explained.

Most GCC upgrades are as simple as switching the compiler version (here from 4.4.5 to 4.5.3) and rebuilding :

If upgrading GCC from a version earlier than 3.4, be sure to also run (provided by ):

(Versions of before 0.3.1 may require escape characters in the library name:  .)

Beyond GCC 3.4, is usually only necessary when upgrading to a new major version (i.e., 3.x to 4.x, or 4.x to 5.x):

Note that was introduced with GCC 3.4.0 and is still in use as of GCC 8.0.0.

Check the current version number and then uninstall the old version:

Enjoy the new compiler!

GCC upgrading explained
GCC upgrading has always been mystified, with suggestions ranging from "users do not need to do anything" to "users will need to rebuild the entire system twice". Most of this fear, uncertainty and doubt comes from the confusion surrounding ABI incompatibility. But first a quick pointer towards.

libtool and fix_libtool_files.sh
Earlier installments of GCC on Gentoo required you to run a specific command called. 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 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 script uses various library locations that have hard-coded  version information in them.

ABI changes
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. If you are upgrading to GCC 4.1, or GCC 5.1, you would probably encounter ABI issues. This is also why we use the command against the  (from GCC 3 to GCC 4.1), or  (from GCC 4 to GCC 5.1).

Versions of GentoolKit less than version 0.3.1 should run:

Version of GentoolKit that are 0.3.1 and greater should run:

So why is this only needed up to GCC 3.4.0/4.1/5.1? That's because from that version onward, 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 library will probably be increased.

The special case C++11 (and C++14)
While GCC (or more specifically, libstdc++) goes to great lengths to guarantee stability of the ABI, this guarantee does not extend to all parts of C++ within libstdc++. Formally, with versions starting from 3.4, GCC/libstdc++ only guarantees C++98/C++03 ABI stability and not more. This is crucial for packages that depend on C++11. GCC only makes C++11 ABI stability guarantees beginning with version 5.1. This means that switching (even minor) versions of gcc (say from 4.7.3 -> 4.7.4) might cause ABI breakage for binaries built from C++11 code.

For more information and some examples, see:


 * https://gcc.gnu.org/bugzilla/show_bug.cgi?id=61758
 * https://blogs.gentoo.org/blueness/2015/03/10/the-c11-abi-incompatibility-problem-in-gentoo/
 * https://stackoverflow.com/questions/16190269/g-always-backward-compatible-with-older-static-libraries/16196475#16196475
 * https://stackoverflow.com/questions/16190269/g-always-backward-compatible-with-older-static-libraries/16196475#16196475

Which packages are known to need a rebuild?
The following table gives the packages that, if installed, need to be rebuilt and why.

To be completely sure that your system is in a sane state, you must rebuild the toolchain and then world to make use of the new compiler.

Rebuilding everything
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.

Some packages need to be built with the same compiler. Although these packages are usually bumped by package maintainers simultaneously (so that they are always built with the same GCC version) cherry-picking re-installs on these packages might prove to be troublesome. The various packages are a an example of this matter.

rebuild of boost
If needs to be rebuilt, one will get the following error message:

One can rebuild with:

libstdc++.so.6: version `GLIBCXX_3.4.15' not found
During updates, you might encounter an error like the following:

This means that you are trying to build a package with an older GCC version than that with which some depending libraries were built. Remember when we told that the C++ ABI is 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 libraries).

To rebuild all the packages depending on libstdc++, see the instructions above.