[Qemu-devel] [PATCH for-2.10 0/3] Improved --version/--help tweaks

[Qemu-devel] [PATCH for-2.10 0/3] Improved --version/--help tweaks

[Eric Blake]

Consistently letting --help point users back to the full resources
of the project is a good idea.  Also enhance some --version outputs.

Eric Blake (3):
  qemu-io: Give more --version information
  qga: Give more --version information
  maint: Include bug-reporting info in --help output.

 include/qemu-common.h | 5 +++++
 vl.c                  | 4 +++-
 bsd-user/main.c       | 2 ++
 linux-user/main.c     | 4 +++-
 qemu-img.c            | 2 +-
 qemu-io.c             | 9 ++++++---
 qemu-nbd.c            | 2 +-
 qga/main.c            | 8 +++++---
 8 files changed, 26 insertions(+), 10 deletions(-)

-- 
2.13.3

[Qemu-devel] [PATCH 1/3] qemu-io: Give more --version information

[Eric Blake]

Include the package version information (useful for detecting
builds from git or downstream backports), and the copyright notice.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 qemu-io.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/qemu-io.c b/qemu-io.c
index 4cfa41c8f9..ec175630a6 100644
--- a/qemu-io.c
+++ b/qemu-io.c
@@ -26,6 +26,7 @@
 #include "block/block_int.h"
 #include "trace/control.h"
 #include "crypto/init.h"
+#include "qemu-version.h"

 #define CMD_NOFILE_OK   0x01

@@ -522,7 +523,8 @@ int main(int argc, char **argv)
             trace_file = trace_opt_parse(optarg);
             break;
         case 'V':
-            printf("%s version %s\n", progname, QEMU_VERSION);
+            printf("%s version " QEMU_VERSION QEMU_PKGVERSION "\n"
+                   QEMU_COPYRIGHT "\n", progname);
             exit(0);
         case 'h':
             usage(progname);
-- 
2.13.3

[Qemu-devel] [PATCH 2/3] qga: Give more --version information

[Eric Blake]

Include the package version information (useful for detecting
builds from git or downstream backports), and the copyright notice.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 qga/main.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/qga/main.c b/qga/main.c
index 1b381d0bf3..b64c7ac2a2 100644
--- a/qga/main.c
+++ b/qga/main.c
@@ -29,6 +29,7 @@
 #include "qemu/help_option.h"
 #include "qemu/sockets.h"
 #include "qemu/systemd.h"
+#include "qemu-version.h"
 #ifdef _WIN32
 #include "qga/service-win32.h"
 #include "qga/vss-win32.h"
@@ -213,7 +214,8 @@ static void usage(const char *cmd)
 {
     printf(
 "Usage: %s [-m <method> -p <path>] [<options>]\n"
-"QEMU Guest Agent %s\n"
+"QEMU Guest Agent " QEMU_VERSION QEMU_PKGVERSION "\n"
+QEMU_COPYRIGHT "\n"
 "\n"
 "  -m, --method      transport method: one of unix-listen, virtio-serial,\n"
 "                    isa-serial, or vsock-listen (virtio-serial is the default)\n"
@@ -248,7 +250,7 @@ static void usage(const char *cmd)
 "  -h, --help        display this help and exit\n"
 "\n"
 "Report bugs to <mdroth@linux.vnet.ibm.com>\n"
-    , cmd, QEMU_VERSION, QGA_VIRTIO_PATH_DEFAULT, QGA_SERIAL_PATH_DEFAULT,
+    , cmd, QGA_VIRTIO_PATH_DEFAULT, QGA_SERIAL_PATH_DEFAULT,
     dfl_pathnames.pidfile,
 #ifdef CONFIG_FSFREEZE
     QGA_FSFREEZE_HOOK_DEFAULT,
-- 
2.13.3

[Qemu-devel] [PATCH 3/3] maint: Include bug-reporting info in --help output.

[Eric Blake]

These days, many programs are including a bug-reporting address,
or better yet, a link to the project web site, at the tail of
their --help output.  However, we were not very consistent at
doing so: only qemu-nbd and qemu-qa mentioned anything, with the
latter pointing to an individual person instead of the project.

Add a new #define that sets up a uniform string, mentioning both
bug reporting instructions and overall project details, and which
a downstream vendor could tweak if they want bugs to go to a
downstream database.  Then use it in all of our binaries which
have --help output.

The canned text intentionally references http:// instead of https://
because our https website currently causes certificate errors in
some browsers.  That can be tweaked later once we have resolved the
web site issued.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 include/qemu-common.h | 5 +++++
 vl.c                  | 4 +++-
 bsd-user/main.c       | 2 ++
 linux-user/main.c     | 4 +++-
 qemu-img.c            | 2 +-
 qemu-io.c             | 5 +++--
 qemu-nbd.c            | 2 +-
 qga/main.c            | 2 +-
 8 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/include/qemu-common.h b/include/qemu-common.h
index b5adbfa5e9..e751361458 100644
--- a/include/qemu-common.h
+++ b/include/qemu-common.h
@@ -22,6 +22,11 @@
 #define QEMU_COPYRIGHT "Copyright (c) 2003-2017 " \
     "Fabrice Bellard and the QEMU Project developers"

+/* Bug reporting information for --help arguments, About dialogs, etc */
+#define QEMU_BUGREPORTS \
+    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \
+    "More information on the qemu project at <http://qemu.org>"
+
 /* main function, renamed */
 #if defined(CONFIG_COCOA)
 int qemu_main(int argc, char **argv, char **envp);
diff --git a/vl.c b/vl.c
index fb6b2efafa..b824f81f64 100644
--- a/vl.c
+++ b/vl.c
@@ -1942,7 +1942,9 @@ static void help(int exitcode)
            "ctrl-alt-n      switch to virtual console 'n'\n"
            "ctrl-alt        toggle mouse and keyboard grab\n"
            "\n"
-           "When using -nographic, press 'ctrl-a h' to get some help.\n");
+           "When using -nographic, press 'ctrl-a h' to get some help.\n"
+           "\n"
+           QEMU_BUGREPORTS "\n");

     exit(exitcode);
 }
diff --git a/bsd-user/main.c b/bsd-user/main.c
index 501e16f675..4db10cb376 100644
--- a/bsd-user/main.c
+++ b/bsd-user/main.c
@@ -686,6 +686,8 @@ static void usage(void)
            "    -E var1=val2 -E var2=val2 -U LD_PRELOAD -U LD_DEBUG\n"
            "Note that if you provide several changes to single variable\n"
            "last change will stay in effect.\n"
+           "\n"
+           QEMU_BUGREPORTS "\n"
            ,
            TARGET_NAME,
            interp_prefix,
diff --git a/linux-user/main.c b/linux-user/main.c
index 2b38d39d87..7d6e481277 100644
--- a/linux-user/main.c
+++ b/linux-user/main.c
@@ -4136,7 +4136,9 @@ static void usage(int exitcode)
            "    -E var1=val2,var2=val2 -U LD_PRELOAD,LD_DEBUG\n"
            "    QEMU_SET_ENV=var1=val2,var2=val2 QEMU_UNSET_ENV=LD_PRELOAD,LD_DEBUG\n"
            "Note that if you provide several changes to a single variable\n"
-           "the last change will stay in effect.\n");
+           "the last change will stay in effect.\n"
+           "\n"
+           QEMU_BUGREPORTS "\n");

     exit(exitcode);
 }
diff --git a/qemu-img.c b/qemu-img.c
index f4d5f0d77d..758719e083 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -201,7 +201,7 @@ static void QEMU_NORETURN help(void)

     printf("%s\nSupported formats:", help_msg);
     bdrv_iterate_format(format_print, NULL);
-    printf("\n");
+    printf("\n\n" QEMU_BUGREPORTS "\n");
     exit(EXIT_SUCCESS);
 }

diff --git a/qemu-io.c b/qemu-io.c
index ec175630a6..b93553a603 100644
--- a/qemu-io.c
+++ b/qemu-io.c
@@ -262,8 +262,9 @@ static void usage(const char *name)
 "  -h, --help           display this help and exit\n"
 "  -V, --version        output version information and exit\n"
 "\n"
-"See '%s -c help' for information on available commands."
-"\n",
+"See '%s -c help' for information on available commands.\n"
+"\n"
+QEMU_BUGREPORTS "\n",
     name, name);
 }

diff --git a/qemu-nbd.c b/qemu-nbd.c
index b8666bb575..052eb4d067 100644
--- a/qemu-nbd.c
+++ b/qemu-nbd.c
@@ -123,7 +123,7 @@ static void usage(const char *name)
 "      --detect-zeroes=MODE  set detect-zeroes mode (off, on, unmap)\n"
 "      --image-opts          treat FILE as a full set of image options\n"
 "\n"
-"Report bugs to <qemu-devel@nongnu.org>\n"
+QEMU_BUGREPORTS "\n"
     , name, NBD_DEFAULT_PORT, "DEVICE");
 }

diff --git a/qga/main.c b/qga/main.c
index b64c7ac2a2..56d5633c13 100644
--- a/qga/main.c
+++ b/qga/main.c
@@ -249,7 +249,7 @@ QEMU_COPYRIGHT "\n"
 "                    options / command-line parameters to stdout\n"
 "  -h, --help        display this help and exit\n"
 "\n"
-"Report bugs to <mdroth@linux.vnet.ibm.com>\n"
+QEMU_BUGREPORTS "\n"
     , cmd, QGA_VIRTIO_PATH_DEFAULT, QGA_SERIAL_PATH_DEFAULT,
     dfl_pathnames.pidfile,
 #ifdef CONFIG_FSFREEZE
-- 
2.13.3

Re: [Qemu-devel] [PATCH 3/3] maint: Include bug-reporting info in --help output.

[Peter Maydell]

On 26 July 2017 at 15:02, Eric Blake <eblake@redhat.com> wrote:
> These days, many programs are including a bug-reporting address,
> or better yet, a link to the project web site, at the tail of
> their --help output.  However, we were not very consistent at
> doing so: only qemu-nbd and qemu-qa mentioned anything, with the
> latter pointing to an individual person instead of the project.
>
> Add a new #define that sets up a uniform string, mentioning both
> bug reporting instructions and overall project details, and which
> a downstream vendor could tweak if they want bugs to go to a
> downstream database.  Then use it in all of our binaries which
> have --help output.
>
> The canned text intentionally references http:// instead of https://
> because our https website currently causes certificate errors in
> some browsers.  That can be tweaked later once we have resolved the
> web site issued.
>
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  include/qemu-common.h | 5 +++++
>  vl.c                  | 4 +++-
>  bsd-user/main.c       | 2 ++
>  linux-user/main.c     | 4 +++-
>  qemu-img.c            | 2 +-
>  qemu-io.c             | 5 +++--
>  qemu-nbd.c            | 2 +-
>  qga/main.c            | 2 +-
>  8 files changed, 19 insertions(+), 7 deletions(-)
>
> diff --git a/include/qemu-common.h b/include/qemu-common.h
> index b5adbfa5e9..e751361458 100644
> --- a/include/qemu-common.h
> +++ b/include/qemu-common.h
> @@ -22,6 +22,11 @@
>  #define QEMU_COPYRIGHT "Copyright (c) 2003-2017 " \
>      "Fabrice Bellard and the QEMU Project developers"
>
> +/* Bug reporting information for --help arguments, About dialogs, etc */
> +#define QEMU_BUGREPORTS \
> +    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \
> +    "More information on the qemu project at <http://qemu.org>"

QEMU should be all upper case.

> +

I wonder if we may regret the embedded newline when
we come to handling UI about dialogs. I guess we
can cross that bridge when we come to it (they
may need to special case it anyway if they want
to make the links clicky).

thanks
-- PMM

Re: [Qemu-devel] [PATCH 3/3] maint: Include bug-reporting info in --help output.

[Eric Blake]

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

On 07/26/2017 09:10 AM, Peter Maydell wrote:
> On 26 July 2017 at 15:02, Eric Blake <eblake@redhat.com> wrote:
>> These days, many programs are including a bug-reporting address,
>> or better yet, a link to the project web site, at the tail of
>> their --help output.  However, we were not very consistent at
>> doing so: only qemu-nbd and qemu-qa mentioned anything, with the
>> latter pointing to an individual person instead of the project.
>>

>>
>> +/* Bug reporting information for --help arguments, About dialogs, etc */
>> +#define QEMU_BUGREPORTS \
>> +    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \
>> +    "More information on the qemu project at <http://qemu.org>"
> 
> QEMU should be all upper case.

Will fix.  While at it, it looks weird that one sentence ends in '.' but
not the other; I omitted it on the second on the chance that it might
interfere with terminals that are able to auto-click the link, but in
testing, at least Gnome's terminal manages just fine thanks to the <>
bracketing.

> 
>> +
> 
> I wonder if we may regret the embedded newline when
> we come to handling UI about dialogs. I guess we
> can cross that bridge when we come to it (they
> may need to special case it anyway if they want
> to make the links clicky).

ui/cocoa.m appears to be the only UI expression version information in a
GUI (which I have no way to test); the GTK window that I get for
'./x86_64-softmmu/qemu-system-x86_64' didn't have anything in its
menubar.  Perhaps it should, but I'm not a gui guy, so I'll leave that
patch for someone with more experience.

Also, I hit this warning:

$ ./x86_64-softmmu/qemu-system-x86_64

(qemu-system-x86_64:19518): Gtk-WARNING **: Allocating size to
GtkScrollbar 0x556c628be340 without calling
gtk_widget_get_preferred_width/height(). How does the code know the size
to allocate?

(qemu-system-x86_64:19518): Gtk-WARNING **: gtk_widget_size_allocate():
attempt to allocate widget with width -426186808 and height 400

I have no idea where it's coming from (that is, whether it is a bug in
the gtk stack of Fedora 26, or whether it is the fault of qemu itself
misusing the preferred dance of gtk calls), but again that's something
that I would rather leave to a programmer more familiar with gui issues
(you can tell I usually test './x86_64-softmmu/qemu-system-x86_64
-nodefaults --nographic -qmp stdio')

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 3/3] maint: Include bug-reporting info in --help output.

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> These days, many programs are including a bug-reporting address,
> or better yet, a link to the project web site, at the tail of
> their --help output.  However, we were not very consistent at
> doing so: only qemu-nbd and qemu-qa mentioned anything, with the
> latter pointing to an individual person instead of the project.
>
> Add a new #define that sets up a uniform string, mentioning both
> bug reporting instructions and overall project details, and which
> a downstream vendor could tweak if they want bugs to go to a
> downstream database.  Then use it in all of our binaries which
> have --help output.
>
> The canned text intentionally references http:// instead of https://
> because our https website currently causes certificate errors in
> some browsers.  That can be tweaked later once we have resolved the
> web site issued.
>
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  include/qemu-common.h | 5 +++++
>  vl.c                  | 4 +++-
>  bsd-user/main.c       | 2 ++
>  linux-user/main.c     | 4 +++-
>  qemu-img.c            | 2 +-
>  qemu-io.c             | 5 +++--
>  qemu-nbd.c            | 2 +-
>  qga/main.c            | 2 +-
>  8 files changed, 19 insertions(+), 7 deletions(-)
>
> diff --git a/include/qemu-common.h b/include/qemu-common.h
> index b5adbfa5e9..e751361458 100644
> --- a/include/qemu-common.h
> +++ b/include/qemu-common.h
> @@ -22,6 +22,11 @@
>  #define QEMU_COPYRIGHT "Copyright (c) 2003-2017 " \
>      "Fabrice Bellard and the QEMU Project developers"
>
> +/* Bug reporting information for --help arguments, About dialogs, etc */
> +#define QEMU_BUGREPORTS \
> +    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \

"See ... for bug reports" sounds like it's about browsing existing bugs.
The web page is actually about reporting bugs.  What about "for how to
report bugs"?

Since I'm basically bikeshedding already: the macro expands into more
than just bug reporting.  Call it QEMU_HELP_BOTTOM?  Feel free to ignore
this one.

> +    "More information on the qemu project at <http://qemu.org>"

"QEMU project"

> +
>  /* main function, renamed */
>  #if defined(CONFIG_COCOA)
>  int qemu_main(int argc, char **argv, char **envp);

Getting late for 2.10, but it's such a lovely little improvement...

Re: [Qemu-devel] [PATCH 3/3] maint: Include bug-reporting info in --help output.

[Paolo Bonzini]

On 08/08/2017 13:06, Markus Armbruster wrote:
> Eric Blake <eblake@redhat.com> writes:
> 
>> These days, many programs are including a bug-reporting address,
>> or better yet, a link to the project web site, at the tail of
>> their --help output.  However, we were not very consistent at
>> doing so: only qemu-nbd and qemu-qa mentioned anything, with the
>> latter pointing to an individual person instead of the project.
>>
>> Add a new #define that sets up a uniform string, mentioning both
>> bug reporting instructions and overall project details, and which
>> a downstream vendor could tweak if they want bugs to go to a
>> downstream database.  Then use it in all of our binaries which
>> have --help output.
>>
>> The canned text intentionally references http:// instead of https://
>> because our https website currently causes certificate errors in
>> some browsers.  That can be tweaked later once we have resolved the
>> web site issued.
>>
>> Signed-off-by: Eric Blake <eblake@redhat.com>
>> ---
>>  include/qemu-common.h | 5 +++++
>>  vl.c                  | 4 +++-
>>  bsd-user/main.c       | 2 ++
>>  linux-user/main.c     | 4 +++-
>>  qemu-img.c            | 2 +-
>>  qemu-io.c             | 5 +++--
>>  qemu-nbd.c            | 2 +-
>>  qga/main.c            | 2 +-
>>  8 files changed, 19 insertions(+), 7 deletions(-)
>>
>> diff --git a/include/qemu-common.h b/include/qemu-common.h
>> index b5adbfa5e9..e751361458 100644
>> --- a/include/qemu-common.h
>> +++ b/include/qemu-common.h
>> @@ -22,6 +22,11 @@
>>  #define QEMU_COPYRIGHT "Copyright (c) 2003-2017 " \
>>      "Fabrice Bellard and the QEMU Project developers"
>>
>> +/* Bug reporting information for --help arguments, About dialogs, etc */
>> +#define QEMU_BUGREPORTS \
>> +    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \
> 
> "See ... for bug reports" sounds like it's about browsing existing bugs.
> The web page is actually about reporting bugs.  What about "for how to
> report bugs"?
> 
> Since I'm basically bikeshedding already: the macro expands into more
> than just bug reporting.  Call it QEMU_HELP_BOTTOM?  Feel free to ignore
> this one.

Easily squashed:

diff --git a/bsd-user/main.c b/bsd-user/main.c
index 4db10cb376..8a6706a1c8 100644
--- a/bsd-user/main.c
+++ b/bsd-user/main.c
@@ -687,7 +687,7 @@ static void usage(void)
            "Note that if you provide several changes to single variable\n"
            "last change will stay in effect.\n"
            "\n"
-           QEMU_BUGREPORTS "\n"
+           QEMU_HELP_BOTTOM "\n"
            ,
            TARGET_NAME,
            interp_prefix,
diff --git a/include/qemu-common.h b/include/qemu-common.h
index d29045631f..0456c79df4 100644
--- a/include/qemu-common.h
+++ b/include/qemu-common.h
@@ -23,8 +23,8 @@
     "Fabrice Bellard and the QEMU Project developers"
 
 /* Bug reporting information for --help arguments, About dialogs, etc */
-#define QEMU_BUGREPORTS \
-    "See <http://qemu.org/contribute/report-a-bug> for bug reports.\n" \
+#define QEMU_HELP_BOTTOM \
+    "See <http://qemu.org/contribute/report-a-bug> for how to report bugs.\n" \
     "More information on the QEMU project at <http://qemu.org>."
 
 /* main function, renamed */
diff --git a/linux-user/main.c b/linux-user/main.c
index 7d6e481277..03666ef657 100644
--- a/linux-user/main.c
+++ b/linux-user/main.c
@@ -4138,7 +4138,7 @@ static void usage(int exitcode)
            "Note that if you provide several changes to a single variable\n"
            "the last change will stay in effect.\n"
            "\n"
-           QEMU_BUGREPORTS "\n");
+           QEMU_HELP_BOTTOM "\n");
 
     exit(exitcode);
 }
diff --git a/qemu-img.c b/qemu-img.c
index 758719e083..56ef49e214 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -201,7 +201,7 @@ static void QEMU_NORETURN help(void)
 
     printf("%s\nSupported formats:", help_msg);
     bdrv_iterate_format(format_print, NULL);
-    printf("\n\n" QEMU_BUGREPORTS "\n");
+    printf("\n\n" QEMU_HELP_BOTTOM "\n");
     exit(EXIT_SUCCESS);
 }
 
diff --git a/qemu-io.c b/qemu-io.c
index b93553a603..265445ad89 100644
--- a/qemu-io.c
+++ b/qemu-io.c
@@ -264,7 +264,7 @@ static void usage(const char *name)
 "\n"
 "See '%s -c help' for information on available commands.\n"
 "\n"
-QEMU_BUGREPORTS "\n",
+QEMU_HELP_BOTTOM "\n",
     name, name);
 }
 
diff --git a/qemu-nbd.c b/qemu-nbd.c
index 052eb4d067..27164b8205 100644
--- a/qemu-nbd.c
+++ b/qemu-nbd.c
@@ -123,7 +123,7 @@ static void usage(const char *name)
 "      --detect-zeroes=MODE  set detect-zeroes mode (off, on, unmap)\n"
 "      --image-opts          treat FILE as a full set of image options\n"
 "\n"
-QEMU_BUGREPORTS "\n"
+QEMU_HELP_BOTTOM "\n"
     , name, NBD_DEFAULT_PORT, "DEVICE");
 }
 
diff --git a/qga/main.c b/qga/main.c
index 56d5633c13..62a62755bd 100644
--- a/qga/main.c
+++ b/qga/main.c
@@ -249,7 +249,7 @@ QEMU_COPYRIGHT "\n"
 "                    options / command-line parameters to stdout\n"
 "  -h, --help        display this help and exit\n"
 "\n"
-QEMU_BUGREPORTS "\n"
+QEMU_HELP_BOTTOM "\n"
     , cmd, QGA_VIRTIO_PATH_DEFAULT, QGA_SERIAL_PATH_DEFAULT,
     dfl_pathnames.pidfile,
 #ifdef CONFIG_FSFREEZE
diff --git a/vl.c b/vl.c
index 3b53de725c..8e247cc2a2 100644
--- a/vl.c
+++ b/vl.c
@@ -1944,7 +1944,7 @@ static void help(int exitcode)
            "\n"
            "When using -nographic, press 'ctrl-a h' to get some help.\n"
            "\n"
-           QEMU_BUGREPORTS "\n");
+           QEMU_HELP_BOTTOM "\n");
 
     exit(exitcode);
 }

>> +    "More information on the qemu project at <http://qemu.org>"
> 
> "QEMU project"

This one is already fixed in the next version of the patchset.

Paolo

>> +
>>  /* main function, renamed */
>>  #if defined(CONFIG_COCOA)
>>  int qemu_main(int argc, char **argv, char **envp);
> 
> Getting late for 2.10, but it's such a lovely little improvement...
>