linux-kernel - Re: [PATCH] kbuild: Do not run kernel-doc when building external modules

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <aYMUc5FVbROqtY6s@foz.lan>
Date: Wed, 4 Feb 2026 11:22:26 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Nathan Chancellor <nathan@...nel.org>
Cc: Masahiro Yamada <masahiroy@...nel.org>, 
	Nicolas Schier <nsc@...nel.org>, Jonathan Corbet <corbet@....net>, linux-kbuild@...r.kernel.org, 
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, stable@...r.kernel.org, 
	Rong Zhang <i@...g.moe>, Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Subject: Re: [PATCH] kbuild: Do not run kernel-doc when building external
 modules

On Wed, Feb 04, 2026 at 12:39:03AM -0700, Nathan Chancellor wrote:
> Hi Masahiro,
> 
> Good to see you around.
> 
> On Wed, Feb 04, 2026 at 04:02:10PM +0900, Masahiro Yamada wrote:
> > On Sun, Feb 1, 2026 at 12:15 AM Nicolas Schier <nsc@...nel.org> wrote:
> > >
> > > On Fri, 30 Jan 2026 14:37:47 -0700, Nathan Chancellor wrote:
> > > > After commit 778b8ebe5192 ("docs: Move the python libraries to
> > > > tools/lib/python"), building an external module with any value of W=
> > > > against the output of install-extmod-build fails with:
> > > >
> > > >   $ make -C /usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build M=$PWD W=1
> > > >   make: Entering directory '/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build'
> > > >   make[1]: Entering directory '...'
> > > >     CC [M] ...
> > > >   Traceback (most recent call last):
> > > >     File "/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build/scripts/kernel-doc.py", line 339, in <module>
> > > >       main()
> > > >       ~~~~^^
> > > >     File "/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build/scripts/kernel-doc.py", line 295, in main
> > > >       from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
> > > >       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > >   ModuleNotFoundError: No module named 'kdoc'
> > > >
> > > > [...]
> > >
> > > Applied to kbuild/linux.git (kbuild-fixes-unstable), thanks!
> > 
> > 
> > I believe this is a wrong direction to go.
> > 
> > Since kernel-doc is a part of Kbuild,
> > all dependent libraries should exist under scripts/.
> 
> Is this around the recent moves such as 778b8ebe5192? I guess Kbuild was
> never consulted on that change and I missed eba6ffd126cd, despite being
> CC'd, so that is on me.
> 
> I did wonder if it was worth it to package these files in a previous
> change but Mauro seemed somewhat opposed to it (but maybe I
> misinterpreted something):
> 
>   https://lore.kernel.org/20260130063056.72fbe458@foz.lan/

Not really opposed. The point is that, on a normal run, kernel-doc
is executed with -none, to check if are there a trouble with the
kernel-doc markup (there's a kconfig option for such purpose).
Also, it is not the only tool that it is executed on such case,
on a normal build. See docs/Makefile (*):

    ifneq ($(MAKECMDGOALS),cleandocs)
    # Check for broken documentation file references
    ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
    $(shell $(srctree)/tools/docs/documentation-file-ref-check --warn)
    endif

    # Check for broken ABI files
    ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
    $(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate)
    endif
    endif

(*) The only difference is that kernel-doc call is currently sitting
    at scripts/Makefile.build. Perhaps it could make sense to move
    it to docs/Makefile.

-

I think it is not worth running any such documentation-validation-tools
when doing OOT driver builds, as their goal is to ensure a good
quality of documentation within the Kernel, and OOT drivers usually
have a lot more problems than just documentation, but it is up to you.
I'm ok with either solution.
 
> Perhaps tools/docs could be moved to scripts/docs and tools/lib/python
> could be moved to just lib/python to have everything live logically
> outside of tools/ and make it easier to package?

The idea of moving it out of scripts is because scripts became
a no-man's land, with lots of mixed stuff. From my side, I don't
care much about its location, provided that the path is very short.

-

That's said, if you want htmldocs/mandocs/... targets to work
with OOT builds, you don't really need kernel-doc executable, 
as Sphinx uses kdoc libraries directly. Yet, you need a lot
more:

1) tools executed by docs/Makefile:

    tools/docs/sphinx-build-wrapper
    tools/docs/sphinx-pre-install

2) Sphinx config and extensions:

    Documentation/conf.py
    Documentation/sphinx/
    Documentation/sphinx-includes/
    Documentation/sphinx-static/

3) Libraries used by sphinx-build-wrapper and sphinx extensions:

    tools/lib/python/jobserver.py
    tools/lib/python/abi/
    tools/lib/python/feat/
    tools/lib/python/kdoc/

You can also install optional command line tools, which
are helpful to run the code inside abi/feat/kdoc outside
Sphinx build:

    tools/docs/kernel-doc
    tools/docs/get_abi.py
    tools/docs/get_feat.py
    tools/docs/parse-headers.py
  
Regards,
Mauro