Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

[Randy Dunlap]

Hi,

On 11/3/25 10:56 AM, Nathan Chancellor wrote:
> On Mon, Nov 03, 2025 at 01:14:19PM +0100, Jean Delvare wrote:
>> 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 <jdelvare@suse.de>
> 
> 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).

>> ---
>>  Makefile |    2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> --- linux-6.17.orig/Makefile
>> +++ linux-6.17/Makefile
>> @@ -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 \
>>
>>
>> -- 
>> Jean Delvare
>> SUSE L3 Support
> 

-- 
~Randy

Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

[Mauro Carvalho Chehab]

Em Mon, 3 Nov 2025 11:00:51 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi,
> 
> On 11/3/25 10:56 AM, Nathan Chancellor wrote:
> > On Mon, Nov 03, 2025 at 01:14:19PM +0100, Jean Delvare wrote:  
> >> 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 <jdelvare@suse.de>  
> > 
> > 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

> 
> >> ---
> >>  Makefile |    2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >> --- linux-6.17.orig/Makefile
> >> +++ linux-6.17/Makefile
> >> @@ -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.

> >>  export KERNELDOC
> >>  
> >>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> >>
> >>
> >> -- 
> >> Jean Delvare
> >> SUSE L3 Support  
> >   
> 

Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

[Jean Delvare]

Hi Mauro,

On Fri, 7 Nov 2025 07:13:42 -0300, Mauro Carvalho Chehab wrote:
> 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,
-- 
Jean Delvare
SUSE L3 Support

Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

[Mauro Carvalho Chehab]

Em Fri, 7 Nov 2025 19:26:24 +0100
Jean Delvare <jdelvare@suse.de> escreveu:

> Hi Mauro,
> 
> On Fri, 7 Nov 2025 07:13:42 -0300, Mauro Carvalho Chehab wrote:
> > 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.

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.

> 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