Skip to contentSkip to conversation

Makefile: Let kernel-doc.py use PYTHON3 override

PATCH Superseded Jean Delvare 4 participants 6 messages Nov 3, 2025 – Nov 7, 2025

Subsystems (2)
Documentation Kbuild

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Jean Delvare

author
#0 lore raw

PATCH 1/1 Makefile: Let kernel-doc.py use PYTHON3 override

It is possible to force a specific version of python to be used when building the kernel by passing PYTHON3= on the make command line. However kernel-doc.py is currently called with python3 hard-coded and thus ignores this setting.

Use PYTHON3 to call kernel-doc.py so that the desired version of python is used.

Signed-off-by Jean Delvare <[email protected]>
---
 Makefile |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Makefile +1 -1
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/scripts/kernel-doc.py
+KERNELDOC       = $(PYTHON3) $(srctree)/scripts/kernel-doc.py
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
Signature · 2 lines
Jean Delvare
SUSE L3 Support
maintainer
#1 lore raw
Quoted 9 lines · Jean Delvare

It is possible to force a specific version of python to be used when building the kernel by passing PYTHON3= on the make command line. However kernel-doc.py is currently called with python3 hard-coded and thus ignores this setting.

Use PYTHON3 to call kernel-doc.py so that the desired version of python is used.

Signed-off-by Jean Delvare <[email protected]>

I see one use of KERNELDOC in tools/docs/sphinx-build-wrapper that would appear to break with this change? Does it matter? I am not familiar with the docs build. Otherwise, this seems like the correct thing to do.

Quoted 20 lines
---
 Makefile |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Makefile +1 -1
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/scripts/kernel-doc.py
+KERNELDOC       = $(PYTHON3) $(srctree)/scripts/kernel-doc.py
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
Signature · 3 lines
-- 
Jean Delvare
SUSE L3 Support
reviewer
#2 lore raw

Hi,

Quoted 6 lines · Nathan Chancellor
Quoted 5 lines · Jean Delvare

It is possible to force a specific version of python to be used when building the kernel by passing PYTHON3= on the make command line. However kernel-doc.py is currently called with python3 hard-coded and thus ignores this setting.

Quoted 8 lines
Quoted 4 lines

Use PYTHON3 to call kernel-doc.py so that the desired version of python is used.

Signed-off-by Jean Delvare <[email protected]>

I see one use of KERNELDOC in tools/docs/sphinx-build-wrapper that would appear to break with this change? Does it matter? I am not familiar with the docs build. Otherwise, this seems like the correct thing to do.

I think there has been some discussion of these matters on the linux-doc mailing list (adding it here).

Quoted 21 lines
Quoted 20 lines
---
 Makefile |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Makefile +1 -1
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/scripts/kernel-doc.py
+KERNELDOC       = $(PYTHON3) $(srctree)/scripts/kernel-doc.py
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
Signature · 3 lines
-- 
Jean Delvare
SUSE L3 Support
Signature · 1 line
~Randy
#3 lore raw

Em Mon, 3 Nov 2025 11:00:51 -0800
Randy Dunlap <[email protected]> escreveu:

Quoted 12 lines

Hi,

Quoted 9 lines · Nathan Chancellor
Quoted 8 lines · Jean Delvare

It is possible to force a specific version of python to be used when building the kernel by passing PYTHON3= on the make command line. However kernel-doc.py is currently called with python3 hard-coded and thus ignores this setting.

Use PYTHON3 to call kernel-doc.py so that the desired version of python is used.

Quoted 8 lines
Quoted 5 lines
Quoted 1 line
Signed-off-by Jean Delvare <[email protected]>

I see one use of KERNELDOC in tools/docs/sphinx-build-wrapper that would appear to break with this change? Does it matter? I am not familiar with the docs build. Otherwise, this seems like the correct thing to do.

I think there has been some discussion of these matters on the linux-doc mailing list (adding it here).

Yes. The way the current building system works, after the discussions, is that:

1. Makefile runs sphinx-build-wrapper, which is a python script, using this target:

    htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
        $(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
                $(srctree)/tools/docs/sphinx-pre-install --version-check
        +$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
                $(PYTHON3) $(BUILD_WRAPPER) $@ \
                --sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \
                --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
                --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)

2. sphinx-build-wrapper will run sphinx-build with the same python version it was called;
3. Sphinx kerneldoc.py extension will directly call kernel-doc classes, meaning that it will use the same python version as sphinx-build. There, it will use KERNELDOC var *only* to check if it ends with ".py", as there is (still) a fallback code there to allow running a different script via fork.

On other words, if one wants to run a different python version, it has to do:

make PYTHON3=/usr/bin/python-3.11 htmldocs

This should work for doc builds.

Please notice, however, that kERNEL_DOC env var is also called at some DRM makefiles. Perhaps the issue you're getting is there.

Regards,
Mauro

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
---
 Makefile |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 8 lines
Quoted 8 lines

Makefile HOSTPKG_CONFIG = pkg-config · line 463

Quoted 8 lines
Makefile +1 -1
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/scripts/kernel-doc.py
+KERNELDOC       = $(PYTHON3) $(srctree)/scripts/kernel-doc.py

This is not the right place to add it, as it may break the Sphinx extension.

Quoted 10 lines
Quoted 9 lines
Quoted 8 lines
Makefile +0 -0
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
Signature · 3 lines
-- 
Jean Delvare
SUSE L3 Support
author
#4 lore raw

Hi Mauro,

Quoted 2 lines · Mauro Carvalho Chehab

Please notice, however, that kERNEL_DOC env var is also called at some DRM makefiles. Perhaps the issue you're getting is there.

I'm getting the warnings from a simple "make" call with W=1, and for pretty much all C files, not just drm drivers. For example:

$ nice make CC=/usr/bin/gcc-8 PYTHON3=/usr/bin/python3.12 W=1
(...)
  CC      arch/x86/events/intel/core.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/core.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/bts.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/bts.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/ds.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/ds.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/knc.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/knc.c:0 Python 3.7 or later is required for correct results

So without my patch, PYTHON3= is ignored for part of the build, and these recurrent warnings make it difficult to spot other warnings. Which is the reason why I proposed a fix. Alas, I see that my first candidate fix breaks "make htmldocs" as reported by Nathan. I'll send a different fix which doesn't seem to break anything in my tests.

Thanks,

Signature · 2 lines
Jean Delvare
SUSE L3 Support
#5 lore raw

Em Fri, 7 Nov 2025 19:26:24 +0100
Jean Delvare <[email protected]> escreveu:

Quoted 24 lines

Hi Mauro,

Quoted 2 lines · Mauro Carvalho Chehab

Please notice, however, that kERNEL_DOC env var is also called at some DRM makefiles. Perhaps the issue you're getting is there.

I'm getting the warnings from a simple "make" call with W=1, and for pretty much all C files, not just drm drivers. For example:

$ nice make CC=/usr/bin/gcc-8 PYTHON3=/usr/bin/python3.12 W=1
(...)
  CC      arch/x86/events/intel/core.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/core.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/bts.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/bts.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/ds.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/ds.c:0 Python 3.7 or later is required for correct results
  CC      arch/x86/events/intel/knc.o
Warning: Python 3.7 or later is required for correct results
Warning: arch/x86/events/intel/knc.c:0 Python 3.7 or later is required for correct results
Quoted 2 lines

So without my patch, PYTHON3= is ignored for part of the build, and these recurrent warnings make it difficult to spot other warnings.

I was kind of expecting such issues on SUSE/openSUSE. That's why I proposed a logic which auto-detects if a newer python was present, using it when python version is < 3.7. However, most people didn't like such approach.

Quoted 3 lines

Which is the reason why I proposed a fix. Alas, I see that my first candidate fix breaks "make htmldocs" as reported by Nathan. I'll send a different fix which doesn't seem to break anything in my tests.

The second patch seems to be the correct approach to make PYTHON3 override work for kernel-doc. Sent my R-B to it.

Thanks,
Mauro