Re: [Qemu-devel] [PATCH] tracing.txt: add missing '-' for trace option

[Yaowei Bai <baiyaowei@cmss.chinamobile.com>]

On Wed, Jun 13, 2018 at 06:27:49AM -0500, Eric Blake wrote:
> On 06/12/2018 10:50 PM, Emilio G. Cota wrote:
> >On Tue, Jun 12, 2018 at 23:15:49 -0400, Yaowei Bai wrote:
> >>Signed-off-by: Yaowei Bai <baiyaowei@cmss.chinamobile.com>
> >>---
> >>  docs/devel/tracing.txt | 2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >>diff --git a/docs/devel/tracing.txt b/docs/devel/tracing.txt
> >>index 07abbb3..6ab32cc 100644
> >>--- a/docs/devel/tracing.txt
> >>+++ b/docs/devel/tracing.txt
> >>@@ -18,7 +18,7 @@ for debugging, profiling, and observing execution.
> >>  3. Run the virtual machine to produce a trace file:
> >>-    qemu -trace events=/tmp/events ... # your normal QEMU invocation
> >>+    qemu --trace events=/tmp/events ... # your normal QEMU invocation
> >
> >The second dash is not missing; both '-args' and '--args' work.
> >
> >'-args' seems to be favoured though; see `qemu -h' or `qemu --h' :-)
> 
> Actually, we're trying to fix that:
> https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation
> 
> The one-vs-two dash usage is only supported in qemu, not in qemu-nbd
> or qemu-img (that is, qemu acts as if it uses getopt_long_only(),
> while the others use getopt_long() - except that we hand-rolled the
> parser in qemu, meaning you might find quirks where it sometimes
> doesn't even match getopt_long_only()).
> 
> At any rate, since --trace is an option that is supported across
> multiple binaries, we SHOULD favor the double-dash spelling in our
> documentation, so that you can consistently reuse the same --trace
> invocation without worrying whether the binary parses its arguments

Yes, this patch is inspired by this situation when translating DPRINT into
trace for a new qemu utility (much like qemu-nbd) following docs/devel/tracing.txt.
The utility complains it don't support -trace option. So i sent this
patch after confirming this with qemu-nbd,qemu-io utilities.

> with getopt_long() (where double is required) or like
> getopt_long_only() (where the double is optional but supported).
> 
> So I'm in favor of this patch, although it may need more of a commit
> message summarizing the justification I've just pointed you to.

Thanks for your nice explaination. If this patch could be merged i will
send V2 with a commit message.

> 
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks.

> 
> -- 
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.           +1-919-301-3266
> Virtualization:  qemu.org | libvirt.org