Cleaning up contrib/ and tools/

Cleaning up contrib/ and tools/

[Peter Maydell]

We have a couple of directories in our source tree which have
accumulated things in them that don't really belong there; this is a
proposal to clean up by moving things to more appropriate locations
(as 11.1 work, obviously).

Firstly, contrib/ has a tendency to be a dumping ground for stuff that
we didn't think hard enough about finding a good home for, and for
things in a weird "not really maintained" state. We should either
(a) care enough about something to give it a correct home and to
maintain it, or (b) not care about it, and kick it out of our tree.

Secondly, tools/ exists but is very under-used. I think it should be
for the set of standalone tools that we build if you configure
--enable-tools and which we document in docs/tools.  Currently it
contains two things, one of which doesn't match that idea...

So, starting with tools/:

 * tools/ebpf/ is the source for the pre-generated
   ebpf/rss.bpf.skeleton.h ; it should move to ebpf/
 * tools/i386/qemu-vmsr-helper.c is the source for the
   qemu-vmsr-helper tool; it can stay (should it lose its
   i386/ subdir ?)
 * the tools which currently are in the top level directory
   should move into tools/:
    - qemu-bridge-helper.c
    - qemu-edid.c
    - qemu-img.c
    - qemu-io.c
    - qemu-keymap.c
    - qemu-nbd.c

And for contrib/, easy ones first:
 * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
 * contrib/elf2dmp moves to tools/
 * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
 * contrib/plugins moves to plugins/plugins (or a different subdir
   name of your choice)

For contrib/, ones I'm less sure about:

 * contrib/vmapple/uuid.sh is a one-liner; we should either commit to
   having this, by giving it a better name and documentation and
   installing it in 'make install', or else junk it and have
   docs/system/arm/vmapple.rst give you the plutil command and tell
   you to run it directly.
 * contrib/gitdm moves to scripts/ ? It's just config data for
   generating statistics about patches, so with other
   developer-related stuff makes sense.
 * contrib/systemd -- we don't do anything with these (e.g.
   'make install' ignores them), so I am sceptical about their
   usefulness. We could drop them, or move them to scripts/, or put
   them in tools/ and qga/ with the tools that they are systemd
   scripts for.

Then we can delete contrib/ entirely.

(scripts/ is also in danger of being "miscellaneous dumping
ground", of course. I have tried not to suggest it as the
destination when I could think of an alternative.)

-- PMM

Re: Cleaning up contrib/ and tools/

[Daniel P. Berrangé]

On Tue, Mar 24, 2026 at 05:09:33PM +0000, Peter Maydell wrote:
> So, starting with tools/:
> 
>  * tools/ebpf/ is the source for the pre-generated
>    ebpf/rss.bpf.skeleton.h ; it should move to ebpf/
>  * tools/i386/qemu-vmsr-helper.c is the source for the
>    qemu-vmsr-helper tool; it can stay (should it lose its
>    i386/ subdir ?)

Given it is a single source file and we don't have a big
collection of other i386-only tools, I think we loose
nothing by removing the extra i386 subdir.

>  * the tools which currently are in the top level directory
>    should move into tools/:
>     - qemu-bridge-helper.c
>     - qemu-edid.c
>     - qemu-img.c
>     - qemu-io.c
>     - qemu-keymap.c
>     - qemu-nbd.c

ack

> And for contrib/, easy ones first:
>  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>  * contrib/elf2dmp moves to tools/
>  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>  * contrib/plugins moves to plugins/plugins (or a different subdir
>    name of your choice)

plugins/demos or plugins/examples or are they more formal than
demo-ware ?

> For contrib/, ones I'm less sure about:
> 
>  * contrib/vmapple/uuid.sh is a one-liner; we should either commit to
>    having this, by giving it a better name and documentation and
>    installing it in 'make install', or else junk it and have
>    docs/system/arm/vmapple.rst give you the plutil command and tell
>    you to run it directly.

Earlier versions of the vmapple patch series had the command
listed in the rst docs, but it was then pulled out into the
script to make it easier for users.

Rename to qemu-vmapple-extract-uuid  or something less verbose ?

>  * contrib/gitdm moves to scripts/ ? It's just config data for
>    generating statistics about patches, so with other
>    developer-related stuff makes sense.

Yes, scripts seems reasonable for that.

>  * contrib/systemd -- we don't do anything with these (e.g.
>    'make install' ignores them), so I am sceptical about their
>    usefulness. We could drop them, or move them to scripts/, or put
>    them in tools/ and qga/ with the tools that they are systemd
>    scripts for.

I think they should probably move to the respective dir
that contains the tool source, and be installed.

The qga one differs from what Fedora ships, but by adding
them as installed files, we likely motivate someone to
care more about what they contain.

> (scripts/ is also in danger of being "miscellaneous dumping
> ground", of course. I have tried not to suggest it as the
> destination when I could think of an alternative.)

One problem at a time :-) Unlike contrib/, scripts/ is not end-user
facing it is just a grab bag of tools targetted at QEMU contributors
or the build system. So those only need to stay working & supported
to the extent that we're using them ourselves.

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: Cleaning up contrib/ and tools/

[Pierrick Bouvier]

On 3/24/26 10:09 AM, Peter Maydell wrote:
> We have a couple of directories in our source tree which have
> accumulated things in them that don't really belong there; this is a
> proposal to clean up by moving things to more appropriate locations
> (as 11.1 work, obviously).
> 
> Firstly, contrib/ has a tendency to be a dumping ground for stuff that
> we didn't think hard enough about finding a good home for, and for
> things in a weird "not really maintained" state. We should either
> (a) care enough about something to give it a correct home and to
> maintain it, or (b) not care about it, and kick it out of our tree.
> 
> Secondly, tools/ exists but is very under-used. I think it should be
> for the set of standalone tools that we build if you configure
> --enable-tools and which we document in docs/tools.  Currently it
> contains two things, one of which doesn't match that idea...
> 
> So, starting with tools/:
> 
>   * tools/ebpf/ is the source for the pre-generated
>     ebpf/rss.bpf.skeleton.h ; it should move to ebpf/
>   * tools/i386/qemu-vmsr-helper.c is the source for the
>     qemu-vmsr-helper tool; it can stay (should it lose its
>     i386/ subdir ?)
>   * the tools which currently are in the top level directory
>     should move into tools/:
>      - qemu-bridge-helper.c
>      - qemu-edid.c
>      - qemu-img.c
>      - qemu-io.c
>      - qemu-keymap.c
>      - qemu-nbd.c
> 
> And for contrib/, easy ones first:
>   * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>   * contrib/elf2dmp moves to tools/
>   * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>   * contrib/plugins moves to plugins/plugins (or a different subdir
>     name of your choice)
>

I would suggest plugins/contrib or plugins/community, to make clear they 
are the community contributed ones.
@Alex, do you have a different suggestion/preference?

Moving those sources will break build folder hierarchy also, which is an 
issue for all existing binaries built from contrib anyway.
I'm not sure there is anything sane to do to fix that except accepting 
the breaking change.

> For contrib/, ones I'm less sure about:
> 
>   * contrib/vmapple/uuid.sh is a one-liner; we should either commit to
>     having this, by giving it a better name and documentation and
>     installing it in 'make install', or else junk it and have
>     docs/system/arm/vmapple.rst give you the plutil command and tell
>     you to run it directly.
>   * contrib/gitdm moves to scripts/ ? It's just config data for
>     generating statistics about patches, so with other
>     developer-related stuff makes sense.
>   * contrib/systemd -- we don't do anything with these (e.g.
>     'make install' ignores them), so I am sceptical about their
>     usefulness. We could drop them, or move them to scripts/, or put
>     them in tools/ and qga/ with the tools that they are systemd
>     scripts for.
> 
> Then we can delete contrib/ entirely.
> 
> (scripts/ is also in danger of being "miscellaneous dumping
> ground", of course. I have tried not to suggest it as the
> destination when I could think of an alternative.)
> 
> -- PMM

Regards,
Pierrick

Re: Cleaning up contrib/ and tools/

[Peter Maydell]

On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
<pierrick.bouvier@linaro.org> wrote:
>
> On 3/24/26 10:09 AM, Peter Maydell wrote:
> > And for contrib/, easy ones first:
> >   * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
> >   * contrib/elf2dmp moves to tools/
> >   * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
> >   * contrib/plugins moves to plugins/plugins (or a different subdir
> >     name of your choice)
> >
>
> I would suggest plugins/contrib or plugins/community, to make clear they
> are the community contributed ones.
> @Alex, do you have a different suggestion/preference?

I firmly do not want us to have anything that claims to be
"contrib" or "community" or similar. Everything in QEMU is
community contributed in some sense. Either we care about
and maintain these plugins, in which case call them "plugins",
or we do not in fact care about and maintain them, in which
case delete them. "In the tree but not maintained" is not
a category I think we should have, and that is what "contrib"
generally implies.

> Moving those sources will break build folder hierarchy also, which is an
> issue for all existing binaries built from contrib anyway.
> I'm not sure there is anything sane to do to fix that except accepting
> the breaking change.

What are we breaking here ? Nothing outside QEMU ought to be
depending on the layout of our source tree. When we move things
around we'll update the meson.build and the documentation.
I don't think we have 'contrib' in our installed-locations
layout (tools get installed into the bin/ dir, for instance),
but I might have missed something.

-- PMM

Re: Cleaning up contrib/ and tools/

[Pierrick Bouvier]

On 3/24/26 11:33 AM, Peter Maydell wrote:
> On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
> <pierrick.bouvier@linaro.org> wrote:
>>
>> On 3/24/26 10:09 AM, Peter Maydell wrote:
>>> And for contrib/, easy ones first:
>>>    * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>>>    * contrib/elf2dmp moves to tools/
>>>    * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>>>    * contrib/plugins moves to plugins/plugins (or a different subdir
>>>      name of your choice)
>>>
>>
>> I would suggest plugins/contrib or plugins/community, to make clear they
>> are the community contributed ones.
>> @Alex, do you have a different suggestion/preference?
> 
> I firmly do not want us to have anything that claims to be
> "contrib" or "community" or similar. Everything in QEMU is
> community contributed in some sense. Either we care about
> and maintain these plugins, in which case call them "plugins",
> or we do not in fact care about and maintain them, in which
> case delete them. "In the tree but not maintained" is not
> a category I think we should have, and that is what "contrib"
> generally implies.
>

We make sure they build, and test them (manually) on changes. The only 
difference with tests/tcg/plugins is that those are used for make 
check-tcg. I personnally consider both of them as properly maintained.

>> Moving those sources will break build folder hierarchy also, which is an
>> issue for all existing binaries built from contrib anyway.
>> I'm not sure there is anything sane to do to fix that except accepting
>> the breaking change.
> 
> What are we breaking here ? Nothing outside QEMU ought to be
> depending on the layout of our source tree. When we move things
> around we'll update the meson.build and the documentation.
> I don't think we have 'contrib' in our installed-locations
> layout (tools get installed into the bin/ dir, for instance),
> but I might have missed something.
>

I was thinking more about users that might have custom scripts using 
various contrib plugins, or using vhost-* binaries or ivshmem-server or 
elf2dmp. They will be relocated because meson automatically uses layout 
of sources in build folder.
It's not a big deal anyway.

> -- PMM

Regards,
Pierrick

Re: Cleaning up contrib/ and tools/

[Kostiantyn Kostiuk]

[-- Attachment #1: Type: text/plain, Size: 3036 bytes --]

On Tue, Mar 24, 2026 at 7:09 PM Peter Maydell <peter.maydell@linaro.org>
wrote:

> We have a couple of directories in our source tree which have
> accumulated things in them that don't really belong there; this is a
> proposal to clean up by moving things to more appropriate locations
> (as 11.1 work, obviously).
>
> Firstly, contrib/ has a tendency to be a dumping ground for stuff that
> we didn't think hard enough about finding a good home for, and for
> things in a weird "not really maintained" state. We should either
> (a) care enough about something to give it a correct home and to
> maintain it, or (b) not care about it, and kick it out of our tree.
>
> Secondly, tools/ exists but is very under-used. I think it should be
> for the set of standalone tools that we build if you configure
> --enable-tools and which we document in docs/tools.  Currently it
> contains two things, one of which doesn't match that idea...
>
> So, starting with tools/:
>
>  * tools/ebpf/ is the source for the pre-generated
>    ebpf/rss.bpf.skeleton.h ; it should move to ebpf/
>  * tools/i386/qemu-vmsr-helper.c is the source for the
>    qemu-vmsr-helper tool; it can stay (should it lose its
>    i386/ subdir ?)
>  * the tools which currently are in the top level directory
>    should move into tools/:
>     - qemu-bridge-helper.c
>     - qemu-edid.c
>     - qemu-img.c
>     - qemu-io.c
>     - qemu-keymap.c
>     - qemu-nbd.c
>
> And for contrib/, easy ones first:
>  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>  * contrib/elf2dmp moves to tools/
>  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>  * contrib/plugins moves to plugins/plugins (or a different subdir
>    name of your choice)
>
> For contrib/, ones I'm less sure about:
>
>  * contrib/vmapple/uuid.sh is a one-liner; we should either commit to
>    having this, by giving it a better name and documentation and
>    installing it in 'make install', or else junk it and have
>    docs/system/arm/vmapple.rst give you the plutil command and tell
>    you to run it directly.
>  * contrib/gitdm moves to scripts/ ? It's just config data for
>    generating statistics about patches, so with other
>    developer-related stuff makes sense.
>  * contrib/systemd -- we don't do anything with these (e.g.
>    'make install' ignores them), so I am sceptical about their
>    usefulness. We could drop them, or move them to scripts/, or put
>    them in tools/ and qga/ with the tools that they are systemd
>    scripts for.
>

Not sure that we need qemu-guest-agent.service at all. Fedora/CentOS don't
use it and create a different service file.
I think this one can be dropped.

Best Regards,
Kostiantyn Kostiuk.



>
> Then we can delete contrib/ entirely.
>
> (scripts/ is also in danger of being "miscellaneous dumping
> ground", of course. I have tried not to suggest it as the
> destination when I could think of an alternative.)
>
> -- PMM
>
>

[-- Attachment #2: Type: text/html, Size: 3914 bytes --]

Re: Cleaning up contrib/ and tools/

[Daniel P. Berrangé]

On Tue, Mar 24, 2026 at 11:44:37AM -0700, Pierrick Bouvier wrote:
> On 3/24/26 11:33 AM, Peter Maydell wrote:
> > On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
> > > Moving those sources will break build folder hierarchy also, which is an
> > > issue for all existing binaries built from contrib anyway.
> > > I'm not sure there is anything sane to do to fix that except accepting
> > > the breaking change.
> > 
> > What are we breaking here ? Nothing outside QEMU ought to be
> > depending on the layout of our source tree. When we move things
> > around we'll update the meson.build and the documentation.
> > I don't think we have 'contrib' in our installed-locations
> > layout (tools get installed into the bin/ dir, for instance),
> > but I might have missed something.
> > 
> 
> I was thinking more about users that might have custom scripts using various
> contrib plugins, or using vhost-* binaries or ivshmem-server or elf2dmp.
> They will be relocated because meson automatically uses layout of sources in
> build folder.
> It's not a big deal anyway.

If we're concerned about external users relying on stuff in contrib/,
then that is exactly the reason why contrib/ should go, and everything
be considered an officially supported deliverable of QEMU with an
appropriate home in the source tree, and covered by 'make install'.

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: Cleaning up contrib/ and tools/

[Marc-André Lureau]

Hi

On Wed, Mar 25, 2026 at 1:22 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Tue, Mar 24, 2026 at 11:44:37AM -0700, Pierrick Bouvier wrote:
> > On 3/24/26 11:33 AM, Peter Maydell wrote:
> > > On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
> > > > Moving those sources will break build folder hierarchy also, which is an
> > > > issue for all existing binaries built from contrib anyway.
> > > > I'm not sure there is anything sane to do to fix that except accepting
> > > > the breaking change.
> > >
> > > What are we breaking here ? Nothing outside QEMU ought to be
> > > depending on the layout of our source tree. When we move things
> > > around we'll update the meson.build and the documentation.
> > > I don't think we have 'contrib' in our installed-locations
> > > layout (tools get installed into the bin/ dir, for instance),
> > > but I might have missed something.
> > >
> >
> > I was thinking more about users that might have custom scripts using various
> > contrib plugins, or using vhost-* binaries or ivshmem-server or elf2dmp.
> > They will be relocated because meson automatically uses layout of sources in
> > build folder.
> > It's not a big deal anyway.
>
> If we're concerned about external users relying on stuff in contrib/,
> then that is exactly the reason why contrib/ should go, and everything
> be considered an officially supported deliverable of QEMU with an
> appropriate home in the source tree, and covered by 'make install'.

A solution worth considering is to split into various meson
subprojects. I did it for libslirp, libvhost-user, and started qga a
few years ago (https://patchew.org/QEMU/20220810124857.1360211-1-marcandre.lureau@redhat.com/)

This requires a bit of reorganization to have some common (internal)
libraries, but imho, we would make the whole project cleaner that way.

-- 
Marc-André Lureau

Re: Cleaning up contrib/ and tools/

[Alex Bennée]

Pierrick Bouvier <pierrick.bouvier@linaro.org> writes:

> On 3/24/26 11:33 AM, Peter Maydell wrote:
>> On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
>> <pierrick.bouvier@linaro.org> wrote:
>>>
>>> On 3/24/26 10:09 AM, Peter Maydell wrote:
>>>> And for contrib/, easy ones first:
>>>>    * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>>>>    * contrib/elf2dmp moves to tools/
>>>>    * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>>>>    * contrib/plugins moves to plugins/plugins (or a different subdir
>>>>      name of your choice)
>>>>
>>>
>>> I would suggest plugins/contrib or plugins/community, to make clear they
>>> are the community contributed ones.
>>> @Alex, do you have a different suggestion/preference?
>> I firmly do not want us to have anything that claims to be
>> "contrib" or "community" or similar. Everything in QEMU is
>> community contributed in some sense. Either we care about
>> and maintain these plugins, in which case call them "plugins",
>> or we do not in fact care about and maintain them, in which
>> case delete them. "In the tree but not maintained" is not
>> a category I think we should have, and that is what "contrib"
>> generally implies.
>>
>
> We make sure they build, and test them (manually) on changes. The only
> difference with tests/tcg/plugins is that those are used for make
> check-tcg. I personnally consider both of them as properly maintained.

They are maintained.

The aim have having these more complete plugins in the source tree was
to ensure they where updated as APIs change as well as provide useful
tools compared to the more toy like implementations we use for
check-tcg.

I'm not sure about having them directly in the plugins folder as their
implementation is meant to be separated from the core QEMU code itself.
Maybe tools/plugins?

While we are at it we should consider moving the example plugin descriptions
from About/Emulation/TCG Plugins to the Tools section.

>
>>> Moving those sources will break build folder hierarchy also, which is an
>>> issue for all existing binaries built from contrib anyway.
>>> I'm not sure there is anything sane to do to fix that except accepting
>>> the breaking change.
>> What are we breaking here ? Nothing outside QEMU ought to be
>> depending on the layout of our source tree. When we move things
>> around we'll update the meson.build and the documentation.
>> I don't think we have 'contrib' in our installed-locations
>> layout (tools get installed into the bin/ dir, for instance),
>> but I might have missed something.
>>
>
> I was thinking more about users that might have custom scripts using
> various contrib plugins, or using vhost-* binaries or ivshmem-server
> or elf2dmp. They will be relocated because meson automatically uses
> layout of sources in build folder.
> It's not a big deal anyway.
>
>> -- PMM
>
> Regards,
> Pierrick

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: Cleaning up contrib/ and tools/

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> We have a couple of directories in our source tree which have
> accumulated things in them that don't really belong there; this is a
> proposal to clean up by moving things to more appropriate locations
> (as 11.1 work, obviously).
>
> Firstly, contrib/ has a tendency to be a dumping ground for stuff that
> we didn't think hard enough about finding a good home for, and for
> things in a weird "not really maintained" state. We should either
> (a) care enough about something to give it a correct home and to
> maintain it, or (b) not care about it, and kick it out of our tree.
>
> Secondly, tools/ exists but is very under-used. I think it should be
> for the set of standalone tools that we build if you configure
> --enable-tools and which we document in docs/tools.  Currently it
> contains two things, one of which doesn't match that idea...
>
> So, starting with tools/:

[...]

> And for contrib/, easy ones first:
>  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>  * contrib/elf2dmp moves to tools/
>  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/

Absolutely not.  This is example code, provided in the hope of helping
people understand the protocol, and experiment with it.  It is entirely
unfit for more serious use, and that's intentional.

If somebody contributes something fit for more serious use, and there's
interest in maintaining it in that role going forward, and that code is
still simple enough to serve the example code's purpose as described
above, we can drop the example code from contrib/.

We could also drop it without replacement just to have an empty
contrib/.  I think that would be a disservice to people trying to use
ivshmem.  But then I'm the guy who keeps telling people *not* to use it,
so why should I care?

Perhaps contrib/ is not a good home for example code.  It seems to
bother people whose judgement I respect.  Can we find a better home?

>  * contrib/plugins moves to plugins/plugins (or a different subdir
>    name of your choice)
>
> For contrib/, ones I'm less sure about:

[...]

Re: Cleaning up contrib/ and tools/

[Alex Bennée]

Markus Armbruster <armbru@redhat.com> writes:

> Peter Maydell <peter.maydell@linaro.org> writes:
>
>> We have a couple of directories in our source tree which have
>> accumulated things in them that don't really belong there; this is a
>> proposal to clean up by moving things to more appropriate locations
>> (as 11.1 work, obviously).
>>
>> Firstly, contrib/ has a tendency to be a dumping ground for stuff that
>> we didn't think hard enough about finding a good home for, and for
>> things in a weird "not really maintained" state. We should either
>> (a) care enough about something to give it a correct home and to
>> maintain it, or (b) not care about it, and kick it out of our tree.
>>
>> Secondly, tools/ exists but is very under-used. I think it should be
>> for the set of standalone tools that we build if you configure
>> --enable-tools and which we document in docs/tools.  Currently it
>> contains two things, one of which doesn't match that idea...
>>
>> So, starting with tools/:
>
> [...]
>
>> And for contrib/, easy ones first:
>>  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>>  * contrib/elf2dmp moves to tools/
>>  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>
> Absolutely not.  This is example code, provided in the hope of helping
> people understand the protocol, and experiment with it.  It is entirely
> unfit for more serious use, and that's intentional.

The rust-vmm project has gpu, input and scsi vhost-user daemons which
are actively maintained. I don't think there is a blk device although I
guess people should be directed to use qsd for storage?

>
> If somebody contributes something fit for more serious use, and there's
> interest in maintaining it in that role going forward, and that code is
> still simple enough to serve the example code's purpose as described
> above, we can drop the example code from contrib/.
>
> We could also drop it without replacement just to have an empty
> contrib/.  I think that would be a disservice to people trying to use
> ivshmem.  But then I'm the guy who keeps telling people *not* to use it,
> so why should I care?
>
> Perhaps contrib/ is not a good home for example code.  It seems to
> bother people whose judgement I respect.  Can we find a better home?
>
>>  * contrib/plugins moves to plugins/plugins (or a different subdir
>>    name of your choice)
>>
>> For contrib/, ones I'm less sure about:
>
> [...]

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: Cleaning up contrib/ and tools/

[Pierrick Bouvier]

On 3/25/26 4:11 AM, Alex Bennée wrote:
> Pierrick Bouvier <pierrick.bouvier@linaro.org> writes:
> 
>> On 3/24/26 11:33 AM, Peter Maydell wrote:
>>> On Tue, 24 Mar 2026 at 18:28, Pierrick Bouvier
>>> <pierrick.bouvier@linaro.org> wrote:
>>>>
>>>> On 3/24/26 10:09 AM, Peter Maydell wrote:
>>>>> And for contrib/, easy ones first:
>>>>>     * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
>>>>>     * contrib/elf2dmp moves to tools/
>>>>>     * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>>>>>     * contrib/plugins moves to plugins/plugins (or a different subdir
>>>>>       name of your choice)
>>>>>
>>>>
>>>> I would suggest plugins/contrib or plugins/community, to make clear they
>>>> are the community contributed ones.
>>>> @Alex, do you have a different suggestion/preference?
>>> I firmly do not want us to have anything that claims to be
>>> "contrib" or "community" or similar. Everything in QEMU is
>>> community contributed in some sense. Either we care about
>>> and maintain these plugins, in which case call them "plugins",
>>> or we do not in fact care about and maintain them, in which
>>> case delete them. "In the tree but not maintained" is not
>>> a category I think we should have, and that is what "contrib"
>>> generally implies.
>>>
>>
>> We make sure they build, and test them (manually) on changes. The only
>> difference with tests/tcg/plugins is that those are used for make
>> check-tcg. I personnally consider both of them as properly maintained.
> 
> They are maintained.
> 
> The aim have having these more complete plugins in the source tree was
> to ensure they where updated as APIs change as well as provide useful
> tools compared to the more toy like implementations we use for
> check-tcg.
> 
> I'm not sure about having them directly in the plugins folder as their
> implementation is meant to be separated from the core QEMU code itself.
> Maybe tools/plugins?

Fine for me.
Peter, is that ok for you too?

> 
> While we are at it we should consider moving the example plugin descriptions
> from About/Emulation/TCG Plugins to the Tools section.
>

Yes, good idea.

>>
>>>> Moving those sources will break build folder hierarchy also, which is an
>>>> issue for all existing binaries built from contrib anyway.
>>>> I'm not sure there is anything sane to do to fix that except accepting
>>>> the breaking change.
>>> What are we breaking here ? Nothing outside QEMU ought to be
>>> depending on the layout of our source tree. When we move things
>>> around we'll update the meson.build and the documentation.
>>> I don't think we have 'contrib' in our installed-locations
>>> layout (tools get installed into the bin/ dir, for instance),
>>> but I might have missed something.
>>>
>>
>> I was thinking more about users that might have custom scripts using
>> various contrib plugins, or using vhost-* binaries or ivshmem-server
>> or elf2dmp. They will be relocated because meson automatically uses
>> layout of sources in build folder.
>> It's not a big deal anyway.
>>
>>> -- PMM
>>
>> Regards,
>> Pierrick
> 

Re: Cleaning up contrib/ and tools/

[Peter Maydell]

On Wed, 25 Mar 2026 at 15:17, Pierrick Bouvier
<pierrick.bouvier@linaro.org> wrote:
>
> On 3/25/26 4:11 AM, Alex Bennée wrote:
> > The aim have having these more complete plugins in the source tree was
> > to ensure they where updated as APIs change as well as provide useful
> > tools compared to the more toy like implementations we use for
> > check-tcg.
> >
> > I'm not sure about having them directly in the plugins folder as their
> > implementation is meant to be separated from the core QEMU code itself.
> > Maybe tools/plugins?
>
> Fine for me.
> Peter, is that ok for you too?

It doesn't really fit with "tools/ is where we put the things
which --enable-tools causes us to build and which we document
in docs/tools". The plugins are neither of those. That's why
I thought some subdirectory of plugins/ would fit better.

-- PMM

Re: Cleaning up contrib/ and tools/

[Peter Maydell]

On Wed, 25 Mar 2026 at 11:44, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > We have a couple of directories in our source tree which have
> > accumulated things in them that don't really belong there; this is a
> > proposal to clean up by moving things to more appropriate locations
> > (as 11.1 work, obviously).
> >
> > Firstly, contrib/ has a tendency to be a dumping ground for stuff that
> > we didn't think hard enough about finding a good home for, and for
> > things in a weird "not really maintained" state. We should either
> > (a) care enough about something to give it a correct home and to
> > maintain it, or (b) not care about it, and kick it out of our tree.
> >
> > Secondly, tools/ exists but is very under-used. I think it should be
> > for the set of standalone tools that we build if you configure
> > --enable-tools and which we document in docs/tools.  Currently it
> > contains two things, one of which doesn't match that idea...
> >
> > So, starting with tools/:
>
> [...]
>
> > And for contrib/, easy ones first:
> >  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
> >  * contrib/elf2dmp moves to tools/
> >  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
>
> Absolutely not.  This is example code, provided in the hope of helping
> people understand the protocol, and experiment with it.  It is entirely
> unfit for more serious use, and that's intentional.

So, example code but we don't think it's a good example ? :-)

Our system documentation seems to assume you're going to run
ivshmem-server:

https://www.qemu.org/docs/master/system/devices/ivshmem.html

> Perhaps contrib/ is not a good home for example code.  It seems to
> bother people whose judgement I respect.  Can we find a better home?

I'm not sure to what extent we should be in the business of
providing example code. If we are doing that we should label
it all a bit better...

-- PMM

Re: Cleaning up contrib/ and tools/

[Daniel P. Berrangé]

On Wed, Mar 25, 2026 at 04:49:57PM +0000, Peter Maydell wrote:
> On Wed, 25 Mar 2026 at 11:44, Markus Armbruster <armbru@redhat.com> wrote:
> >
> > Peter Maydell <peter.maydell@linaro.org> writes:
> >
> > > We have a couple of directories in our source tree which have
> > > accumulated things in them that don't really belong there; this is a
> > > proposal to clean up by moving things to more appropriate locations
> > > (as 11.1 work, obviously).
> > >
> > > Firstly, contrib/ has a tendency to be a dumping ground for stuff that
> > > we didn't think hard enough about finding a good home for, and for
> > > things in a weird "not really maintained" state. We should either
> > > (a) care enough about something to give it a correct home and to
> > > maintain it, or (b) not care about it, and kick it out of our tree.
> > >
> > > Secondly, tools/ exists but is very under-used. I think it should be
> > > for the set of standalone tools that we build if you configure
> > > --enable-tools and which we document in docs/tools.  Currently it
> > > contains two things, one of which doesn't match that idea...
> > >
> > > So, starting with tools/:
> >
> > [...]
> >
> > > And for contrib/, easy ones first:
> > >  * contrib/vhost-user-{blk,bridge,gpu,input,scsi} move to tools/
> > >  * contrib/elf2dmp moves to tools/
> > >  * contrib/ivshmem-client and contrib/ivshmem-server move to tools/
> >
> > Absolutely not.  This is example code, provided in the hope of helping
> > people understand the protocol, and experiment with it.  It is entirely
> > unfit for more serious use, and that's intentional.
> 
> So, example code but we don't think it's a good example ? :-)
> 
> Our system documentation seems to assume you're going to run
> ivshmem-server:
> 
> https://www.qemu.org/docs/master/system/devices/ivshmem.html
> 
> > Perhaps contrib/ is not a good home for example code.  It seems to
> > bother people whose judgement I respect.  Can we find a better home?
> 
> I'm not sure to what extent we should be in the business of
> providing example code. If we are doing that we should label
> it all a bit better...

FWIW, the server does warn the user on startup since Markus commited
a335c6f204eefba8ff935bcee8f31f51d2174119:


+    /*
+     * Do not remove this notice without adding proper error handling!
+     * Start with handling ivshmem_server_send_one_msg() failure.
+     */
+    printf("*** Example code, do not use in production ***\n");


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: Cleaning up contrib/ and tools/

[Peter Maydell]

On Wed, 25 Mar 2026 at 16:49, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Wed, 25 Mar 2026 at 11:44, Markus Armbruster <armbru@redhat.com> wrote:
> > Perhaps contrib/ is not a good home for example code.  It seems to
> > bother people whose judgement I respect.  Can we find a better home?
>
> I'm not sure to what extent we should be in the business of
> providing example code. If we are doing that we should label
> it all a bit better...

One thought that came to mind: for example code, perhaps we
should think of it in terms of it being part of our
documentation, so for instance:
 * shipping it (under /usr/share/qemu/code-examples/ ??
   as a subdir of the docs ???)
 * making sure the docs can hyperlink to the example code
 * making sure we have docs explaining the example code and
   what we intend to demonstrate by it (the plugins docs
   are very good here)

-- PMM