Re: [PATCH v4 00/11]

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

On Fri, Feb 14, 2025 at 09:29:33PM +0100, Victor Toso wrote:
> Hi again,
> 
> This patch series intent is to introduce a generator that produces a Go
> module for Go applications to interact over QMP with QEMU.
> 
> Previous version (10 Jan 2025)
>     https://lists.gnu.org/archive/html/qemu-devel/2025-01/msg01530.html
> 
> The generated code was mostly tested using existing examples in the QAPI
> documentation, 192 instances that might have multiple QMP messages each.
> 
> You can find the the tests and the generated code in my personal repo,
> main branch:
> 
>     https://gitlab.com/victortoso/qapi-go
> 
> If you want to see the generated code from QEMU's master but per patch:
> 
>     https://gitlab.com/victortoso/qapi-go/-/commits/qapi-golang-v4-by-patch

In terms of generated code, my only real feedback is that the
re-wrapping of docs comments is having undesirable effets
on formatting

##
# @add_client:
#
# Allow client connections for VNC, Spice and socket based character
# devices to be passed in to QEMU via SCM_RIGHTS.
#
# If the FD associated with @fdname is not a socket, the command will
# fail and the FD will be closed.
#
# @protocol: protocol name.  Valid names are "vnc", "spice",
#     "@dbus-display" or the name of a character device (e.g. from
#     -chardev id=XXXX)
#
# @fdname: file descriptor name previously passed via 'getfd' command
#
# @skipauth: whether to skip authentication.  Only applies to "vnc"
#     and "spice" protocols
#
# @tls: whether to perform TLS.  Only applies to the "spice" protocol
#
# Since: 0.14
#
# .. qmp-example::
#
#     -> { "execute": "add_client", "arguments": { "protocol": "vnc",
#                                                  "fdname": "myclient" } }
#     <- { "return": {} }
##


is getting turned into


// Allow client connections for VNC, Spice and socket based character
// devices to be passed in to QEMU via SCM_RIGHTS.  If the FD
// associated with @fdname is not a socket, the command will fail and
// the FD will be closed.
//
// Since: 0.14
//
// .. qmp-example::    -> { "execute": "add_client", "arguments": {
// "protocol": "vnc",                          "fdname": "myclient" }
// }   <- { "return": {} }


the '.. qmp-example' bit is what's particularly badly affected.

If we assume that the input QAPI schemas are nicely lined wrapped,
we could probably just preserve the docs lines as-is with no change
in wrapping.

That said I'm not sure if we'll need some docs syntax changes to
make it render nicely - hard to say until the code appears up on
pkg.go.dev, so can probably worry about that aspect later.


> ################
> # Expectations #
> ################
> 
> As is, this still is a PoC that works. I'd like to have the generated
> code included in QEMU's gitlab [0] in order to write library and tools
> on top. Initial version should be considered alpha. Moving to
> beta/stable would require functional libraries and tools, but this work
> needs to be merged before one commit to that.

We don't need to overthink this. I don't think we're best served by
continuing to post many more rounds of this series. Better to just
get it into a dedicated git repo and iterate via pull requests IMHO.

Golang uses semver, so we could start publishing the generated code in
a Go module as it is today, as long as we pick a v0.XXX.0 version number.
'XXX' would be a packing of QEMU's 3 digit version into the semver 2nd
digit. This lets us indicate this is not considered a stable API, letting
us iterate on further imlp details, while also getting us in the habit of
publishing releases to track schema updates for each new QEMU.

We just need the patch for qapi-gen.py to support plugins for code
generation to make this happen, so we can decouple ongoing development
from QEMU's main git repo & release cycle.

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