On Tue, Jan 13, 2026 at 7:09 AM Daniel P. Berrangé <[email protected]> wrote: > > 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.
I more or less agree with Dan - that is how it is currently arranged. In the past, however, I have suggested moving certain other modules that are bigger than a single file into python/ for the sake of being able to maintain them more aggressively: i.e. I do not regularly check for Python regression and compatibility issues for things under scripts/, except for qapi, which is also something I proposed moving to python/ before. The current state of things is that I aggressively check and test these things: - python/* - scripts/qapi/ - docs/sphinx/qapi_domain.py - docs/sphinx/qapidoc.py Everything else is just "best effort" which generally means "I fix it when I notice that it is broken". If it is not a multi-file module and not necessary for configure+build to run, I think for now it is best kept outside of python/. > > 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 :| >
