Em Tue, 13 Jan 2026 14:52:56 -0500 John Snow <[email protected]> escreveu:
> 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 Giving my 2 cents here: at Linux Kernel, we're moving documentation to tools/docs document because just scripts/ became too messy. Also, having a directory specifically for python modules makes sense. So, we just moved libraries to tools/python/lib. > 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/. In the specific case of kernel-doc + modules this is required at build time, if docs are enabled. > > 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. Not quite: those files are the actual kernel-doc implementation. The exec is just a shell to call them. At the Linux Kernel, we don't even run kernel-doc exec anymore: they're called directly by the Sphinx kerneldoc extension. We use the exec just to allow us to run manually, as it can be helpful to see the ReST result when problems rise. Right now on QEMU we're still running the exec, but this can change some day. > > > > 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 > > :| > > > Thanks, Mauro
