Project:Toolchain/sys-devel/gcc

Release cycle

Upstream maintains approximately 3 branches at a time (e.g. 12/13/14).
The last version of a branch is usually X.5, e.g. GCC 11.5. Upstream then immediately close the relevant branch (e.g. releases/gcc-11) 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.

Snapshots

We try to package the weekly snapshots published by the GCC developers including for the stable branches.
Generally, because we're a source-based distribution, the fixes matter more for us (as something doesn't have to build & build correctly just on one machine, but on every user's machine with their *FLAGS). Especially so for wrong-code/miscompilation fixes.
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 14 is the last released version and GCC 15 is the new version in development.

Immediately upon branching:

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

These parts can be done later as development proceeds:

File a tracker bug (see e.g. bug #914580) called "sys-devel/gcc-15 porting" and add 'gcc-15' to the Alias field (replace version as necessary). Link to the relevant GCC porting page in the bug, e.g. https://gcc.gnu.org/gcc-15/porting_to.html.
Update Project:Toolchain/Porting notes with a new page.
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

Note
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.

Usually wait a while until GCC reaches Stage 4 (subscribe to the GCC mailing list if haven't already)
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.

Usage

Warning
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 https://wiki.gentoo.org/wiki/Project:Toolchain/sys-devel/gcc#Usage
<sys-devel/gcc-12.5.9999:12 **
<sys-devel/gcc-13.4.9999:13 **
<sys-devel/gcc-14.3.9999:14 **
<sys-devel/gcc-15.0.9999:15 **

Development

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:

user $git clone https://sourceware.org/git/builder.git

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

user $builder/containers/autoregen.py

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

GCC's testsuite usually doesn't pass entirely cleanly because of the guality (debug information quality tests). We use tooling to generate a sane baseline and allow comparisons in future runs.

ebuild

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

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.

Configuration

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

GCC_TESTS_COMPARISON_DIR
GCC_TESTS_COMPARISON_SLOT
GCC_TESTS_IGNORE_NO_BASELINE
GCC_TESTS_REGEN_BASELINE
GCC_TESTS_CHECK_TARGET
GCC_TESTS_RUNTESTFLAGS

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.

Setup

To get started with running the testsuite from the ebuild:

Setup etckeeper in /var/cache/gcc/testresults (see below)
Build GCC with FEATURES=test GCC_TESTS_IGNORE_NO_BASELINE=1 or FEATURES="test test-fail-continue"
On future builds, check if new failures look problematic (consider continuing to use test-fail-continue at first and just review afterwards in /var/cache/gcc with git log -p)

The ebuild can be instructed to run a small test of execute-only tests to check for serious, critical breakage with GCC_TESTS_RUNTESTFLAGS="execute.exp". Otherwise, the default runs all tests, which is fine but may require more attention.

etckeeper

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
    setup|prerm)
        etckeeper pre-install
        etckeeper pre-install -d /var/cache/gcc/testresults/
        ;;
    postinst|postrm)
        etckeeper post-install
        etckeeper post-install -d /var/cache/gcc/testresults/
        ;;
esac

General

This section is a set of misc notes on the test suite.

Check out dmalcolm's docs too as well as the GCC wiki page on testing.

Torture tests

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

FILE /tmp/site.exp

$ cat ~/site.exp
set ADDITIONAL_TORTURE_OPTIONS  [list \
  { -O3 -fno-vect-cost-model } \
  { -O3 } ]

Then optionally export GCC_TEST_RUN_EXPENSIVE to run expensive tests:

user $export GCC_TEST_RUN_EXPENSIVE=1

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"