Re: [PULL 35/35] docs: mark '-mon' as deprecated in favour of -object

["Daniel P. Berrangé" <berrange@redhat.com>]

On Mon, Aug 24, 2026 at 11:58:52AM +0100, Peter Maydell wrote:
> On Mon, 24 Aug 2026 at 11:48, Markus Armbruster <armbru@redhat.com> wrote:
> > Peter Maydell <peter.maydell@linaro.org> writes:
> > > Can we be more precise in deprecation messages of this kind, please?
> > > This warning is not enough for the user to be able to figure out how
> > > to change their existing command line.
> > >
> > > I had to look into deprecated.rst, check the git history to see which
> > > commit added the deprecation, then find out how this commit was adjusting
> > > the examples in the tree.
> > >
> > > Notably, "-object monitor-hmp" appears to require an "id=" despite
> > > nothing actually caring what that ID is,
> >
> > Yes, -object requires @id regardless of object type.  It calls
> > object_new_with_props_from_qdict() via user_creatable_add_qapi().
> > Together, they create the object at /objects/ID.
> 
> Yes, but usually you need the ID because it's going to plug into
> some other option somewhere else; other options like -drive
> can take an id=, but don't insist on it if you don't need it, and
> some options like chardev are only useful if you connect them to
> something else by using the ID elsewhere in the command line, so
> whether they require id= or not never comes up. So the idea of an
> option requiring an ID even though it is never referenced anywhere
> else may well be new to the user.

FYI, the ID for the monitor can be used with  object-del  QMP/HMP
commands. 

> Mostly I mention it because otherwise I think the typical user is
> going to do what I did, i.e. replace "-mon" with "-object monitor-hmp"
> and then immediately get a different error from QEMU. The warning
> being more precise could save them a step.

I was thinking that the user would do 'man qemu' where we have
docs for "-object", for each object type including "monitor-hmp/qmp",
which are shown taking an ID parameter.

> 
> > >                                          and the warning message
> > > doesn't say how to determine whether your existing -mon option
> > > should be changed to monitor-hmp or monitor-qmp. The deprecated.rst
> > > docs do say that part, but don't mention the ID bit.
> >
> > Fair points.
> >
> > Is this just "do better in the future", or are you also asking for a
> > patch to improve this warning?
> 
> Both, preferably :-)
> 
> There's an argument that the deprecation warning could look at the
> option the user actually provided and emit the exact right new
> option to use instead. But I don't think that's something we've
> ever done before for deprecations.

Essentially we have three distinct places with info - the deprecation
message at runtime, the deprecated.rst docs, and the qemu.1 manual
page. It is a trade off between how much effort we want to put into
each area.

For humans I anticipated they'd be mostly using -monitor / -qmp
convenience options, with -mon mostly used by machines which are
already familiar with -object usage already.

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 :|