linux-kernel - Re: [GIT PULL for v6.17-rc2] add a generic yaml parser integrated with Netlink specs generation

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 for Android: free password hash cracker in your pocket

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

Message-ID: <20250813091526.3cf39352@foz.lan>
Date: Wed, 13 Aug 2025 09:15:26 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Akira Yokosawa <akiyks@...il.com>
Cc: Jonathan Corbet <corbet@....net>, Jakub Kicinski <kuba@...nel.org>, EDAC
 Mailing List <linux-edac@...r.kernel.org>, Linux Kernel Mailing List
 <linux-kernel@...r.kernel.org>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, "David S. Miller" <davem@...emloft.net>,
 Ignacio Encinas Rubio <ignacio@...cinas.com>, Marco Elver
 <elver@...gle.com>, Shuah Khan <skhan@...uxfoundation.org>, Donald Hunter
 <donald.hunter@...il.com>, Eric Dumazet <edumazet@...gle.com>, Jan Stancek
 <jstancek@...hat.com>, Paolo Abeni <pabeni@...hat.com>, Ruben Wauters
 <rubenru09@....com>, linux-kernel-mentees@...ts.linux.dev,
 netdev@...r.kernel.org, Breno Leitao <leitao@...ian.org>, Randy Dunlap
 <rdunlap@...radead.org>, Simon Horman <horms@...nel.org>
Subject: Re: [GIT PULL for v6.17-rc2] add a generic yaml parser integrated
 with Netlink specs generation

On Wed, 13 Aug 2025 11:49:50 +0900
Akira Yokosawa <akiyks@...il.com> wrote:

> [-CC: LKMM folks and list; this has nothing to do with the memory model]
> 
> Hi Jon,
> 
> On Tue, 12 Aug 2025 12:31:03 -0600, Jonathan Corbet wrote:
> > Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:
> >   
> >> Hi Jon/Jakub,
> >>
> >> In case you both prefer to merge from a stable tag, please pull from:
> >>
> >> 	git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-docs.git docs/v6.17-1
> >>
> >> For:
> >>
> >> - An YAML parser Sphinx plugin, integrated with Netlink YAML doc
> >>   parser.  
> > 
> > OK, I have done that.  I will note that it adds a warning:
> >   
> >> Documentation/networking/netlink_spec/index.rst: WARNING: document isn't included in any toctree  
> > 
> > ...it might be nice to get that straightened out.  
> 
> After the merge, "git status" complains:
> 
>     Untracked files:
>       (use "git add <file>..." to include in what will be committed)
> 	Documentation/networking/netlink_spec/
> 
> So, I don't think there is anything you can do in the Git repo side ...
> 
> We need to remember to "rm -rf" the directory after crossing this merge
> point.
> 
> In theory, such "rm -rf" could be added somewhere in Documentation/Makefile,
> but that would not work well with write-protected shared kernel repos.

And this is actually what started this patch series: the original
approach of auto-generating and writing files under
Documentation/networking/netlink_spec/ is problematic: a patch
that renamed some files caused the past version of the generated
files to generate warnings.

So, yeah, with the old approach one needs to manually clean up
Documentation/networking/netlink_spec/ if this was not the first
time doc were built on a git clone instance.

Btw, before my patch series, there was the cleandocs target
was:

	YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst
	YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec
	YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs
	YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
	YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))

	cleandocs:
		$(Q)rm -f $(YNL_INDEX) $(YNL_RST_FILES)
		$(Q)rm -rf $(BUILDDIR)
		$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean

It means that, with the old approach, the safe way to apply
patches that touch YAML Netlink (YNL) is to do:

	make cleandocs			# remove old auto-generated patches from /Documentation/networking/netlink_spec
	<apply new series>
	make htmldocs

to ensure that the previous auto-generated files were removed.

Thanks,
Mauro