Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + scripts/container | 199 +++++++++++++++++++++++++ 3 files changed, 401 insertions(+) create mode 100644 Documentation/dev-tools/container.rst create mode 100755 scripts/container
This proposal emerged from discussions over email and after a talk at
Plumbers 2024:
https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/
The aim is to facilitate reproducing builds for CI bots as well as
developers using containers. Here's an illustrative example with a
kernel.org toolchain in a Docker image from tuxmake:
$ scripts/container -i tuxmake/korg-clang-21 make LLVM=1 defconfig
HOSTCC scripts/basic/fixdep
HOSTCC scripts/kconfig/conf.o
[...]
HOSTCC scripts/kconfig/util.o
HOSTLD scripts/kconfig/conf
*** Default configuration is based on 'x86_64_defconfig'
#
# configuration written to .config
#
This patch series also includes a documentation page with all the
relevant details and further examples about how to use the tool.
To go one step further, I'm in the process of preparing reference
container images with kernel.org toolchains and no third-party
dependencies other than the base Debian distro. See this thread for
more details and options to host them in an upstream way:
https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
Say, to run KUnit using the latest kernel.org GCC toolchain:
scripts/container --shell \
-i registry.gitlab.com/gtucker/korg-containers/gcc:kunit -- \
tools/testing/kunit/kunit.py \
run \
--arch=x86_64 \
--cross_compile=x86_64-linux-
---
Changes in v3:
- Refactor common code for Docker and Podman
- Add docs.kernel.org URL in help message
- Use pathlib Python package
- Handle signals in parent process by default
- Add --shell option to use an interactive shell
- Tweak debug messages in verbose mode
- Specify Python 3.10 as minimum version in the docs
- Provide an example env file in the docs
- Update docs regarding interactive shell usage
Changes in v2:
- Drop default image but make -i option required
- Look for Docker and Podman if no runtime specified
- Catch SIGINT from user to abort container with Docker
- Explicitly name each container with a UUID
- Update documentation accordingly
---
Guillaume Tucker (2):
scripts: add tool to run containerized builds
Documentation: dev-tools: add container.rst page
Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++
Documentation/dev-tools/index.rst | 1 +
scripts/container | 199 +++++++++++++++++++++++++
3 files changed, 401 insertions(+)
create mode 100644 Documentation/dev-tools/container.rst
create mode 100755 scripts/container
--
2.47.3
On Wed, Dec 31, 2025 at 05:51:48PM +0100, Guillaume Tucker wrote: > This proposal emerged from discussions over email and after a talk at > Plumbers 2024: > > https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/ > > The aim is to facilitate reproducing builds for CI bots as well as > developers using containers. Here's an illustrative example with a > kernel.org toolchain in a Docker image from tuxmake: > > $ scripts/container -i tuxmake/korg-clang-21 make LLVM=1 defconfig > HOSTCC scripts/basic/fixdep > HOSTCC scripts/kconfig/conf.o > [...] > HOSTCC scripts/kconfig/util.o > HOSTLD scripts/kconfig/conf > *** Default configuration is based on 'x86_64_defconfig' > # > # configuration written to .config > # > > This patch series also includes a documentation page with all the > relevant details and further examples about how to use the tool. > > To go one step further, I'm in the process of preparing reference > container images with kernel.org toolchains and no third-party > dependencies other than the base Debian distro. See this thread for > more details and options to host them in an upstream way: > > https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/ > > Say, to run KUnit using the latest kernel.org GCC toolchain: > > scripts/container --shell \ > -i registry.gitlab.com/gtucker/korg-containers/gcc:kunit -- \ > tools/testing/kunit/kunit.py \ > run \ > --arch=x86_64 \ > --cross_compile=x86_64-linux- > > --- > Changes in v3: > - Refactor common code for Docker and Podman > - Add docs.kernel.org URL in help message > - Use pathlib Python package > - Handle signals in parent process by default > - Add --shell option to use an interactive shell > - Tweak debug messages in verbose mode > - Specify Python 3.10 as minimum version in the docs > - Provide an example env file in the docs > - Update docs regarding interactive shell usage > > Changes in v2: > - Drop default image but make -i option required > - Look for Docker and Podman if no runtime specified > - Catch SIGINT from user to abort container with Docker > - Explicitly name each container with a UUID > - Update documentation accordingly > > --- > > Guillaume Tucker (2): > scripts: add tool to run containerized builds > Documentation: dev-tools: add container.rst page > > Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++ > Documentation/dev-tools/index.rst | 1 + > scripts/container | 199 +++++++++++++++++++++++++ > 3 files changed, 401 insertions(+) > create mode 100644 Documentation/dev-tools/container.rst > create mode 100755 scripts/container > > -- > 2.47.3 > > Out-of-source builds do not work on my system with podman. If this is expected, I think it would be great to mention that somewhere in the documentation. Nevertheless, thanks a lot! I expect me to use that a lot in the future! For the whole patch set: Tested-by: Nicolas Schier <nsc@kernel.org> Acked-by: Nicolas Schier <nsc@kernel.org> Kind regards, Nicolas -- Nicolas
Hi Nicolas, On 20/01/2026 14:54, Nicolas Schier wrote: > Out-of-source builds do not work on my system with podman. If this is > expected, I think it would be great to mention that somewhere in the > documentation. The v4 now mentions this and also includes a trick using bind-mount: mkdir -p $HOME/tmp/my-kernel-build mkdir -p build sudo mount --bind $HOME/tmp/my-kernel-build build scripts/container -i kernel.org/gcc -- make mrproper scripts/container -i kernel.org/gcc -- make O=build defconfig scripts/container -i kernel.org/gcc -- make O=build -j$(nproc) Would this work for your use-case? Directory names are entirely arbitrary. It's not ideal but might be good enough as a workaround until this gets properly supported by the tool in a future version. Cheers, Guillaume
On Thu, Jan 22, 2026 at 03:12:36PM +0100, Guillaume Tucker wrote: > Hi Nicolas, > > On 20/01/2026 14:54, Nicolas Schier wrote: > > Out-of-source builds do not work on my system with podman. If this is > > expected, I think it would be great to mention that somewhere in the > > documentation. > > The v4 now mentions this and also includes a trick using bind-mount: > > mkdir -p $HOME/tmp/my-kernel-build > mkdir -p build > sudo mount --bind $HOME/tmp/my-kernel-build build > scripts/container -i kernel.org/gcc -- make mrproper > scripts/container -i kernel.org/gcc -- make O=build defconfig > scripts/container -i kernel.org/gcc -- make O=build -j$(nproc) > > Would this work for your use-case? Directory names are entirely > arbitrary. It's not ideal but might be good enough as a workaround > until this gets properly supported by the tool in a future version. sorry for the long delay. Yes, thanks for the follow-up! Kind regards, Nicolas
Hi Nicolas, On 27/01/2026 9:13 pm, Nicolas Schier wrote: > On Thu, Jan 22, 2026 at 03:12:36PM +0100, Guillaume Tucker wrote: >> Hi Nicolas, >> >> On 20/01/2026 14:54, Nicolas Schier wrote: >>> Out-of-source builds do not work on my system with podman. If this is >>> expected, I think it would be great to mention that somewhere in the >>> documentation. >> >> The v4 now mentions this and also includes a trick using bind-mount: >> >> mkdir -p $HOME/tmp/my-kernel-build >> mkdir -p build >> sudo mount --bind $HOME/tmp/my-kernel-build build >> scripts/container -i kernel.org/gcc -- make mrproper >> scripts/container -i kernel.org/gcc -- make O=build defconfig >> scripts/container -i kernel.org/gcc -- make O=build -j$(nproc) >> >> Would this work for your use-case? Directory names are entirely >> arbitrary. It's not ideal but might be good enough as a workaround >> until this gets properly supported by the tool in a future version. > > sorry for the long delay. Yes, thanks for the follow-up! Great! Thank you for confirming. It's now in linux-next. Cheers, Guillaume
Hi Nicolas, On 20/01/2026 2:54 pm, Nicolas Schier wrote: > Out-of-source builds do not work on my system with podman. If this is > expected, I think it would be great to mention that somewhere in the > documentation. Yes, as discussed with Nathan. So here's the list of potential improvements gathered so far: * automatically pick Podman first, Docker second * explicitly mention docker.io registry in examples * mention TuxMake available images more explicitly in the docs * mention that out-of-tree builds aren't supported yet * distinguish true Docker from Docker-compatible Podman * add support for out-of-tree output build directory * add option for mounting source tree from arbitrary path (needed for nested containers e.g. Docker-in-Docker) * detect when Docker has namespace support enabled and document * add user config file with default images and runtime etc. Then beyond that we could consider other container runtimes such as containerd, lxc, runc or whatever works in practice. > Nevertheless, thanks a lot! I expect me to use that a lot in the > future! > > For the whole patch set: > Tested-by: Nicolas Schier<nsc@kernel.org> > Acked-by: Nicolas Schier<nsc@kernel.org> Thank you! Let's hope others will find it useful too. Cheers, Guillaume
On Tue, Jan 20, 2026 at 02:54:47PM +0100, Nicolas Schier wrote: > Out-of-source builds do not work on my system with podman. If this is > expected, I think it would be great to mention that somewhere in the > documentation. Yeah, that is expected for this revision of the script, I brought that up in a previous review: https://lore.kernel.org/20251219194748.GA1404325@ax162/ Cheers, Nathan
Hi Guillaume, On Wed, Dec 31, 2025 at 05:51:48PM +0100, Guillaume Tucker wrote: > This proposal emerged from discussions over email and after a talk at > Plumbers 2024: > > https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/ > > The aim is to facilitate reproducing builds for CI bots as well as > developers using containers. Here's an illustrative example with a > kernel.org toolchain in a Docker image from tuxmake: > > $ scripts/container -i tuxmake/korg-clang-21 make LLVM=1 defconfig > HOSTCC scripts/basic/fixdep > HOSTCC scripts/kconfig/conf.o > [...] > HOSTCC scripts/kconfig/util.o > HOSTLD scripts/kconfig/conf > *** Default configuration is based on 'x86_64_defconfig' > # > # configuration written to .config > # > > This patch series also includes a documentation page with all the > relevant details and further examples about how to use the tool. > > To go one step further, I'm in the process of preparing reference > container images with kernel.org toolchains and no third-party > dependencies other than the base Debian distro. See this thread for > more details and options to host them in an upstream way: > > https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/ > > Say, to run KUnit using the latest kernel.org GCC toolchain: > > scripts/container --shell \ > -i registry.gitlab.com/gtucker/korg-containers/gcc:kunit -- \ > tools/testing/kunit/kunit.py \ > run \ > --arch=x86_64 \ > --cross_compile=x86_64-linux- I went over the script and the documentation and it looks pretty good to me at this point. My only comment would be potentially referencing the TuxMake container images in the example section to give folks a "prebuilt" container option while getting the kernel.org container images sorted out but that can always be done in a follow-up change. I will apply this to kbuild-next-unstable shortly to give folks a week or so to voice any objections or give critical review comments. Cheers, Nathan
Hi Nathan,
On 19/01/2026 22:35, Nathan Chancellor wrote:
> I went over the script and the documentation and it looks pretty good to
> me at this point. My only comment would be potentially referencing the
> TuxMake container images in the example section to give folks a
> "prebuilt" container option while getting the kernel.org container
> images sorted out but that can always be done in a follow-up change.
Well the tuxmake LLVM image is mentioned in the first example:
scripts/container -i tuxmake/korg-clang -- make LLVM=1 defconfig
scripts/container -i tuxmake/korg-clang -- make LLVM=1 -j$(nproc)
So that should just work out of the box. Or did you mean to add
something else to the docs?
But yes, the topic of available container images will be something to
expand upon once the tool starts getting used. If things go well
with this initial version then we can try and move forward with
hosting first-party images as per the other discussion thread:
https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
> I will apply this to kbuild-next-unstable shortly to give folks a week
> or so to voice any objections or give critical review comments.
Sounds great, thanks! I'll spread the word too once it's available
in linux-next.
Cheers,
Guillaume
On Tue, Jan 20, 2026 at 10:46:15AM +0100, Guillaume Tucker wrote: > Well the tuxmake LLVM image is mentioned in the first example: > > scripts/container -i tuxmake/korg-clang -- make LLVM=1 defconfig > scripts/container -i tuxmake/korg-clang -- make LLVM=1 -j$(nproc) > > So that should just work out of the box. Or did you mean to add > something else to the docs? I was just envisioning a blurb like "Additionally, TuxMake has prebuilt containers for various architectures: https://hub.docker.com/u/tuxmake" or something like that at the end of the paragraph before "To build just ``bzImage`` using Clang::" in the documentation. > But yes, the topic of available container images will be something to > expand upon once the tool starts getting used. If things go well > with this initial version then we can try and move forward with > hosting first-party images as per the other discussion thread: > > https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/ Yeah hopefully usage of this tool will spur some movement on that discussion thread. Cheers, Nathan
On Mon, Jan 19, 2026 at 02:35:16PM -0700, Nathan Chancellor wrote: > I will apply this to kbuild-next-unstable shortly to give folks a week > or so to voice any objections or give critical review comments. During application, checkpatch.pl pointed out that this should have a MAINTAINERS entry. Would you be opposed to the following? CONTAINER BUILD SCRIPT M: Guillaume Tucker <gtucker@gtucker.io> S: Maintained F: Documentation/dev-tools/container.rst F: scripts/container I will also add scripts/container to the kbuild entry. Now that I am looking, it looks like Nicolas has been left out of this whole thread, cc'ing him now (even though I assume he should have seen this through linux-kbuild but just in case not, the top of the thread is https://lore.kernel.org/cover.1767199119.git.gtucker@gtucker.io/). Cheers, Nathan
On 19/01/2026 22:49, Nathan Chancellor wrote: > On Mon, Jan 19, 2026 at 02:35:16PM -0700, Nathan Chancellor wrote: >> I will apply this to kbuild-next-unstable shortly to give folks a week >> or so to voice any objections or give critical review comments. > > During application, checkpatch.pl pointed out that this should have a > MAINTAINERS entry. Would you be opposed to the following? Not at all, on the contrary I have some dedicated time and long-term interest to keep maintaining this. Please feel free to add me or I can send an extra patch if you'd rather I did it. > CONTAINER BUILD SCRIPT > M: Guillaume Tucker <gtucker@gtucker.io> > S: Maintained > F: Documentation/dev-tools/container.rst > F: scripts/container > > I will also add scripts/container to the kbuild entry. Now that I am > looking, it looks like Nicolas has been left out of this whole thread, > cc'ing him now (even though I assume he should have seen this through > linux-kbuild but just in case not, the top of the thread is > https://lore.kernel.org/cover.1767199119.git.gtucker@gtucker.io/). OK sounds good. And sorry, get_maintainer.pl didn't mention Nicolas. I should have checked the KERNEL BUILD entry by hand in the file... Cheers, Guillaume
On Tue, Jan 20, 2026 at 10:56:46AM +0100, Guillaume Tucker wrote: > Not at all, on the contrary I have some dedicated time and long-term > interest to keep maintaining this. Please feel free to add me or I > can send an extra patch if you'd rather I did it. I can fold that into the two changes in a natural way. > OK sounds good. And sorry, get_maintainer.pl didn't mention Nicolas. > I should have checked the KERNEL BUILD entry by hand in the file... No worries, I am sure there are quite a few scripts that we technically own but do not have an entry for it in MAINTAINERS. This won't be a problem going forward at least :)
Hello, On 31/12/2025 17:51, Guillaume Tucker wrote: > Changes in v3: > - Refactor common code for Docker and Podman > - Add docs.kernel.org URL in help message > - Use pathlib Python package > - Handle signals in parent process by default > - Add --shell option to use an interactive shell > - Tweak debug messages in verbose mode > - Specify Python 3.10 as minimum version in the docs > - Provide an example env file in the docs > - Update docs regarding interactive shell usage I'm sure you're all busy landing commits ahead of the next merge window. Could you please take a look at this v3 when you have a moment? I believe I've addressed everything from previous reviews. Thanks, Guillaume
Hi Guillaume, On Fri, Jan 16, 2026 at 11:28:24AM +0100, Guillaume Tucker wrote: > Hello, > > On 31/12/2025 17:51, Guillaume Tucker wrote: > > Changes in v3: > > - Refactor common code for Docker and Podman > > - Add docs.kernel.org URL in help message > > - Use pathlib Python package > > - Handle signals in parent process by default > > - Add --shell option to use an interactive shell > > - Tweak debug messages in verbose mode > > - Specify Python 3.10 as minimum version in the docs > > - Provide an example env file in the docs > > - Update docs regarding interactive shell usage > > I'm sure you're all busy landing commits ahead of the next merge > window. Could you please take a look at this v3 when you have a > moment? I believe I've addressed everything from previous reviews. So sorry for the radio silence. I was going to try and look at this today to give feedback before the weekend but I will not be able to look at it until Monday. Given that this is self-contained (no pun intended) with no regression risks, I would have no qualms with applying this late in the development cycle. Cheers, Nathan
Hi Nathan, On 16/01/2026 10:12 pm, Nathan Chancellor wrote: > Hi Guillaume, > > On Fri, Jan 16, 2026 at 11:28:24AM +0100, Guillaume Tucker wrote: >> Hello, >> >> On 31/12/2025 17:51, Guillaume Tucker wrote: >>> Changes in v3: >>> - Refactor common code for Docker and Podman >>> - Add docs.kernel.org URL in help message >>> - Use pathlib Python package >>> - Handle signals in parent process by default >>> - Add --shell option to use an interactive shell >>> - Tweak debug messages in verbose mode >>> - Specify Python 3.10 as minimum version in the docs >>> - Provide an example env file in the docs >>> - Update docs regarding interactive shell usage >> >> I'm sure you're all busy landing commits ahead of the next merge >> window. Could you please take a look at this v3 when you have a >> moment? I believe I've addressed everything from previous reviews. > > So sorry for the radio silence. I was going to try and look at this > today to give feedback before the weekend but I will not be able to look > at it until Monday. Given that this is self-contained (no pun intended) > with no regression risks, I would have no qualms with applying this late > in the development cycle. Thanks for getting back to me, that's great. I'll keep working on some follow-up improvements in the meantime, regardless of the pace of the review process. Cheers, Guillaume
© 2016 - 2026 Red Hat, Inc.