Project:Distribution Kernel/Bumping kernels

The process of bumping Gentoo dist-kernel packages involves a few helpful scripts that are used to update the ebuilds and build binary kernel packages. The whole process of testing the kernels and building binpkgs is done in a Docker container, so that it can be reliably reproduced on different hosts, as well as done remotely. This document describes the bumping process.

When are dist-kernels bumped?
Dist-kernels are bumped after the Gentoo kernel team releases the new genpatches tarballs, i.e. after are bumped.

However, it is useful to monitor or upstream release feeds, and start preparing the build containers as described below.

Platforms
At the moment, dist-kernel packages are built for amd64, arm64, ppc64le and x86 platforms. Normally, the arm64 and ppc64le builds are done using the relevant devboxes, so if you're planning on bumping the kernels, please request access to them. If you do not own a beefy amd64 box, you may want to also perform amd64 and/or x86 builds remotely.

The boxes used to build kernels do not need to be running Gentoo. They only need a running Docker daemon and your user needs to have permissions to use it.

Initial local box setup
On the development box, install the Docker client and helpful scripts used to bump kernels:

Clone the scripts used to build packages, preferably in :

Inside the repository, create a file called and put the remote hosts used to build kernels inside. For example, for arm64/ppc64le devboxes you'd use:

If you're also going to perform amd64/x86 builds remotely, add appropriate hosts with AMD64 and X86 suffixes.

Preparing the build images (optional)
When new kernels are released upstream but gentoo-sources are not ready yet, you can prepare the build images early. In binpkg-docker:

This will create Docker images with the necessary tools and baseline gentoo.git checkout. To avoid conflicts, you should also update your local gentoo.git checkout at the same time and use it as a base for the kernel bumps.

Bumping source packages
The kernel bumps are done using script from. The script is run inside gentoo.git and takes one or more pairs of arguments specifying the old and new versions respectively:

The script will copy kernel ebuilds and then open your ${EDITOR} to edit them. You may need to update upstream config (CONFIG_VER and CONFIG_HASH), Gentoo config (GENTOO_CONFIG_VER) and genpatches offset (GENPATCHES_P, in case of ). For the latter, it is recommended to grep gentoo-sources to avoid missing an update, e.g.:

Afterwards, the script will update the, perform signature verification (in case of ) and perform the commit. Once all kernels are committed, it will also create in the  checkout that will be used to build the kernels.

Building binary packages
Enter the checkout and start the kernel builds.

If you haven't prepared the build images yet, Docker will do that now. It will then apply the gentoo.git changes from (i.e. your bumps), build the kernels, test them and copy the resulting binary packages into.

The resulting binary packages need to be copied to your devspace for distribution. To do so, use:

This will first rsync new kernel packages from kamaji and bogsucker to your tree, then rsync this tree into dev.gentoo.org.

Once all kernels are built successfully, it is worthwhile to prune old containers and images immediately. If you forget to do that, the next builds will reuse existing images and will fail to apply the diff. To do so, you can use the convenience target that iterates over all Docker hosts and prunes tagged containers and images from them:

Bumping binary kernel packages
Enter once again and run  with the same arguments as the earlier  call:

This script copies kernel packages from your tree to your DISTDIR, and bumps. Note that you may need to sync GENPATCHES_P with the respective source package, and possibly update the binary package URLs.