tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: kernel-doc: avoid script crash on ancient Python

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>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/87d55e76b0b1391cb7a83e3e965dbddb83fa9786.1753806485.git.mchehab+huawei@kernel.org

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet fc973dcd 7b41f6f9

+24 -10
+24 -10
scripts/kernel-doc.py
··· 2 2 # SPDX-License-Identifier: GPL-2.0 3 3 # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>. 4 4 # 5 - # pylint: disable=C0103,R0915 6 - # 5 + # pylint: disable=C0103,R0912,R0914,R0915 6 + 7 + # NOTE: While kernel-doc requires at least version 3.6 to run, the 8 + # command line should work with Python 3.2+ (tested with 3.4). 9 + # The rationale is that it shall fail gracefully during Kernel 10 + # compilation with older Kernel versions. Due to that: 11 + # - encoding line is needed here; 12 + # - no f-strings can be used on this file. 13 + # - the libraries that require newer versions can only be included 14 + # after Python version is checked. 15 + 7 16 # Converted from the kernel-doc script originally written in Perl 8 17 # under GPLv2, copyrighted since 1998 by the following authors: 9 18 # ··· 115 106 SRC_DIR = os.path.dirname(os.path.realpath(__file__)) 116 107 117 108 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) 118 - 119 - from kdoc_files import KernelFiles # pylint: disable=C0413 120 - from kdoc_output import RestFormat, ManFormat # pylint: disable=C0413 121 109 122 110 DESC = """ 123 111 Read C language source or header FILEs, extract embedded documentation comments, ··· 279 273 280 274 python_ver = sys.version_info[:2] 281 275 if python_ver < (3,6): 282 - logger.warning("Python 3.6 or later is required by kernel-doc") 276 + # Depending on Kernel configuration, kernel-doc --none is called at 277 + # build time. As we don't want to break compilation due to the 278 + # usage of an old Python version, return 0 here. 279 + if args.none: 280 + logger.error("Python 3.6 or later is required by kernel-doc. skipping checks") 281 + sys.exit(0) 283 282 284 - # Return 0 here to avoid breaking compilation 285 - sys.exit(0) 283 + sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") 286 284 287 285 if python_ver < (3,7): 288 286 logger.warning("Python 3.7 or later is required for correct results") 287 + 288 + # Import kernel-doc libraries only after checking Python version 289 + from kdoc_files import KernelFiles # pylint: disable=C0415 290 + from kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 289 291 290 292 if args.man: 291 293 out_style = ManFormat(modulename=args.modulename) ··· 322 308 sys.exit(0) 323 309 324 310 if args.werror: 325 - print(f"{error_count} warnings as errors") 311 + print("%s warnings as errors" % error_count) # pylint: disable=C0209 326 312 sys.exit(error_count) 327 313 328 314 if args.verbose: 329 - print(f"{error_count} errors") 315 + print("%s errors" % error_count) # pylint: disable=C0209 330 316 331 317 if args.none: 332 318 sys.exit(0)