From Gentoo Wiki
Jump to:navigation Jump to:search

Release cycle

  • Upstream maintains approximately 3 branches at a time (e.g. 11/12/13).
  • The last version of a branch is usually X.5, e.g. GCC 9.5. Upstream then immediately close the relevant branch (e.g. releases/gcc-9) and it is no longer used for backports.
  • When a new major GCC version enters Stage 4, the Gentoo Toolchain project begins testing (or steps up efforts if they already began) with building large amounts of the tree. Request tinderboxing if possible.
    • At this point, it's encouraged that developers with backups consider converting their experimental systems to the new, unreleased version.


  • We try to package the weekly snapshots published by the GCC developers.
  • Upstream are quite rigid about releasing once per year for each release series (with the exception of the first two releases, which happen about 2-4 months apart). Serious regressions are often fixed after releases and by using snapshots, we pick these up quickly.
  • We don't therefore worry about keeping the last "real" releases in tree. There's no real benefit from using them apart from making people feel better.
  • This matches what e.g. opensuse (+ fedora/debian/ubuntu) does and it allows us to easily pick up fixes rather than trying to delicately cherry-pick only a handful and possibly missing dependent commits as a result (GCC doesn't at present use 'Fixes' very often in commit messages, so it's not always easy to establish).
  • Don't keyword every snapshot.
  • Snapshots should usually start off unkeyworded even if the intent is to keyword-and-later-stable it.
  • The snapshots correspond to a particular release branch, except for the latest unreleased version, and are safe to use.
    • GCC doesn't make frequent stable releases because of the work involved on their end and expect distributions to pull from these branches.

Procedure for new major versions

For the purposes of this example, assume GCC 13 is the last released version and GCC 14 is the new version in development.

Immediately upon branching:

  1. Copy gcc-13.0.9999.ebuild to gcc-14.0.9999.ebuild
  2. Update EGIT_BRANCH in gcc-13.0.9999.ebuild to EGIT_BRANCH=releases/gcc-$(ver_cut 1)
  3. In gcc-patches.git, copy 13.0 -> 14.0.
  4. Update PATCH_GCC_VER and MUSL_GCC_VER in gcc-13.0.9999.ebuild accordingly.

These parts can be done later as development proceeds:

  1. File a tracker bug (see e.g. bug #914580) called "sys-devel/gcc-14 porting" and add 'gcc-14' to the Alias field (replace version as necessary). Link to the relevant GCC porting page in the bug, e.g.
  2. Update Project:Toolchain/Porting notes with a new page.
  3. Create a new folder in gcc-patches.git, copying from the last version. Test/rebase as needed. Use the live ebuilds with an override to test a local gcc-patches repo to avoid committing junk which doesn't apply.

Testing new major versions

We appreciate testing from keen users, but please be careful to not report bugs upstream without running it by someone else first. Ideally please file a Gentoo bug first, clearly noting which GCC is being used, and it can be taken from there.
  1. Usually wait a while until GCC reaches Stage 4 (subscribe to the GCC mailing list if haven't already)
  2. Once GCC reaches Stage 4, consider building testing systems with it (as long as there's backups!)
    1. Daily drive it if possible.
    2. Perform regular emerge -ev @world runs (the more packages installed & the less common, the better!) to build failures initially and later, regressions.
    3. Consider doing a FEATURES=test (consider skipping dev-python/*, dev-perl/* etc via package.env) build with the previous GCC version, noting the test failures which occur with the known-working version (and reporting any bugs), then do it again with the new GCC version to see if anything broke. Report bugs and investigate. Failures are likely bugs in the programs (probably UB) but there's a chance of a compiler bug too.


Please don't use a new major version as your system compiler if using stable keywords. Fixes for packages will start in ~arch and we don't want duplicate bug reports for every issue.

The following is a snippet to pick up the snapshots in each slot even if unkeyworded:

FILE /etc/portage/package.accept_keywords/gcc
# Get the latest version of this from
<sys-devel/gcc-11.5.9999:11 **
<sys-devel/gcc-12.4.9999:12 **
<sys-devel/gcc-13.4.9999:13 **
<sys-devel/gcc-14.1.9999:14 **
<sys-devel/gcc-15.0.9999:15 **


Build system

binutils-gdb and gcc share the same build system across two repositories. The same instructions below apply for both.

Install the following packages:

root #emerge --ask dev-build/autoconf-vanilla:2.69 dev-build/automake-vanilla:1.15

Grab builder.git from sourceware's buildbot for a useful script:

Then run builder/containers/ in gcc/binutils-gdb.git:

user $builder/containers/

It is possible to try run autoreconf manually but it may not correctly regenerate all directories because the top-level buildsystem in gcc/binutils-gdb doesn't use AC_CONFIG_SUBDIRS:

user $WANT_AUTOCONF=vanilla-2.69 WANT_AUTOMAKE=vanilla-1.15 autoreconf -fi

Test suite


We make use of contrib/testsuite-management/ from gcc.git.

toolchain.eclass has a set of variables to customize the test setup:


A manifest of the test results from a run is recorded at GCC_TESTS_COMPARISON_DIR (defaulting to /var/cache/gcc/testresults/${CHOST}/${SLOT}/${CHOST}.xfail).

Subsequent runs will compare against the manifest and only fail src_test if new failures are found.

They have sensible defaults and shouldn't need meddling with to start with. Note that these variables are documented in its eclassdoc - see app-doc/eclass-manpages.


To track results and their changes over time, one may want to setup Etckeeper for the test results directory.

FILE /etc/portage/bashrc
case "${EBUILD_PHASE}" in
        etckeeper pre-install
        etckeeper pre-install -d /var/cache/gcc/testresults/
        etckeeper post-install
        etckeeper post-install -d /var/cache/gcc/testresults/


Misc notes on the test suite. Check out dmalcolm's docs too.

To run the torture tests with an additional set of flags:

FILE /tmp/site.exp
$ cat ~/site.exp
  { -O3 -fno-vect-cost-model } \
  { -O3 } ]

Then optionally export GCC_TEST_RUN_EXPENSIVE to run expensive tests:


Tell dejagnu where to find the config file:

user $export DEJAGNU=/tmp/site.exp

Run the tests:

user $make -Oline check-gcc RUNTESTFLAGS="execute.exp"

External links