On Tue, Jan 13, 2026 at 11:44:51AM +0000, Peter Maydell wrote: > On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab > <[email protected]> wrote: > > > > Hi Peter/John, > > > > There were several updates at kernel-doc upstream fixing bugs, > > doing cleanups and a couple of improvements. > > > > Better to keep QEMU in sync with such changes. > > > > Worth mentioning that we did some changes on Linux at the > > kernel-doc.py script itself, to avoid Kernel build to crash > > with too old Python versions, as there docs build is a > > separate target, and python >= 3.6 is a new requirement > > there. > > > > On kernel, if python < 3.6, it will simply ignore docs > > build (emitting a warning). > > > > I opted to not backport such changes, but if you prefer > > doing that, I can do that on a v2. > > --- > > > > For now, I opted to keep kernel-doc libraries at the same > > directory as before - e.g. at scripts/lib/kdoc. On Linux, > > we ended moving it to tools/lib/python/kdoc. It could make > > sense to move it on QEMU too, as it makes a little bit > > easier to keep things in sync. > > > > What do you think? > > Hi; thanks for doing this backport. I checked that the output > with this patch applied is still the same as with the old > kernel-doc, and eyeballed the diffs between our kernel-doc > and the Linux version, to confirm that we have kept our two > minor QEMU-specific modifications and haven't missed anything > from Linux's version that we ought to have. So: > > Reviewed-by: Peter Maydell <[email protected]> > > On your two questions: > > (1) As Dan says, QEMU already enforces a new enough > Python version, so we don't need to handle 3.6. I think > the main thing driving a choice to backport or not those > changes would be simply keeping in sync with Linux's > version of the script so we don't diverge. We want to > make future re-syncing of the script as easy as possible. > > (2) Regarding the location of the kernel-doc libraries: > we seem to have two things here, possibly in tension: > - we don't want to gratuitously diverge from Linux > - QEMU's directory hierarchy is not the kernel's > > In particular, I'm not sure tools/ is where we would > naturally put python libraries used during the build > process. Maybe that would be python/ for us, but I defer > to John or another Python expert on that.
I tend to see the 'python' directory as being for stuff we formally maintain as a python API for use by multiple internal consumers. This is just a bunch of helper files exclusively for use by the kernel-doc tool, and so the scripts/ directory is a decent fit for it, given that this dir is for a collection of arbitary supporting tools & scripts. As precedent, see the tracetool, which keeps all its helpers under scripts/tracetool too. TL;DR: I would not want to see a new top level tools/ directory created, and don't think it fits in python/ either; scripts/ is a fine home. With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
