Em Thu, 13 Feb 2025 09:35:58 -0700
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:
>
> > Kernel-doc has an obscure logic that uses an external file
> > to map files via a .tmp_filelist.txt file stored at the current
> > directory. The rationale for such code predates git time,
> > as it was added on Kernel v2.4.5.5, with the following description:
> >
> > # 26/05/2001 - Support for separate source and object trees.
> > # Return error code.
> > # Keith Owens <kaos@xxxxxxxxxx>
> >
> > from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historic
> > tree:
> > https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/
> >
> > Support for separate source and object trees is now done on a different
> > way via make O=<object>.
> >
> > There's no logic to create such file, so it sounds to me that this is
> > just dead code.
> >
> > So, drop it.
> >
> > Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > ---
> > scripts/kernel-doc | 19 +------------------
> > 1 file changed, 1 insertion(+), 18 deletions(-)
>
> Weird ... I went and looked, and can't find anything that ever created
> that tmp_filelist.txt file; I wonder if this code ever did anything?
I wonder the same ;-) Anyway, better to remove this now, as, if people
complain, it would be easier to revert than after switching to the
Python version.
> Don't put that functionality into the Python version :)
Yeah, I started implementing it, but it sounded a waste of time, so
I dropped it from the RFC versions. It sounded too complex for people
to maintain a separate tmp file when make O=dir would do it on a much
better and automated way.
-
With regards to the Python transition, since our Makefile allows
switching to a different script since ever[1], I'm playing with
the idea of sending a patch series with:
Patch 1:
- drops Sphinx version check from both kerneldoc
(-sphinx-version parameter) and the corresponding Sphinx extension;
patch 2:
- renames kerneldoc to kerneldoc.pl
- creates a symlink:
kerneldoc.pl -> kerneldoc
patch 3:
- adds kerneldoc.py:
patch 4:
- add info messages on both versions related to the transition,
and instructions about using KERNELDOC=<script> makefile and ask
people to report eventual regressions with new script.
patch 5:
- change kerneldoc symlink to point to kerneldoc.py
We can then keep both for maybe one Kernel cycle and see how it goes,
stop accepting patches to the Perl version, in favor of doing the needed
changes at the Python one.
If everything goes well, we can remove the venerable Perl version on the
upcoming merge window, and change the Sphinx extension to use the Python
classes directly instead of running an external executable code.
What do you think?
-
I'm in doubt if I should split the Kernel classes for the Python version
into a scripts/lib/kdoc directory on this series or doing such change
only after we drop the Perl version.
Keeping it on a single file helps to do more complex code adjustments
on a single place, specially if we end renaming/shifting stuff[2].
[1] I didn't remember about that - it is a very welcomed feature,
probably thanks to Markus.
[2] the currently global const regex macros is something that I want
to rename and place them inside a class (or on multiple classes).
Also, Python coding style is to use uppercase for const. There is
currently a Pylint disabled warning about that. So, I do plan to
do such changes in the future to make it more compatible with
Python coding style.
-
On a separate but related issue, perhaps we should start talking about
coding style. We don't have anything defined at the Kernel, and
different scripts follow different conventions (or most likely
don't follow any convention at all). We should probably think having
something defined in the future.
