* Re: [PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert
From: Alexey Dobriyan @ 2025-12-27 14:51 UTC (permalink / raw)
To: David Laight; +Cc: corbet, workflows, linux-kernel
In-Reply-To: <20250513204031.26f50209@pumpkin>
On Tue, May 13, 2025 at 08:40:31PM +0100, David Laight wrote:
> On Fri, 9 May 2025 23:34:27 +0300
> Alexey Dobriyan <adobriyan@gmail.com> wrote:
>
> > Linux's BUG_ON is done backwards (condition is inverted).
> > But it is a long story.
> >
> > However C11/C23 allow to partially transition to what all normal
> > programmers are used to, namely assert().
> >
> > Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
> > And then some day BUG_ON will be flipped as well.
>
> _Static_assert() is broken by design and only usable for trival tests.
It is not broken by design. I was going to recommend it
for "static_assert(sizeof(struct S) == ...)" type of things. For ABI types and
similar stuff.
BTW BUILD_BUG_ON is broken by design too, there are places with fake functions
for a block so that they can put statement in.
> clang also output the entire expansion of the conditional (even when
> a message is specified) which can lead to very very very very long lines.
Oh, that's very unfortunate.
> It isn't at all suitable for many of the checks in the kernel.
STATIC_ASSERT could be arranged.
> Look at the signedness test in min() as an example.
The very fact you all made giant mess trying to imitate min<T, U>()
should not block progress of using standard (and better!) stuff.
^ permalink raw reply
* Re: [PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert
From: David Laight @ 2025-12-27 19:45 UTC (permalink / raw)
To: Alexey Dobriyan; +Cc: corbet, workflows, linux-kernel
In-Reply-To: <c6f0c3d8-eb2b-49e1-b874-610fbeb248e4@p183>
On Sat, 27 Dec 2025 17:51:49 +0300
Alexey Dobriyan <adobriyan@gmail.com> wrote:
> On Tue, May 13, 2025 at 08:40:31PM +0100, David Laight wrote:
> > On Fri, 9 May 2025 23:34:27 +0300
> > Alexey Dobriyan <adobriyan@gmail.com> wrote:
> >
> > > Linux's BUG_ON is done backwards (condition is inverted).
> > > But it is a long story.
> > >
> > > However C11/C23 allow to partially transition to what all normal
> > > programmers are used to, namely assert().
> > >
> > > Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
> > > And then some day BUG_ON will be flipped as well.
> >
> > _Static_assert() is broken by design and only usable for trival tests.
>
> It is not broken by design. I was going to recommend it
> for "static_assert(sizeof(struct S) == ...)" type of things. For ABI types and
> similar stuff.
As I said, it can only be used for trivial tests.
Checking the sizes on structures is one of them.
You can't put one inside a compile-time conditional and the tested value
has to be an 'integer constant expression' not just a 'compile time constant'.
In particular that means you can't use it to check constant parameters to
inline functions or variables defined within statements blocks.
When I was rewriting min() there was an outer builtin_choose_expr(),
_Static_assert() within the 'unselected' expression would trip.
That really isn't what you want.
So there are many places where BUILD_BUG_ON() can be used but
_Static_assert() cannot be used.
BUILD_BUG_ON() cannot be deprecated until there is a working replacement.
That won't happen until the C language group actually understand how the
language is actually used :-)
The _Pragma(warning/error...) are just as useless.
They can only report things detected by pre-processor conditionals,
not checks that rely on the optimiser to have deleted unreachable code.
>
> BTW BUILD_BUG_ON is broken by design too, there are places with fake functions
> for a block so that they can put statement in.
It works 'as designed' within the constraints of the language.
The error message required a log of 'lateral thought'.
Some of the 'fake functions' may well be replaceable with something
based on _Static_assert() - but that is only a small number.
>
> > clang also output the entire expansion of the conditional (even when
> > a message is specified) which can lead to very very very very long lines.
>
> Oh, that's very unfortunate.
>
> > It isn't at all suitable for many of the checks in the kernel.
>
> STATIC_ASSERT could be arranged.
>
> > Look at the signedness test in min() as an example.
>
> The very fact you all made giant mess trying to imitate min<T, U>()
> should not block progress of using standard (and better!) stuff.
There are other 'sanity' checks like those in FIELD_PREP().
Without assigning the parameters to local variables the expansion
of FIELD_PREP(GENMASK(8, 5) val) comes to around 18KB.
And that is a typical use - not the triple-nests min() that came
out as multi-megabyte and broke compilation.
David
^ permalink raw reply
* Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h
From: Andy Shevchenko @ 2025-12-28 18:02 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Randy Dunlap, Dr. David Alan Gilbert, linux-doc, linux-kernel,
workflows, linux-remoteproc, Greg Kroah-Hartman,
Rafael J. Wysocki, Danilo Krummrich, Dwaipayan Ray, Lukas Bulwahn,
Joe Perches, Bjorn Andersson, Mathieu Poirier
In-Reply-To: <87fr9218jr.fsf@trenco.lwn.net>
On Mon, Dec 22, 2025 at 03:00:24PM -0700, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
>
> > For several years, and still ongoing, the kernel.h is being split
> > to smaller and narrow headers to avoid "including everything" approach
> > which is bad in many ways. Since that, documentation missed a few
> > required updates to align with that work. Do it here.
> >
> > Note, language translations are left untouched and if anybody willing
> > to help, please provide path(es) based on the updated English variant.
> >
> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> > ---
> >
> > v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
> >
> > Documentation/core-api/kobject.rst | 2 +-
> > Documentation/dev-tools/checkpatch.rst | 2 +-
> > Documentation/driver-api/basics.rst | 17 ++++++++++++++++-
> > .../driver-api/driver-model/design-patterns.rst | 2 +-
> > Documentation/process/coding-style.rst | 10 +++++++---
> > Documentation/staging/rpmsg.rst | 7 +++++--
> > include/linux/util_macros.h | 2 +-
> > 7 files changed, 32 insertions(+), 10 deletions(-)
>
> Applied (finally) thanks.
Thank you! I leave the translations to the respective maintainers and native
speakers to decide.
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* [PATCH 0/3] scripts: coccicheck: document debug log handling
From: Benjamin Philip @ 2025-12-28 19:31 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
Currently coccicheck prints debug logs to stdout unless a debug file has been
set. This makes it hard to read coccinelle's suggested changes, especially for
someone new to coccicheck.
This patchset documents this behaviour in both the coccicheck script as well as
in the dev-tools documentation. Additionally, it simplifies some of the logic
for handling debug files.
Benjamin Philip (3):
scripts: coccicheck: simplify debug file handling
scripts: coccicheck: warn on unset debug file
Documentation: Coccinelle: document debug log handling
Documentation/dev-tools/coccinelle.rst | 21 ++++++++++++++++-----
scripts/coccicheck | 21 +++++++++++++--------
2 files changed, 29 insertions(+), 13 deletions(-)
--
2.52.0
^ permalink raw reply
* [PATCH 1/3] scripts: coccicheck: simplify debug file handling
From: Benjamin Philip @ 2025-12-28 19:34 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <CAMEXYWegtqikPYBRaZcpd_JwQPH80cXhaRK66J8ZhWPrYc7-yw@mail.gmail.com>
This commit separates handling unset files and pre-existing files. It
also eliminates a duplicated check for unset files in run_cmd_parmap().
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
scripts/coccicheck | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/scripts/coccicheck b/scripts/coccicheck
index 89d591af5f3e..2efb74afef2b 100755
--- a/scripts/coccicheck
+++ b/scripts/coccicheck
@@ -138,7 +138,7 @@ run_cmd_parmap() {
if [ $VERBOSE -ne 0 ] ; then
echo "Running ($NPROC in parallel): $@"
fi
- if [ "$DEBUG_FILE" != "/dev/null" -a "$DEBUG_FILE" != "" ]; then
+ if [ "$DEBUG_FILE" != "/dev/null" ]; then
echo $@>>$DEBUG_FILE
$@ 2>>$DEBUG_FILE
else
@@ -259,13 +259,13 @@ coccinelle () {
}
-if [ "$DEBUG_FILE" != "/dev/null" -a "$DEBUG_FILE" != "" ]; then
- if [ -f $DEBUG_FILE ]; then
- echo "Debug file $DEBUG_FILE exists, bailing"
- exit
- fi
-else
- DEBUG_FILE="/dev/null"
+if [ "$DEBUG_FILE" = "" ]; then
+ DEBUG_FILE="/dev/null"
+fi
+
+if [ -f $DEBUG_FILE ]; then
+ echo "Debug file $DEBUG_FILE exists, bailing"
+ exit
fi
if [ "$COCCI" = "" ] ; then
--
2.52.0
^ permalink raw reply related
* [PATCH 2/3] scripts: coccicheck: warn on unset debug file
From: Benjamin Philip @ 2025-12-28 19:34 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <20251228193417.1143676-1-benjamin.philip495@gmail.com>
coccicheck prints debug logs to stdout unless a debug file has been set.
This makes it hard to read coccinelle's suggested changes, especially
for someone new to coccicheck.
From this commit, we warn about this behaviour from within the script on
an unset debug file. Explicitly setting the debug file to /dev/null
suppresses the warning while keeping the default.
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
scripts/coccicheck | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/scripts/coccicheck b/scripts/coccicheck
index 2efb74afef2b..8dd766009de1 100755
--- a/scripts/coccicheck
+++ b/scripts/coccicheck
@@ -260,6 +260,11 @@ coccinelle () {
}
if [ "$DEBUG_FILE" = "" ]; then
+ echo 'You have not explicitly specified the debug file to use.'
+ echo 'Using default "/dev/null" as debug file.'
+ echo 'Debug logs will be printed to stdout.'
+ echo 'You can specify the debug file with "make coccicheck
DEBUG_FILE=<debug_file>"'
+ echo ''
DEBUG_FILE="/dev/null"
fi
--
2.52.0
^ permalink raw reply related
* [PATCH 2/3] scripts: coccicheck: warn on unset debug file
From: Benjamin Philip @ 2025-12-28 19:36 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <CAMEXYWegtqikPYBRaZcpd_JwQPH80cXhaRK66J8ZhWPrYc7-yw@mail.gmail.com>
coccicheck prints debug logs to stdout unless a debug file has been set.
This makes it hard to read coccinelle's suggested changes, especially
for someone new to coccicheck.
From this commit, we warn about this behaviour from within the script on
an unset debug file. Explicitly setting the debug file to /dev/null
suppresses the warning while keeping the default.
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
scripts/coccicheck | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/scripts/coccicheck b/scripts/coccicheck
index 2efb74afef2b..8dd766009de1 100755
--- a/scripts/coccicheck
+++ b/scripts/coccicheck
@@ -260,6 +260,11 @@ coccinelle () {
}
if [ "$DEBUG_FILE" = "" ]; then
+ echo 'You have not explicitly specified the debug file to use.'
+ echo 'Using default "/dev/null" as debug file.'
+ echo 'Debug logs will be printed to stdout.'
+ echo 'You can specify the debug file with "make coccicheck
DEBUG_FILE=<debug_file>"'
+ echo ''
DEBUG_FILE="/dev/null"
fi
--
2.52.0
^ permalink raw reply related
* [PATCH 3/3] Documentation: Coccinelle: document debug log handling
From: Benjamin Philip @ 2025-12-28 19:36 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <CAMEXYWegtqikPYBRaZcpd_JwQPH80cXhaRK66J8ZhWPrYc7-yw@mail.gmail.com>
The current debug documentation does not mention that logs are printed
to stdout unless DEBUG_FILE is set. It also doesn't mention that
Coccinelle cannot overwrite debug files.
Document this behaviour in the examples and reference it in the
debugging section.
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
Documentation/dev-tools/coccinelle.rst | 21 ++++++++++++++++-----
1 file changed, 16 insertions(+), 5 deletions(-)
diff --git a/Documentation/dev-tools/coccinelle.rst
b/Documentation/dev-tools/coccinelle.rst
index 6e70a1e9a3c0..c714780d458a 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -127,6 +127,18 @@ To enable verbose messages set the V= variable,
for example::
make coccicheck MODE=report V=1
+By default, coccicheck will print debug logs to stdout and redirect stderr to
+/dev/null. This can make coccicheck output difficult to read and understand.
+Debug and error messages can instead be written to a debug file instead by
+setting the ``DEBUG_FILE`` variable::
+
+ make coccicheck MODE=report DEBUG_FILE="cocci.log"
+
+Coccinelle cannot overwrite a debug file. Instead of repeatedly deleting a log
+file, you could include the datetime in the debug file name::
+
+ make coccicheck MODE=report DEBUG_FILE="cocci-$(date -Iseconds).log"
+
Coccinelle parallelization
--------------------------
@@ -208,11 +220,10 @@ include options matching the options used when
we compile the kernel.
You can learn what these options are by using V=1; you could then
manually run Coccinelle with debug options added.
-Alternatively you can debug running Coccinelle against SmPL patches
-by asking for stderr to be redirected to stderr. By default stderr
-is redirected to /dev/null; if you'd like to capture stderr you
-can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
-instance::
+An easier approach to debug running Coccinelle against SmPL patches is to ask
+coccicheck to redirect stderr to a debug file. As mentioned in the examples, by
+default stderr is redirected to /dev/null; if you'd like to capture stderr you
+can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For instance::
rm -f cocci.err
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci
MODE=report DEBUG_FILE=cocci.err
--
2.52.0
^ permalink raw reply related
* Re: [PATCH v2 2/2] Documentation: dev-tools: add container.rst page
From: Nathan Chancellor @ 2025-12-30 20:16 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <23c38222-ba4b-4728-8ad6-8bb02c5a2d3a@gtucker.io>
Hi Guillaume,
On Sun, Dec 21, 2025 at 09:13:33PM +0100, Guillaume Tucker wrote:
> On 18/12/2025 1:49 pm, Guillaume Tucker wrote:
> > +User IDs
> > +========
> > +
> > +This is an area where the behaviour will vary slightly depending on the
> > +container runtime. The goal is to run commands as the user invoking the tool.
> > +With Podman, a namespace is created to map the current user id to a different
> > +one in the container (1000 by default). With Docker, while this is also
> > +possible with recent versions it requires a special feature to be enabled in
> > +the daemon so it's not used here for simplicity. Instead, the container is run
> > +with the current user id directly. In both cases, this will provide the same
> > +file permissions for the kernel source tree mounted as a volume. The only
> > +difference is that when using Docker without a namespace, the user id may not
> > +be the same as the default one set in the image.
> > +
> > +Say, we're using an image which sets up a default user with id 1000 and the
> > +current user calling the ``container`` tool has id 1234. The kernel source
> > +tree was checked out by this same user so the files belong to user 1234. With
> > +Podman, the container will be running as user id 1000 with a mapping to id 1234
> > +so that the files from the mounted volume appear to belong to id 1000 inside
> > +the container. With Docker and no namespace, the container will be running
> > +with user id 1234 which can access the files in the volume but not in the user
> > +1000 home directory. This shouldn't be an issue when running commands only in
> > +the kernel tree but it is worth highlighting here as it might matter for
> > +special corner cases.
>
> This part of the docs explains why things are a bit different between
> Podman and Docker. In both cases, it should "just work" from a user
> point of view - just with some special corner cases. Let me know if
> you thing the documentation needs to be improved.
Ah, I had missed that on my skim through of the documentation plus I did
not have it side by side with the script while I was reviewing it.
> I may add a runtime check as a follow-up to detect if namespaces are
> enabled in Docker and if so use them, but to get started I wanted to
> keep things as simple as possible.
Yeah, I agree with keeping things simple up front.
Cheers,
Nathan
^ permalink raw reply
* Re: [PATCH v2 1/2] scripts: add tool to run containerized builds
From: Nathan Chancellor @ 2025-12-30 20:23 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <50ee5ec6-ca9b-486d-ac7e-5a896006a9de@gtucker.io>
On Sun, Dec 21, 2025 at 09:09:17PM +0100, Guillaume Tucker wrote:
> On 19/12/2025 10:27 pm, Nathan Chancellor wrote:
> > On Thu, Dec 18, 2025 at 01:49:52PM +0100, Guillaume Tucker wrote:
> > ...
> > > + def __init__(self, args, logger):
> > Adding something like
> >
> > self._args = [
> > '--rm',
> > '--tty',
> > '--volume', f'{os.getcwd()}:/src',
> > '--workdir', '/src',
> > ]
> >
> > here then adding an __init__() in the subclasses to append the runtime
> > specific arguments would allow _do_run() to be moved into
> > ContainerRuntime(). Otherwise, this looks pretty good and extensible.
>
> Yes, I left these very similar parts as-is on purpose to make it very
> clear what the command line arguments are for each container runtime.
> It's a good idea to refactor this though as you mention, and I'll add
> a debug log message to print the command line instead.
>
> I'm also anticipating that other runtimes will be quite different,
> Podman and Docker just so happen to have many options in common.
> Things like runc or containerd are very different beasts so I don't
> want to over-generalise. But this is straightforward enough for now.
Yeah, I had figured that might have been the reason for keeping these
things separate, which does make sense. At the same time, I would rather
keep things simple and shared now since we can with no other runtimes
supported. If we want to add new runtimes in the future, undoing this
should be simple enough and make it obvious to see why the separation is
happening.
> So I'll rework this a bit in a v3.
Thanks a lot!
Cheers,
Nathan
^ permalink raw reply
* Re: [PATCH v1 1/2] scripts: add tool to run containerized builds
From: Guillaume Tucker @ 2025-12-31 16:54 UTC (permalink / raw)
To: Nathan Chancellor
Cc: Miguel Ojeda, linux-kernel, rust-for-linux, linux-kbuild,
automated-testing, workflows, llvm, Arnd Bergmann
In-Reply-To: <20251219194748.GA1404325@ax162>
Hi Nathan,
Thanks for the follow-up reviews, I just sent a v3. Here's a couple
more things I didn't address in your original email.
> One initial comment (or perhaps feature request) would be handling O= /
> KBUILD_OUTPUT for building out of tree. It may be a little complicated
> for mounting the build directory into the container but it might make it
> easier for folks who build out of tree to use.
Yes, that could be done but I would prefer to add it incrementally
rather than in the initial version. Handling a build output
directory outside of the source tree means that the "make O=" option
would need to be provided in coordination with the data volume e.g.:
container --output=$HOME/my/directory:/data/output -- make O=/data/output
We could rely on a convention for /data/output but then I don't
really want to start parsing and patching the "make" arguments yet.
A workaround is to bind-mount your build directory inside the tree
and then just pass "make O=" in the container, but that comes with
some caveats too (root privilege, potential security issues).
On a related note, I did a quick experiment with a "container -C"
option to mount the source tree from elsewhere than the current
working directory as that can be done independently of the command
run inside the container. It's needed for Docker-in-Docker as you
have to provide the path on the host to mount volumes. Other than
that I'm not entirely sure how useful this may be so I'm leaving it
aside for now as well.
> Is there a minimum python version required for this? If not, I would
> prefer using pathlib here:
>
> from pathlib import Path
>
> then
>
> Path.cwd()
>
Sure, the pathlib package was added in Python 3.4 so that's ancient
enough. I reworked this part in the v3 series and added a note in
the docs setting Python 3.10 as a reasonable minimum requirement.
> Is there documentation for how an environment file should be formatter?
I added something about this in the v3 docs, essentially the file is
passed as-is to the container runtime so it's not for the container
script itself to parse it. The short answer is that it should look
like the output of the env command.
Cheers,
Guillaume
^ permalink raw reply
* [PATCH v3 2/2] Documentation: dev-tools: add container.rst page
From: Guillaume Tucker @ 2025-12-31 16:51 UTC (permalink / raw)
To: Nathan Chancellor, Miguel Ojeda, David Gow, Onur Özkan
Cc: Guillaume Tucker, Arnd Bergmann, linux-kernel, rust-for-linux,
linux-kbuild, automated-testing, workflows, llvm
In-Reply-To: <cover.1767199119.git.gtucker@gtucker.io>
Add a dev-tools/container.rst documentation page for the
scripts/container tool. This covers the basic usage with additional
information about environment variables and user IDs. It also
includes a number of practical examples with a reference to the
experimental kernel.org toolchain images.
Cc: Nathan Chancellor <nathan@kernel.org>
Cc: Miguel Ojeda <ojeda@kernel.org>
Cc: David Gow <davidgow@google.com>
Cc: "Onur Özkan" <work@onurozkan.dev>
Signed-off-by: Guillaume Tucker <gtucker@gtucker.io>
---
Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++
Documentation/dev-tools/index.rst | 1 +
2 files changed, 202 insertions(+)
create mode 100644 Documentation/dev-tools/container.rst
diff --git a/Documentation/dev-tools/container.rst b/Documentation/dev-tools/container.rst
new file mode 100644
index 000000000000..f6f134ec09f5
--- /dev/null
+++ b/Documentation/dev-tools/container.rst
@@ -0,0 +1,201 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2025 Guillaume Tucker
+
+====================
+Containerized Builds
+====================
+
+The ``container`` tool can be used to run any command in the kernel source tree
+from within a container. Doing so facilitates reproducing builds across
+various platforms, for example when a test bot has reported an issue which
+requires a specific version of a compiler or an external test suite. While
+this can already be done by users who are familiar with containers, having a
+dedicated tool in the kernel tree lowers the barrier to entry by solving common
+problems once and for all (e.g. user id management). It also makes it easier
+to share an exact command line leading to a particular result. The main use
+case is likely to be kernel builds but virtually anything can be run: KUnit,
+checkpatch etc. provided a suitable image is available.
+
+
+Options
+=======
+
+Command line syntax::
+
+ scripts/container -i IMAGE [OPTION]... CMD...
+
+Available options:
+
+``-e, --env-file ENV_FILE``
+
+ Path to an environment file to load in the container.
+
+``-g, --gid GID``
+
+ Group id to use inside the container.
+
+``-i, --image IMAGE``
+
+ Container image name (required).
+
+``-r, --runtime RUNTIME``
+
+ Container runtime name. Supported runtimes: ``docker``, ``podman``.
+
+ If not specified, the first one found on the system will be used
+ i.e. Docker if present, otherwise Podman.
+
+``-s, --shell``
+
+ Run the container in an interactive shell.
+
+``-u, --uid UID``
+
+ User id to use inside the container.
+
+ If the ``-g`` option is not specified, the user id will also be used for
+ the group id.
+
+``-v, --verbose``
+
+ Enable verbose output.
+
+``-h, --help``
+
+ Show the help message and exit.
+
+
+Usage
+=====
+
+It's entirely up to the user to choose which image to use and the ``CMD``
+arguments are passed directly as an arbitrary command line to run in the
+container. The tool will take care of mounting the source tree as the current
+working directory and adjust the user and group id as needed.
+
+The container image which would typically include a compiler toolchain is
+provided by the user and selected via the ``-i`` option. The container runtime
+can be selected with the ``-r`` option, which can be either ``docker`` or
+``podman``. If none is specified, the first one found on the system will be
+used. Support for other runtimes may be added later depending on their
+popularity among users.
+
+By default, commands are run non-interactively. The user can abort a running
+container with SIGINT (Ctrl-C). To run commands interactively with a TTY, the
+``--shell`` or ``-s`` option can be used. Signals will then be received by the
+shell directly rather than the parent ``container`` process. To exit an
+interactive shell, use Ctrl-D or ``exit``.
+
+.. note::
+
+ The only host requirement aside from a container runtime is Python 3.10 or
+ later.
+
+
+Environment Variables
+=====================
+
+Environment variables are not propagated to the container so they have to be
+either defined in the image itself or via the ``-e`` option using an
+environment file. In some cases it makes more sense to have them defined in
+the Containerfile used to create the image. For example, a Clang-only compiler
+toolchain image may have ``LLVM=1`` defined.
+
+The local environment file is more useful for user-specific variables added
+during development. It is passed as-is to the container runtime so its format
+may vary. Typically, it will look like the output of ``env``. For example::
+
+ INSTALL_MOD_STRIP=1
+ SOME_RANDOM_TEXT=One upon a time
+
+Please also note that ``make`` options can still be passed on the command line,
+so while this can't be done since the first argument needs to be the
+executable::
+
+ scripts/container -i tuxmake/korg-clang LLVM=1 make
+
+this will work::
+
+ scripts/container -i tuxmake/korg-clang make LLVM=1
+
+
+User IDs
+========
+
+This is an area where the behaviour will vary slightly depending on the
+container runtime. The goal is to run commands as the user invoking the tool.
+With Podman, a namespace is created to map the current user id to a different
+one in the container (1000 by default). With Docker, while this is also
+possible with recent versions it requires a special feature to be enabled in
+the daemon so it's not used here for simplicity. Instead, the container is run
+with the current user id directly. In both cases, this will provide the same
+file permissions for the kernel source tree mounted as a volume. The only
+difference is that when using Docker without a namespace, the user id may not
+be the same as the default one set in the image.
+
+Say, we're using an image which sets up a default user with id 1000 and the
+current user calling the ``container`` tool has id 1234. The kernel source
+tree was checked out by this same user so the files belong to user 1234. With
+Podman, the container will be running as user id 1000 with a mapping to id 1234
+so that the files from the mounted volume appear to belong to id 1000 inside
+the container. With Docker and no namespace, the container will be running
+with user id 1234 which can access the files in the volume but not in the user
+1000 home directory. This shouldn't be an issue when running commands only in
+the kernel tree but it is worth highlighting here as it might matter for
+special corner cases.
+
+
+Examples
+========
+
+The shortest example is to run a basic kernel build using the default runtime
+(e.g. Docker) and a ``tuxmake`` Clang image::
+
+ scripts/container -i tuxmake/korg-clang -- make LLVM=1 defconfig
+ scripts/container -i tuxmake/korg-clang -- make LLVM=1 -j$(nproc)
+
+.. note::
+
+ When running a command with options within the container, it should be
+ separated with a double dash ``--`` to not confuse them with the
+ ``container`` tool options. Plain commands with no options don't strictly
+ require the double dashes e.g.::
+
+ scripts/container -i tuxmake/korg-clang make mrproper
+
+To run ``checkpatch.pl`` in a ``patches`` directory with a generic image::
+
+ scripts/container -i perl:slim-trixie scripts/checkpatch.pl patches/*
+
+The examples below refer to ``kernel.org`` images which are based on the
+`kernel.org compiler toolchains
+<https://mirrors.edge.kernel.org/pub/tools/>`__. These aren't (yet) officially
+available in any public registry but users can build their own locally instead
+using this `experimental repository
+<https://gitlab.com/gtucker/korg-containers>`__ by running ``make
+PREFIX=kernel.org/``.
+
+To build just ``bzImage`` using Clang::
+
+ scripts/container -i kernel.org/clang -- make bzImage -j$(nproc)
+
+Same with GCC 15 as a particular version tag::
+
+ scripts/container -i kernel.org/gcc:15 -- make bzImage -j$(nproc)
+
+To run KUnit in an interactive shell and get the full output::
+
+ scripts/container -s -i kernel.org/gcc:kunit -- \
+ tools/testing/kunit/kunit.py \
+ run \
+ --arch=x86_64 \
+ --cross_compile=x86_64-linux-
+
+To just start an interactive shell::
+
+ scripts/container -si kernel.org/gcc bash
+
+To build the HTML documentation, which requires the ``kdocs`` image built with
+``make PREFIX=kernel.org/ extra`` as it's not a compiler toolchain::
+
+ scripts/container -i kernel.org/kdocs make htmldocs
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 4b8425e348ab..527a0e4cf2ed 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -38,6 +38,7 @@ Documentation/process/debugging/index.rst
gpio-sloppy-logic-analyzer
autofdo
propeller
+ container
.. only:: subproject and html
--
2.47.3
^ permalink raw reply related
* [PATCH v3 1/2] scripts: add tool to run containerized builds
From: Guillaume Tucker @ 2025-12-31 16:51 UTC (permalink / raw)
To: Nathan Chancellor, Miguel Ojeda, David Gow, Onur Özkan
Cc: Guillaume Tucker, Arnd Bergmann, linux-kernel, rust-for-linux,
linux-kbuild, automated-testing, workflows, llvm
In-Reply-To: <cover.1767199119.git.gtucker@gtucker.io>
Add a 'scripts/container' tool written in Python to run any command in
the source tree from within a container. This can typically be used
to call 'make' with a compiler toolchain image to run reproducible
builds but any arbitrary command can be run too. Only Docker and
Podman are supported in this initial version.
Cc: Nathan Chancellor <nathan@kernel.org>
Cc: Miguel Ojeda <ojeda@kernel.org>
Cc: David Gow <davidgow@google.com>
Cc: "Onur Özkan" <work@onurozkan.dev>
Link: https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/
Signed-off-by: Guillaume Tucker <gtucker@gtucker.io>
---
scripts/container | 199 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 199 insertions(+)
create mode 100755 scripts/container
diff --git a/scripts/container b/scripts/container
new file mode 100755
index 000000000000..dbe92630f05b
--- /dev/null
+++ b/scripts/container
@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright (C) 2025 Guillaume Tucker
+
+"""Containerized builds"""
+
+import abc
+import argparse
+import logging
+import os
+import pathlib
+import shutil
+import subprocess
+import sys
+import uuid
+
+
+class ContainerRuntime(abc.ABC):
+ """Base class for a container runtime implementation"""
+
+ name = None # Property defined in each implementation class
+
+ def __init__(self, args, logger):
+ self._uid = args.uid or os.getuid()
+ self._gid = args.gid or args.uid or os.getgid()
+ self._env_file = args.env_file
+ self._shell = args.shell
+ self._logger = logger
+
+ @classmethod
+ def is_present(cls):
+ """Determine whether the runtime is present on the system"""
+ return shutil.which(cls.name) is not None
+
+ @abc.abstractmethod
+ def _do_run(self, image, cmd, container_name):
+ """Runtime-specific handler to run a command in a container"""
+
+ @abc.abstractmethod
+ def _do_abort(self, container_name):
+ """Runtime-specific handler to abort a running container"""
+
+ def run(self, image, cmd):
+ """Run a command in a runtime container"""
+ container_name = str(uuid.uuid4())
+ self._logger.debug("container: %s", container_name)
+ try:
+ return self._do_run(image, cmd, container_name)
+ except KeyboardInterrupt:
+ self._logger.error("user aborted")
+ self._do_abort(container_name)
+ return 1
+
+
+class CommonRuntime(ContainerRuntime):
+ """Common logic for Docker and Podman"""
+
+ def _do_run(self, image, cmd, container_name):
+ cmdline = [self.name, 'run']
+ cmdline += self._get_opts(container_name)
+ cmdline.append(image)
+ cmdline += cmd
+ self._logger.debug('command: %s', ' '.join(cmdline))
+ return subprocess.call(cmdline)
+
+ def _get_opts(self, container_name):
+ opts = [
+ '--name', container_name,
+ '--rm',
+ '--volume', f'{pathlib.Path.cwd()}:/src',
+ '--workdir', '/src',
+ ]
+ if self._env_file:
+ opts += ['--env-file', self._env_file]
+ if self._shell:
+ opts += ['--interactive', '--tty']
+ return opts
+
+ def _do_abort(self, container_name):
+ subprocess.call([self.name, 'kill', container_name])
+
+
+class DockerRuntime(CommonRuntime):
+ """Run a command in a Docker container"""
+
+ name = 'docker'
+
+ def _get_opts(self, container_name):
+ return super()._get_opts(container_name) + [
+ '--user', f'{self._uid}:{self._gid}'
+ ]
+
+
+class PodmanRuntime(CommonRuntime):
+ """Run a command in a Podman container"""
+
+ name = 'podman'
+
+ def _get_opts(self, container_name):
+ return super()._get_opts(container_name) + [
+ '--userns', f'keep-id:uid={self._uid},gid={self._gid}',
+ ]
+
+
+class Runtimes:
+ """List of all supported runtimes"""
+
+ runtimes = [DockerRuntime, PodmanRuntime]
+
+ @classmethod
+ def get_names(cls):
+ """Get a list of all the runtime names"""
+ return list(runtime.name for runtime in cls.runtimes)
+
+ @classmethod
+ def get(cls, name):
+ """Get a single runtime class matching the given name"""
+ for runtime in cls.runtimes:
+ if runtime.name == name:
+ if not runtime.is_present():
+ raise ValueError(f"runtime not found: {name}")
+ return runtime
+ raise ValueError(f"unknown runtime: {runtime}")
+
+ @classmethod
+ def find(cls):
+ """Find the first runtime present on the system"""
+ for runtime in cls.runtimes:
+ if runtime.is_present():
+ return runtime
+ raise ValueError("no runtime found")
+
+
+def _get_logger(verbose):
+ """Set up a logger with the appropriate level"""
+ logger = logging.getLogger('container')
+ handler = logging.StreamHandler()
+ handler.setFormatter(logging.Formatter(
+ fmt='[container {levelname}] {message}', style='{'
+ ))
+ logger.addHandler(handler)
+ logger.setLevel(logging.DEBUG if verbose is True else logging.INFO)
+ return logger
+
+
+def main(args):
+ """Main entry point for the container tool"""
+ logger = _get_logger(args.verbose)
+ try:
+ cls = Runtimes.get(args.runtime) if args.runtime else Runtimes.find()
+ except ValueError as ex:
+ logger.error(ex)
+ return 1
+ logger.debug("runtime: %s", cls.name)
+ logger.debug("image: %s", args.image)
+ return cls(args, logger).run(args.image, args.cmd)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ 'container',
+ description="See the documentation for more details: "
+ "https://docs.kernel.org/dev-tools/container.html"
+ )
+ parser.add_argument(
+ '-e', '--env-file',
+ help="Path to an environment file to load in the container."
+ )
+ parser.add_argument(
+ '-g', '--gid',
+ help="Group ID to use inside the container."
+ )
+ parser.add_argument(
+ '-i', '--image', required=True,
+ help="Container image name."
+ )
+ parser.add_argument(
+ '-r', '--runtime', choices=Runtimes.get_names(),
+ help="Container runtime name. If not specified, the first one found "
+ "on the system will be used i.e. Docker if present, otherwise Podman."
+ )
+ parser.add_argument(
+ '-s', '--shell', action='store_true',
+ help="Run the container in an interactive shell."
+ )
+ parser.add_argument(
+ '-u', '--uid',
+ help="User ID to use inside the container. If the -g option is not "
+ "specified, the user ID will also be set as the group ID."
+ )
+ parser.add_argument(
+ '-v', '--verbose', action='store_true',
+ help="Enable verbose output."
+ )
+ parser.add_argument(
+ 'cmd', nargs='+',
+ help="Command to run in the container"
+ )
+ sys.exit(main(parser.parse_args(sys.argv[1:])))
--
2.47.3
^ permalink raw reply related
* [PATCH v3 0/2] scripts: introduce containerized builds
From: Guillaume Tucker @ 2025-12-31 16:51 UTC (permalink / raw)
To: Nathan Chancellor, Miguel Ojeda, David Gow, Onur Özkan
Cc: Guillaume Tucker, Arnd Bergmann, linux-kernel, rust-for-linux,
linux-kbuild, automated-testing, workflows, llvm
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
^ permalink raw reply
* Re: [PATCH 1/2] Documentation/process: maintainer-soc: Be more explicit about defconfig
From: Linus Walleij @ 2026-01-01 22:33 UTC (permalink / raw)
To: Krzysztof Kozlowski
Cc: Arnd Bergmann, Krzysztof Kozlowski, Alexandre Belloni,
Linus Walleij, Drew Fustini, Jonathan Corbet, linux-arm-kernel,
soc, workflows, linux-doc, linux-kernel
In-Reply-To: <20251223142726.73417-3-krzysztof.kozlowski@oss.qualcomm.com>
On Tue, Dec 23, 2025 at 3:27 PM Krzysztof Kozlowski
<krzysztof.kozlowski@oss.qualcomm.com> wrote:
> It is already documented but people still send noticeable amount of
> patches ignoring the rule - get_maintainers.pl does not work on
> arm64/configs/defconfig or any other shared ARM defconfig.
>
> Be more explicit, that one must not rely on typical/simple approach
> here for getting To/Cc list.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
Despite the complaints that the patch does not fix the problem
there is nothing wrong with the patch.
Reviewed-by: Linus Walleij <linusw@kernel.org>
Yours,
Linus Walleij
^ permalink raw reply
* Re: [PATCH 2/2] Documentation/process: maintainer-soc: Mark 'make' as commands
From: Linus Walleij @ 2026-01-01 22:33 UTC (permalink / raw)
To: Krzysztof Kozlowski
Cc: Arnd Bergmann, Krzysztof Kozlowski, Alexandre Belloni,
Linus Walleij, Drew Fustini, Jonathan Corbet, linux-arm-kernel,
soc, workflows, linux-doc, linux-kernel
In-Reply-To: <20251223142726.73417-4-krzysztof.kozlowski@oss.qualcomm.com>
On Tue, Dec 23, 2025 at 3:27 PM Krzysztof Kozlowski
<krzysztof.kozlowski@oss.qualcomm.com> wrote:
> Improve readability of the docs by marking 'make dtbs/dtbs_check' as
> shell commands.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
Reviewed-by: Linus Walleij <linusw@kernel.org>
Yours,
Linus Walleij
^ permalink raw reply
* Re: [PATCH v2] docs: process: email-client: add Thunderbird "Toggle Line Wrap" extension
From: Sotir Danailov @ 2026-01-06 10:00 UTC (permalink / raw)
To: Vincent Mailhol
Cc: Jonathan Corbet, workflows, linux-doc, linux-kernel,
Giedrius Statkevičius, Paul McQuade, Jan Kiszka,
Randy Dunlap
In-Reply-To: <20251226-docs_thunderbird-toggle-line-wrap-v2-1-aebb8c60025d@kernel.org>
On Fri, Dec 26, 2025 at 12:47 AM Vincent Mailhol <mailhol@kernel.org> wrote:
>
> [1] man git-format-patch -- §Thunderbird
> Link: https://git-scm.com/docs/git-format-patch#_thunderbird
>
> Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
> ---
> Changes in v2:
>
> - Use the international URL (remove "fr/")
>
> Link to v1: https://lore.kernel.org/r/20251225-docs_thunderbird-toggle-line-wrap-v1-1-24794afa4abf@kernel.org
> ---
> Documentation/process/email-clients.rst | 9 ++++++++-
> 1 file changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
> index 84a2450bb6ec..b5377630a648 100644
> --- a/Documentation/process/email-clients.rst
> +++ b/Documentation/process/email-clients.rst
> @@ -324,7 +324,14 @@ To beat some sense out of the internal editor, do this:
>
> - Set ``mailnews.send_plaintext_flowed`` to ``false``
>
> - - Set ``mailnews.wraplength`` from ``72`` to ``0``
> + - Set ``mailnews.wraplength`` from ``72`` to ``0`` **or** install the
> + "Toggle Line Wrap" extension
> +
> + https://github.com/jan-kiszka/togglelinewrap
> +
> + https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap
> +
> + to control this registry on the fly.
>
> - Don't write HTML messages! Go to the main window
> :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`!
>
> ---
> base-commit: 9448598b22c50c8a5bb77a9103e2d49f134c9578
> change-id: 20251225-docs_thunderbird-toggle-line-wrap-dbe39bcb650b
It's a practical alternative, I see no issue.
Acked-by: Sotir Danailov <sndanailov@gmail.com> # As past commit author
^ permalink raw reply
* Re: [PATCH v2] docs: process: email-client: add Thunderbird "Toggle Line Wrap" extension
From: Gal Pressman @ 2026-01-06 16:42 UTC (permalink / raw)
To: Vincent Mailhol, Jonathan Corbet
Cc: workflows, linux-doc, linux-kernel, Sotir Danailov,
Giedrius Statkevičius, Paul McQuade, Jan Kiszka,
Randy Dunlap
In-Reply-To: <20251226-docs_thunderbird-toggle-line-wrap-v2-1-aebb8c60025d@kernel.org>
On 26/12/2025 1:46, Vincent Mailhol wrote:
> While reading the git-format-patch manpages [1], I discovered the existence
> of the "Toggle Line Wrap" extension for Thunderbird which I found rather
> convenient.
>
> Looking at the history, the ancestor of this extension was added to the
> documentation in commit e0e34e977a7c ("Documentation/email-clients.txt:
> update Thunderbird docs with wordwrap plugin") but then removed in commit
> f9a0974d3f70 ("Documentation: update thunderbird email client settings").
>
> Extend the paragraph on Thunderbird's mailnews.wraplength register to
> mention the existence of the "Toggle Line Wrap" extension. The goal is not
> to create a war on what is the best option so make it clear that this is
> just an alternative.
>
> [1] man git-format-patch -- §Thunderbird
> Link: https://git-scm.com/docs/git-format-patch#_thunderbird
>
> Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
I also use this extension and find it useful, good to have it documented.
Reviewed-by: Gal Pressman <gal@nvidia.com>
Btw, there are some tricks for when you want to wrap parts of the mail,
and leave other parts unwrapped. Useful when drafting a reply that
contains code snippets.
I don't remember the exact steps, but if you know it then it's good to
have it in here as well :).
^ permalink raw reply
* Re: [PATCH v2] docs: process: email-client: add Thunderbird "Toggle Line Wrap" extension
From: Jan Kiszka @ 2026-01-06 17:04 UTC (permalink / raw)
To: Gal Pressman, Vincent Mailhol, Jonathan Corbet
Cc: workflows, linux-doc, linux-kernel, Sotir Danailov,
Giedrius Statkevičius, Paul McQuade, Randy Dunlap
In-Reply-To: <ce4af5ab-5dcf-4b67-b1af-f2288797e342@nvidia.com>
On 06.01.26 17:42, Gal Pressman wrote:
> On 26/12/2025 1:46, Vincent Mailhol wrote:
>> While reading the git-format-patch manpages [1], I discovered the existence
>> of the "Toggle Line Wrap" extension for Thunderbird which I found rather
>> convenient.
>>
>> Looking at the history, the ancestor of this extension was added to the
>> documentation in commit e0e34e977a7c ("Documentation/email-clients.txt:
>> update Thunderbird docs with wordwrap plugin") but then removed in commit
>> f9a0974d3f70 ("Documentation: update thunderbird email client settings").
>>
>> Extend the paragraph on Thunderbird's mailnews.wraplength register to
>> mention the existence of the "Toggle Line Wrap" extension. The goal is not
>> to create a war on what is the best option so make it clear that this is
>> just an alternative.
>>
>> [1] man git-format-patch -- §Thunderbird
>> Link: https://git-scm.com/docs/git-format-patch#_thunderbird
>>
>> Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
>
> I also use this extension and find it useful, good to have it documented.
> Reviewed-by: Gal Pressman <gal@nvidia.com>
>
> Btw, there are some tricks for when you want to wrap parts of the mail,
> and leave other parts unwrapped. Useful when drafting a reply that
> contains code snippets.
>
> I don't remember the exact steps, but if you know it then it's good to
> have it in here as well :).
This got broken quite a while ago: You could enable line wrapping, mark
the paragraph you wanted to have wrapped, select "rewrap" from the edit
menu, and then disable wrapping again. The used to leave the marked
paragraph wrapped-around behind, but not anymore. If there is a
different trick by now, I would be all ears as I used that very often in
the past.
BTW, if you want TB to have better wrapping support natively, please
jump on https://bugzilla.mozilla.org/show_bug.cgi?id=1587153. We either
need to convince them of that or at least finally get an add-on API so
that I do not need to permanently bump the supported TB versions (see
https://github.com/jan-kiszka/togglelinewrap/commits/master/). With the
API Experiment that is still needed for toggling, I'm not allowed to
declare the add-on as compatible with future TB versions.
Jan
^ permalink raw reply
* [PATCH RESEND 0/3] scripts: coccicheck: document debug log handling
From: Benjamin Philip @ 2026-01-06 19:08 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
Currently coccicheck prints debug logs to stdout unless a debug file has been
set. This makes it hard to read coccinelle's suggested changes, especially for
someone new to coccicheck.
This patchset documents this behaviour in both the coccicheck script as well as
in the dev-tools documentation. Additionally, it simplifies some of the logic
for handling debug files.
Benjamin Philip (3):
scripts: coccicheck: simplify debug file handling
scripts: coccicheck: warn on unset debug file
Documentation: Coccinelle: document debug log handling
Documentation/dev-tools/coccinelle.rst | 21 ++++++++++++++++-----
scripts/coccicheck | 21 +++++++++++++--------
2 files changed, 29 insertions(+), 13 deletions(-)
--
2.52.0
^ permalink raw reply
* [PATCH RESEND 1/3] scripts: coccicheck: simplify debug file handling
From: Benjamin Philip @ 2026-01-06 19:08 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <20260106190836.36630-1-benjamin.philip495@gmail.com>
This commit separates handling unset files and pre-existing files. It
also eliminates a duplicated check for unset files in run_cmd_parmap().
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
scripts/coccicheck | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/scripts/coccicheck b/scripts/coccicheck
index 89d591af5f3e..2efb74afef2b 100755
--- a/scripts/coccicheck
+++ b/scripts/coccicheck
@@ -138,7 +138,7 @@ run_cmd_parmap() {
if [ $VERBOSE -ne 0 ] ; then
echo "Running ($NPROC in parallel): $@"
fi
- if [ "$DEBUG_FILE" != "/dev/null" -a "$DEBUG_FILE" != "" ]; then
+ if [ "$DEBUG_FILE" != "/dev/null" ]; then
echo $@>>$DEBUG_FILE
$@ 2>>$DEBUG_FILE
else
@@ -259,13 +259,13 @@ coccinelle () {
}
-if [ "$DEBUG_FILE" != "/dev/null" -a "$DEBUG_FILE" != "" ]; then
- if [ -f $DEBUG_FILE ]; then
- echo "Debug file $DEBUG_FILE exists, bailing"
- exit
- fi
-else
- DEBUG_FILE="/dev/null"
+if [ "$DEBUG_FILE" = "" ]; then
+ DEBUG_FILE="/dev/null"
+fi
+
+if [ -f $DEBUG_FILE ]; then
+ echo "Debug file $DEBUG_FILE exists, bailing"
+ exit
fi
if [ "$COCCI" = "" ] ; then
--
2.52.0
^ permalink raw reply related
* [PATCH RESEND 2/3] scripts: coccicheck: warn on unset debug file
From: Benjamin Philip @ 2026-01-06 19:08 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <20260106190836.36630-1-benjamin.philip495@gmail.com>
coccicheck prints debug logs to stdout unless a debug file has been set.
This makes it hard to read coccinelle's suggested changes, especially
for someone new to coccicheck.
From this commit, we warn about this behaviour from within the script on
an unset debug file. Explicitly setting the debug file to /dev/null
suppresses the warning while keeping the default.
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
scripts/coccicheck | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/scripts/coccicheck b/scripts/coccicheck
index 2efb74afef2b..8dd766009de1 100755
--- a/scripts/coccicheck
+++ b/scripts/coccicheck
@@ -260,6 +260,11 @@ coccinelle () {
}
if [ "$DEBUG_FILE" = "" ]; then
+ echo 'You have not explicitly specified the debug file to use.'
+ echo 'Using default "/dev/null" as debug file.'
+ echo 'Debug logs will be printed to stdout.'
+ echo 'You can specify the debug file with "make coccicheck DEBUG_FILE=<debug_file>"'
+ echo ''
DEBUG_FILE="/dev/null"
fi
--
2.52.0
^ permalink raw reply related
* [PATCH RESEND 3/3] Documentation: Coccinelle: document debug log handling
From: Benjamin Philip @ 2026-01-06 19:08 UTC (permalink / raw)
To: Julia Lawall, Nicolas Palix, Jonathan Corbet
Cc: cocci, workflows, linux-doc, linux-kernel, Benjamin Philip
In-Reply-To: <20260106190836.36630-1-benjamin.philip495@gmail.com>
The current debug documentation does not mention that logs are printed
to stdout unless DEBUG_FILE is set. It also doesn't mention that
Coccinelle cannot overwrite debug files.
Document this behaviour in the examples and reference it in the
debugging section.
Signed-off-by: Benjamin Philip <benjamin.philip495@gmail.com>
---
Documentation/dev-tools/coccinelle.rst | 21 ++++++++++++++++-----
1 file changed, 16 insertions(+), 5 deletions(-)
diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
index 6e70a1e9a3c0..c714780d458a 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -127,6 +127,18 @@ To enable verbose messages set the V= variable, for example::
make coccicheck MODE=report V=1
+By default, coccicheck will print debug logs to stdout and redirect stderr to
+/dev/null. This can make coccicheck output difficult to read and understand.
+Debug and error messages can instead be written to a debug file instead by
+setting the ``DEBUG_FILE`` variable::
+
+ make coccicheck MODE=report DEBUG_FILE="cocci.log"
+
+Coccinelle cannot overwrite a debug file. Instead of repeatedly deleting a log
+file, you could include the datetime in the debug file name::
+
+ make coccicheck MODE=report DEBUG_FILE="cocci-$(date -Iseconds).log"
+
Coccinelle parallelization
--------------------------
@@ -208,11 +220,10 @@ include options matching the options used when we compile the kernel.
You can learn what these options are by using V=1; you could then
manually run Coccinelle with debug options added.
-Alternatively you can debug running Coccinelle against SmPL patches
-by asking for stderr to be redirected to stderr. By default stderr
-is redirected to /dev/null; if you'd like to capture stderr you
-can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
-instance::
+An easier approach to debug running Coccinelle against SmPL patches is to ask
+coccicheck to redirect stderr to a debug file. As mentioned in the examples, by
+default stderr is redirected to /dev/null; if you'd like to capture stderr you
+can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For instance::
rm -f cocci.err
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
--
2.52.0
^ permalink raw reply related
* [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2026-01-06 20:51 UTC (permalink / raw)
To: linux-kernel
Cc: Dave Hansen, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, Luis Chamberlain, SeongJae Park, Dan Williams,
Steven Rostedt, NeilBrown, Lorenzo Stoakes, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In the last few years, the capabilities of coding tools have exploded.
As those capabilities have expanded, contributors and maintainers have
more and more questions about how and when to apply those
capabilities.
Add new Documentation to guide contributors on how to best use kernel
development tools, new and old.
Note, though, there are fundamentally no new or unique rules in this
new document. It clarifies expectations that the kernel community has
had for many years. For example, researchers are already asked to
disclose the tools they use to find issues by
Documentation/process/researcher-guidelines.rst. This new document
just reiterates existing best practices for development tooling.
In short: Please show your work and make sure your contribution is
easy to review.
Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
Reviewed-by: Shuah Khan <shuah@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
Reviewed-by: Luis Chamberlain <mcgrof@kernel.org>
Reviewed-by: SeongJae Park <sj@kernel.org>
Reviewed-by: Dan Williams <dan.j.williams@intel.com>
Reviewed-by: Steven Rostedt <rostedt@goodmis.org>
Cc: NeilBrown <neilb@ownmail.net>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: Sasha Levin <sashal@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: workflows@vger.kernel.org
Cc: ksummit@lists.linux.dev
--
There has been a ton of feedback since v2. Thanks everyone! I've
tried to respect all of the feedback, but some of it has been
contradictory and I haven't been able to incorporate everything.
Please speak up if I missed something important here.
Changes from v2:
* Mention testing (Shuah)
* Remove "very", rename LLM => coding assistant (Dan)
* More formatting sprucing up and minor typos (Miguel)
* Make changelog and text less flashy (Christian)
* Tone down critical=>helpful (Neil)
* Wording/formatting tweaks (Randy)
Changes from v1:
* Rename to generated-content.rst and add to documentation index.
(Jon)
* Rework subject to align with the new filename
* Replace commercial names with generic ones. (Jon)
* Be consistent about punctuation at the end of bullets for whole
sentences. (Miguel)
* Formatting sprucing up and minor typos (Miguel)
This document was a collaborative effort from all the members of
the TAB. I just reformatted it into .rst and wrote the changelog.
---
Documentation/process/generated-content.rst | 97 +++++++++++++++++++++
Documentation/process/index.rst | 1 +
2 files changed, 98 insertions(+)
create mode 100644 Documentation/process/generated-content.rst
diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst
new file mode 100644
index 000000000000..917d6e93c66d
--- /dev/null
+++ b/Documentation/process/generated-content.rst
@@ -0,0 +1,97 @@
+============================================
+Kernel Guidelines for Tool-Generated Content
+============================================
+
+Purpose
+=======
+
+Kernel contributors have been using tooling to generate contributions
+for a long time. These tools can increase the volume of contributions.
+At the same time, reviewer and maintainer bandwidth is a scarce
+resource. Understanding which portions of a contribution come from
+humans versus tools is helpful to maintain those resources and keep
+kernel development healthy.
+
+The goal here is to clarify community expectations around tools. This
+lets everyone become more productive while also maintaining high
+degrees of trust between submitters and reviewers.
+
+Out of Scope
+============
+
+These guidelines do not apply to tools that make trivial tweaks to
+preexisting content. Nor do they pertain to AI tooling that helps with
+menial tasks. Some examples:
+
+ - Spelling and grammar fix ups, like rephrasing to imperative voice
+ - Typing aids like identifier completion, common boilerplate or
+ trivial pattern completion
+ - Purely mechanical transformations like variable renaming
+ - Reformatting, like running Lindent, ``clang-format`` or
+ ``rust-fmt``
+
+Even if your tool use is out of scope, you should still always consider
+if it would help reviewing your contribution if the reviewer knows
+about the tool that you used.
+
+In Scope
+========
+
+These guidelines apply when a meaningful amount of content in a kernel
+contribution was not written by a person in the Signed-off-by chain,
+but was instead created by a tool.
+
+Detection of a problem and testing the fix for it is also part of the
+development process; if a tool was used to find a problem addressed by
+a change, that should be noted in the changelog. This not only gives
+credit where it is due, it also helps fellow developers find out about
+these tools.
+
+Some examples:
+ - Any tool-suggested fix such as ``checkpatch.pl --fix``
+ - Coccinelle scripts
+ - A chatbot generated a new function in your patch to sort list entries.
+ - A .c file in the patch was originally generated by a coding
+ assistant but cleaned up by hand.
+ - The changelog was generated by handing the patch to a generative AI
+ tool and asking it to write the changelog.
+ - The changelog was translated from another language.
+
+If in doubt, choose transparency and assume these guidelines apply to
+your contribution.
+
+Guidelines
+==========
+
+First, read the Developer's Certificate of Origin:
+Documentation/process/submitting-patches.rst. Its rules are simple
+and have been in place for a long time. They have covered many
+tool-generated contributions. Ensure that you understand your entire
+submission and are prepared to respond to review comments.
+
+Second, when making a contribution, be transparent about the origin of
+content in cover letters and changelogs. You can be more transparent
+by adding information like this:
+
+ - What tools were used?
+ - The input to the tools you used, like the Coccinelle source script.
+ - If code was largely generated from a single or short set of
+ prompts, include those prompts. For longer sessions, include a
+ summary of the prompts and the nature of resulting assistance.
+ - Which portions of the content were affected by that tool?
+ - How is the submission tested and what tools were used to test the
+ fix?
+
+As with all contributions, individual maintainers have discretion to
+choose how they handle the contribution. For example, they might:
+
+ - Treat it just like any other contribution.
+ - Reject it outright.
+ - Treat the contribution specially like reviewing with extra scrutiny,
+ or at a lower priority than human-generated content.
+ - Suggest a better prompt instead of suggesting specific code changes.
+ - Ask for some other special steps, like asking the contributor to
+ elaborate on how the tool or model was trained.
+ - Ask the submitter to explain in more detail about the contribution
+ so that the maintainer can feel comfortable that the submitter fully
+ understands how the code works.
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index aa12f2660194..e1a8a31389f5 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -68,6 +68,7 @@ beyond).
stable-kernel-rules
management-style
researcher-guidelines
+ generated-content
Dealing with bugs
-----------------
--
2.34.1
^ permalink raw reply related
* Re: [PATCH v2] docs: process: email-client: add Thunderbird "Toggle Line Wrap" extension
From: Jonathan Corbet @ 2026-01-06 21:38 UTC (permalink / raw)
To: Vincent Mailhol
Cc: workflows, linux-doc, linux-kernel, Sotir Danailov,
Giedrius Statkevičius, Paul McQuade, Jan Kiszka,
Randy Dunlap, Vincent Mailhol
In-Reply-To: <20251226-docs_thunderbird-toggle-line-wrap-v2-1-aebb8c60025d@kernel.org>
Vincent Mailhol <mailhol@kernel.org> writes:
> While reading the git-format-patch manpages [1], I discovered the existence
> of the "Toggle Line Wrap" extension for Thunderbird which I found rather
> convenient.
>
> Looking at the history, the ancestor of this extension was added to the
> documentation in commit e0e34e977a7c ("Documentation/email-clients.txt:
> update Thunderbird docs with wordwrap plugin") but then removed in commit
> f9a0974d3f70 ("Documentation: update thunderbird email client settings").
>
> Extend the paragraph on Thunderbird's mailnews.wraplength register to
> mention the existence of the "Toggle Line Wrap" extension. The goal is not
> to create a war on what is the best option so make it clear that this is
> just an alternative.
>
> [1] man git-format-patch -- §Thunderbird
> Link: https://git-scm.com/docs/git-format-patch#_thunderbird
>
> Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
> ---
> Changes in v2:
>
> - Use the international URL (remove "fr/")
>
> Link to v1: https://lore.kernel.org/r/20251225-docs_thunderbird-toggle-line-wrap-v1-1-24794afa4abf@kernel.org
> ---
> Documentation/process/email-clients.rst | 9 ++++++++-
> 1 file changed, 8 insertions(+), 1 deletion(-)
Applied, thanks.
jon
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox