[PATCH v2 0/2] Better handle and document Python needs for Kernel build

[PATCH v2 0/2] Better handle and document Python needs for Kernel build

[Mauro Carvalho Chehab]

Hi Jon,

It follows the second version of this small series. It contains
missing patches from the python backward-compatibility series.

I dropped support for 2.7 and did some changes at changes.rst
per Akira's request.

They're not urgent, IMO it should be OK to have them merged for 6.17.

The first patch ensures that kernel-doc won't crash with version
3.2 (tested on 3.4, as 3.2 is like an unicorn: docker containers v1
don't run anymore on Fedora, building is broken since at least
Fedora 32, Anaconda doesn't have it anymore).

With this change, on elder versions, it would emit a warning and
do nothing, as the actual code depends on features at 3.6 (f-strings)
and 3.7 (ordered dict).

The second patch changes process/changes.rst. Currently, it makes
one  think that Python is optional. While not having python may
work on some cases, it breaks on arm/arm64 with defconfigs.
It also breaks with allyesconfig/almodconfig (at least on x86/x86_64),
with clang (on some archs) and apparently on some other
subsystems that I didn't care enough to identify, as for me,
breaking on arm/arm64 with defconfigs, and on x86/x86_64
with allyesconfig/allmodconfig is enough evidence that this
is mandatory nowadays.

So, remove optional from Python and add a quick description
about where it is required, leaving it open to one's imagination
that it could break with other configs we didn't map.

---
v2: drop support for 2.7, updated a comment and updated changes.rst.

Mauro Carvalho Chehab (2):
  docs: kernel-doc: avoid script crash on ancient Python
  docs: changes: better document Python needs

 Documentation/process/changes.rst |  9 +++++++-
 scripts/kernel-doc.py             | 34 ++++++++++++++++++++++---------
 2 files changed, 32 insertions(+), 11 deletions(-)

-- 
2.49.0

[PATCH v2 1/2] docs: kernel-doc: avoid script crash on ancient Python

[Mauro Carvalho Chehab]

While we do need at least 3.6 for kernel-doc to work, and at least
3.7 for it to output functions and structs with parameters at the
right order, let the python binary be compatible with legacy
versions.

The rationale is that the Kernel build nowadays calls kernel-doc
with -none on some places. Better not to bail out when older
versions are found.

With that, potentially this will run with python 2.7 and 3.2+,
according with vermin:

	$ vermin --no-tips -v ./scripts/kernel-doc
	Detecting python files..
	Analyzing using 24 processes..
	2.7, 3.2     /new_devel/v4l/docs/scripts/kernel-doc
	Minimum required versions: 2.7, 3.2

3.2 minimal requirement is due to argparse.

The minimal version I could check was version 3.4
(using anaconda). Anaconda doesn't support 3.2 or 3.3
anymore, and 3.2 doesn't even compile (I tested compiling
Python 3.2 on Fedora 42 and on Fedora 32 - no show).

With 3.4, the script didn't crash and emitted the right warning:

	$ conda create -n py34 python=3.4
	$ conda activate py34
	python --version
        Python 3.4.5
        $ python ./scripts/kernel-doc --none include/media
	Error: Python 3.6 or later is required by kernel-doc
	$ conda deactivate

	$ python --version
	Python 3.13.5
        $ python ./scripts/kernel-doc --none include/media
	(no warnings and script ran properly)

Supporting 2.7 is out of scope, as it is EOL for 5 years, and
changing shebang to point to "python" instead of "python3"
would have a wider impact.

I did some extra checks about the differences from 3.2 and
3.4, and didn't find anything that would cause troubles:

	grep -rE "yield from|asyncio|pathlib|async|await|enum" scripts/kernel-doc

Also, it doesn't use "@" operator. So, I'm confident that it
should run (producing the exit warning) since Python 3.2.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc.py | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index fc3d46ef519f..d9fe2bcbd39c 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -2,8 +2,17 @@
 # SPDX-License-Identifier: GPL-2.0
 # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
 #
-# pylint: disable=C0103,R0915
-#
+# pylint: disable=C0103,R0912,R0914,R0915
+
+# NOTE: While kernel-doc requires at least version 3.6 to run, the
+#       command line should work with Python 3.2+ (tested with 3.4).
+#       The rationale is that it shall fail gracefully during Kernel
+#       compilation with older Kernel versions. Due to that:
+#       - encoding line is needed here;
+#       - no f-strings can be used on this file.
+#       - the libraries that require newer versions can only be included
+#         after Python version is checked.
+
 # Converted from the kernel-doc script originally written in Perl
 # under GPLv2, copyrighted since 1998 by the following authors:
 #
@@ -107,9 +116,6 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
 
 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
-from kdoc_files import KernelFiles                      # pylint: disable=C0413
-from kdoc_output import RestFormat, ManFormat           # pylint: disable=C0413
-
 DESC = """
 Read C language source or header FILEs, extract embedded documentation comments,
 and print formatted documentation to standard output.
@@ -273,14 +279,22 @@ def main():
 
     python_ver = sys.version_info[:2]
     if python_ver < (3,6):
-        logger.warning("Python 3.6 or later is required by kernel-doc")
+        # Depending on Kernel configuration, kernel-doc --none is called at
+        # build time. As we don't want to break compilation due to the
+        # usage of an old Python version, return 0 here.
+        if args.none:
+            logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
+            sys.exit(0)
 
-        # Return 0 here to avoid breaking compilation
-        sys.exit(0)
+        sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
 
     if python_ver < (3,7):
         logger.warning("Python 3.7 or later is required for correct results")
 
+    # Import kernel-doc libraries only after checking Python version
+    from kdoc_files import KernelFiles                  # pylint: disable=C0415
+    from kdoc_output import RestFormat, ManFormat       # pylint: disable=C0415
+
     if args.man:
         out_style = ManFormat(modulename=args.modulename)
     elif args.none:
@@ -308,11 +322,11 @@ def main():
         sys.exit(0)
 
     if args.werror:
-        print(f"{error_count} warnings as errors")
+        print("%s warnings as errors" % error_count)    # pylint: disable=C0209
         sys.exit(error_count)
 
     if args.verbose:
-        print(f"{error_count} errors")
+        print("%s errors" % error_count)                # pylint: disable=C0209
 
     if args.none:
         sys.exit(0)
-- 
2.49.0

[PATCH v2 2/2] docs: changes: better document Python needs

[Mauro Carvalho Chehab]

Python is listed as an optional dependency, but this is not
true, as:

1) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig
   needs it due to DRM_MSM dependencies;

2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o;

3) kernel-doc is called during compilation when some DRM options
   like CONFIG_DRM_I915_WERROR are enabled;

4) allyesconfig/allmodconfig will enable CONFIG_* dependencies
   that needs it;

5) besides DRM, other subsystems seem to have logic calling *.py
   scripts.

So, better document that and change the dependency from optional
to mandatory to reflect the current needs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/process/changes.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index bccfa19b45df..4c9088e429c8 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -61,7 +61,7 @@ Sphinx\ [#f1]_         3.4.3            sphinx-build --version
 GNU tar                1.28             tar --version
 gtags (optional)       6.6.5            gtags --version
 mkimage (optional)     2017.01          mkimage --version
-Python (optional)      3.9.x            python3 --version
+Python                 3.9.x            python3 --version
 GNU AWK (optional)     5.1.0            gawk --version
 ====================== ===============  ========================================
 
@@ -154,6 +154,13 @@ Perl
 You will need perl 5 and the following modules: ``Getopt::Long``,
 ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
 
+Python
+------
+
+Several config options require it: it is required for arm/arm64
+default configs, CONFIG_LTO_CLANG, some DRM optional configs,
+the kernel-doc tool, and docs build (Sphinx), among others.
+
 BC
 --
 
-- 
2.49.0

Re: [PATCH v2 2/2] docs: changes: better document Python needs

[Akira Yokosawa]

On Tue, 29 Jul 2025 18:43:04 +0200, Mauro Carvalho Chehab wrote:
> Python is listed as an optional dependency, but this is not
> true, as:
> 
> 1) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig
>    needs it due to DRM_MSM dependencies;
> 
> 2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o;
> 
> 3) kernel-doc is called during compilation when some DRM options
>    like CONFIG_DRM_I915_WERROR are enabled;
> 
> 4) allyesconfig/allmodconfig will enable CONFIG_* dependencies
>    that needs it;
> 
> 5) besides DRM, other subsystems seem to have logic calling *.py
>    scripts.
> 

OK. This sounds convincing enough.

> So, better document that and change the dependency from optional
> to mandatory to reflect the current needs.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/process/changes.rst | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index bccfa19b45df..4c9088e429c8 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -61,7 +61,7 @@ Sphinx\ [#f1]_         3.4.3            sphinx-build --version
>  GNU tar                1.28             tar --version
>  gtags (optional)       6.6.5            gtags --version
>  mkimage (optional)     2017.01          mkimage --version
> -Python (optional)      3.9.x            python3 --version
> +Python                 3.9.x            python3 --version
>  GNU AWK (optional)     5.1.0            gawk --version
>  ====================== ===============  ========================================
>  
> @@ -154,6 +154,13 @@ Perl
>  You will need perl 5 and the following modules: ``Getopt::Long``,
>  ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
>  
> +Python
> +------
> +
> +Several config options require it: it is required for arm/arm64
> +default configs, CONFIG_LTO_CLANG, some DRM optional configs,
> +the kernel-doc tool, and docs build (Sphinx), among others.
> +

Looks much better.  Feel free to add:

Acked-by: Akira Yokosawa <akiyks@gmail.com>

Thanks.

Re: [PATCH v2 2/2] docs: changes: better document Python needs

[Rob Herring]

On Tue, Jul 29, 2025 at 11:44 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Python is listed as an optional dependency, but this is not
> true, as:
>
> 1) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig
>    needs it due to DRM_MSM dependencies;
>
> 2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o;
>
> 3) kernel-doc is called during compilation when some DRM options
>    like CONFIG_DRM_I915_WERROR are enabled;
>
> 4) allyesconfig/allmodconfig will enable CONFIG_* dependencies
>    that needs it;
>
> 5) besides DRM, other subsystems seem to have logic calling *.py
>    scripts.
>
> So, better document that and change the dependency from optional
> to mandatory to reflect the current needs.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/process/changes.rst | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)

DT schema checks requires it too.

Acked-by: Rob Herring (Arm) <robh@kernel.org>

Re: [PATCH v2 0/2] Better handle and document Python needs for Kernel build

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Hi Jon,
>
> It follows the second version of this small series. It contains
> missing patches from the python backward-compatibility series.

Applied, thanks.

jon