Message-ID: <20260130063056.72fbe458@foz.lan>
Date: Fri, 30 Jan 2026 06:30:56 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Nathan Chancellor <nathan@...nel.org>
Cc: Rong Zhang <i@...g.moe>, Jonathan Corbet <corbet@....net>, Mauro
 Carvalho Chehab <mchehab@...nel.org>, Nicolas Schier <nsc@...nel.org>,
 Masahiro Yamada <masahiroy@...nel.org>, linux-kbuild@...r.kernel.org,
 linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH] kbuild: install-extmod-build: Add missing python
 libraries

Hi Nathan,

On Thu, 29 Jan 2026 18:11:06 -0700
Nathan Chancellor <nathan@...nel.org> wrote:

> + Jon, Mauro, and linux-doc
> 
> FWIW, this ended up in my spam folder but I saw it on linux-kbuild.
> 
> On Fri, Jan 30, 2026 at 01:49:55AM +0800, Rong Zhang wrote:
> > scripts/lib has been moved to tools/lib/python recently. Since then, I
> > got a regression while building out-of-tree modules with W=<anything>
> > (1/2/3/c/e):  
> 
> Hmmm, the W=<anything> bit seems wrong (or at the very least, c/e)... we
> should probably change that to just being enabled at W=1 (but that is
> tangential to this patch).
> 
> >   $ make -C /lib/modules/6.19.0-rc6/build/ M="$(pwd)" modules V=1 W=1
> >   [...]
> >   make -f /usr/src/linux-headers-6.19.0-rc6/scripts/Makefile.build obj=. need-builtin=1 need-modorder=1
> >   # CC [M]  mod.o
> >   [...]
> >   # cmd_checkdoc mod.o
> >   PYTHONDONTWRITEBYTECODE=1 python3 /usr/src/linux-headers-6.19.0-rc6/scripts/kernel-doc.py -none mod.c


This sounds really weird, as it is trying to run scripts/kernel-doc.py
instead of tools/docs/kernel-doc. Does the out-of-tree Makefile
override KERNELDOC variable? The current version contains:
	
	KERNELDOC       = $(srctree)/tools/docs/kernel-doc

But somehow it is using the old version before the renames:

	KERNELDOC       = $(srctree)/scripts/kernel-doc.py

As you can see, kernel-doc.py was renamed to just kernel-doc at the
patches that moved it. Inside kernel-doc, there is this code:

	LIB_DIR = "lib/kdoc"
	SRC_DIR = os.path.dirname(os.path.realpath(__file__))

	sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))

which auto-detect its location and ensures that the library location
will be relative to it.

With that, if you call it outside the kernel tree, like here (on this
example, kernel root tree is at linux-next):

	$ linux-next/tools/docs/kernel-doc linux-next/drivers/acpi/ -none
	Warning: linux-next/drivers/acpi/fan.h:83 function parameter 'speed' not described in 'acpi_fan_speed_valid'
	Warning: linux-next/drivers/acpi/fan.h:83 function parameter 'speed' not described in 'acpi_fan_speed_valid'

it works just fine.

the realpath() function even warrants that a symlink will equally 
work(*):

	$ linux-next/scripts/kernel-doc linux-next/drivers/acpi/ -none
	Warning: linux-next/drivers/acpi/fan.h:83 function parameter 'speed' not described in 'acpi_fan_speed_valid'
	Warning: linux-next/drivers/acpi/fan.h:83 function parameter 'speed' not described in 'acpi_fan_speed_valid'

(*) one of the patches of the rename patch series added a soft link:

	$ ls -lctra linux-next/scripts/kernel-doc
	lrwxrwxrwx 1 user user 24 Jan 23 08:53 linux-next/scripts/kernel-doc -> ../tools/docs/kernel-doc


Btw, I did a very quick test here, using an old OOT project I have
at github:

	https://github.com/mchehab/xr_serial
	
Changing its Makefile to:

	obj-m := xr_serial.o

	SRCTREE=../linux-next
	KERNELDIR ?= $(SRCTREE)/tools/build
	KERNELDOC = $(SRCTREE)/tools/docs/kernel-doc

	PWD       := $(shell pwd)

	EXTRA_CFLAGS    := -DDEBUG=0

	all:
	        $(MAKE) -C $(KERNELDIR) M=$(PWD)

	docs:
        	$(KERNELDOC) .

	modules_install:
        	$(MAKE) -C $(KERNELDIR) M=$(PWD) modules_install

	install: modules_install

	clean:
        	rm -rf *.o *~ core .depend .*.cmd *.ko *.mod.c .tmp_versions vtty built-in.a  cdc-acm.mod modules.order Module.symvers xr_serial.mod

There, building docs didn't crash:

	$ make docs
	../linux-next/tools/docs/kernel-doc .

(none was produced, as xr_serial doesn't contain any kernel-doc
stuff, but still the tool worked properly).

It sounds to me that Rong may be using a Makefile on his OOT project
that was not updated to pick the right kernel-doc tool.

> >   Traceback (most recent call last):
> >     File "/usr/src/linux-headers-6.19.0-rc6/scripts/kernel-doc.py", line 339, in <module>
> >       main()
> >       ~~~~^^
> >     File "/usr/src/linux-headers-6.19.0-rc6/scripts/kernel-doc.py", line 295, in main
> >       from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
> >       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >   ModuleNotFoundError: No module named 'kdoc'
> >   make[3]: *** [/usr/src/linux-headers-6.19.0-rc6/scripts/Makefile.build:287: mod.o] Error 1
> > 
> > Fix it by installing python libraries from tools/lib/python.
> > 
> > Fixes: 778b8ebe5192 ("docs: Move the python libraries to tools/lib/python")
> > Signed-off-by: Rong Zhang <i@...g.moe>  
> 
> Thanks, this seems to be correct to me.
> 
> Reviewed-by: Nathan Chancellor <nathan@...nel.org>
> 
> Nicolas, do you want to take this via kbuild-fixes? This should probably
> have a 'Cc: stable@...r.kernel.org' on it?
> 
> Hmmm, now that I am looking at -next, Jon's move of scripts/kernel-doc
> to tools/docs/ in commit eba6ffd126cd ("docs: kdoc: move kernel-doc to
> tools/docs") in that tree without adding tools/docs to this list breaks
> this exact same scenario, right?
> 
> > ---
> >  scripts/package/install-extmod-build | 1 +
> >  1 file changed, 1 insertion(+)
> > 
> > diff --git a/scripts/package/install-extmod-build b/scripts/package/install-extmod-build
> > index 2576cf7902dbb..a15de610afed3 100755
> > --- a/scripts/package/install-extmod-build
> > +++ b/scripts/package/install-extmod-build
> > @@ -20,6 +20,7 @@ mkdir -p "${destdir}"
> >  (
> >  	cd "${srctree}"
> >  	echo Makefile

> > +	echo tools/lib/python # required by scripts

I don't know exactly how the out-of-tree logic works, but at least
in my eyes, this doesn't sound the right fix. 

Regards,
Mauro

Thanks,
Mauro

Powered by blists - more mailing lists