[Qemu-devel] [PATCH v4 0/3] Improve -help

[Qemu-devel] [PATCH v4 0/3] Improve -help

[Laurent Vivier]

This series allows to only display a given list of help sections
(and fix a typo).

v4: as proposed by Eric, provide a list of sections, restore default -help
v3: add a 2nd patch to add an help section, -help displays only this section
v2: simplify the dance of #define/#undef, thanks to Marc-André.

Laurent Vivier (3):
  vl: Add a flags to define parameters with optional arguments.
  help: fix typo
  Use help sub-sections to create sub-help options

 qemu-options.hx | 122 +++++++++++++++++++++++++++++++++++---
 vl.c            | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 281 insertions(+), 21 deletions(-)

-- 
2.1.0

[Qemu-devel] [PATCH v4 1/3] vl: Add a flags to define parameters with optional arguments.

[Laurent Vivier]

The goal is to be able to use '-help' alone, or with
a sub-section, i.e. '-help network,usb'.

Signed-off-by: Laurent Vivier <lvivier@redhat.com>
---
 vl.c | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/vl.c b/vl.c
index 584ca88..a4fa7e5 100644
--- a/vl.c
+++ b/vl.c
@@ -1932,6 +1932,7 @@ static void help(int exitcode)
 }
 
 #define HAS_ARG 0x0001
+#define IS_OPT  0x0002
 
 typedef struct QEMUOption {
     const char *name;
@@ -2703,12 +2704,21 @@ static const QEMUOption *lookup_opt(int argc, char **argv,
         popt++;
     }
     if (popt->flags & HAS_ARG) {
-        if (optind >= argc) {
-            error_report("requires an argument");
-            exit(1);
+        if (popt->flags & IS_OPT) {
+            if (optind < argc && argv[optind][0] != '-') {
+                optarg = argv[optind++];
+                loc_set_cmdline(argv, optind - 2, 2);
+            } else {
+                optarg = NULL;
+            }
+        } else {
+            if (optind >= argc) {
+                    error_report("requires an argument");
+                    exit(1);
+            }
+            optarg = argv[optind++];
+            loc_set_cmdline(argv, optind - 2, 2);
         }
-        optarg = argv[optind++];
-        loc_set_cmdline(argv, optind - 2, 2);
     } else {
         optarg = NULL;
     }
-- 
2.1.0

[Qemu-devel] [PATCH v4 2/3] help: fix typo

[Laurent Vivier]

Signed-off-by: Laurent Vivier <lvivier@redhat.com>
---
 qemu-options.hx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 77f5853..ab1af02 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3510,7 +3510,7 @@ DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
     "                Output vmstate information in JSON format to file.\n"
     "                Use the scripts/vmstate-static-checker.py file to\n"
     "                check for possible regressions in migration code\n"
-    "                by comparing two such vmstate dumps.",
+    "                by comparing two such vmstate dumps.\n",
     QEMU_ARCH_ALL)
 STEXI
 @item -dump-vmstate @var{file}
-- 
2.1.0

[Qemu-devel] [PATCH v4 3/3] Use help sub-sections to create sub-help options

[Laurent Vivier]

As '-help' output is 400 lines long it is not easy
to find information, but generally we know from
which area we want the information.

As sections already exist in the help description,
add some options to only display the wanted section.

'-help' now can take an optional parameter, which is
a comma separated list of sections to display:

    standard  display standard options
    block     display block options
    usb       display usb options
    display   display display options
    machine   display machine options
    network   display network options
    character display character options
    url       display url options
    bt        display bt options
    tpm       display tpm options
    kernel    display kernel options
    expert    display expert options
    object    display object options

'-help' without option displays all help sections.

Example:

    $ x86_64-softmmu/qemu-system-x86_64 -help kernel,usb
    QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
    usage: qemu-system-x86_64 [options] [disk_image]

    'disk_image' is a raw hard disk image for IDE hard disk 0

    Linux/Multiboot boot specific:
    -kernel bzImage use 'bzImage' as kernel image
    -append cmdline use 'cmdline' as kernel command line
    -initrd file    use 'file' as initial ram disk
    -dtb    file    use 'file' as device tree image

    USB options:
    -usb            enable the USB driver (will be the default soon)
    -usbdevice name add the host or guest USB device 'name'

Signed-off-by: Laurent Vivier <lvivier@redhat.com>
---
 qemu-options.hx | 120 +++++++++++++++++++++++++++++++++++++++---
 vl.c            | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 265 insertions(+), 15 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index ab1af02..ddf71db 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -6,17 +6,76 @@ HXCOMM construct option structures, enums and help message for specified
 HXCOMM architectures.
 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
 
-DEFHEADING(Standard options:)
+#if defined(QEMU_HELP_SELECT_HELP) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_HELP
+DEFHEADING(Help/version options:)
 STEXI
 @table @option
 ETEXI
 
-DEF("help", 0, QEMU_OPTION_h,
-    "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
+DEF("help", HAS_ARG|IS_OPT, QEMU_OPTION_h,
+    "-h|-help [section][,...]\n"
+    "                list help options.\n"
+    "                You can provide the list of sections to display.\n"
+    "                available sections are:\n"
+    "                standard,block,usb,display,machine,network,character,\n"
+    "                url,bt,tpm,kernel,expert,object\n" , QEMU_ARCH_ALL)
 STEXI
-@item -h
+@item -help [section][,...]
 @findex -h
-Display help and exit
+list help options.
+
+You can provide the list of sections to display:
+@table @option
+@item standard
+display standard options
+@item block
+display block options
+@item usb
+display usb options
+@item display
+display display options
+@item machine
+display machine options
+@item network
+display network options
+@item character
+display character options
+@item url
+display url options
+@item bt
+display bt options
+@item tpm
+display tpm options
+@item kernel
+display kernel options
+@item expert
+display expert options
+@item object
+display object options
+@end table
+
+'-help' without option displays all help sections.
+
+@example
+Example:
+    $ x86_64-softmmu/qemu-system-x86_64 -help kernel,usb
+    QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
+    usage: qemu-system-x86_64 [options] [disk_image]
+
+    'disk_image' is a raw hard disk image for IDE hard disk 0
+
+    Linux/Multiboot boot specific:
+    -kernel bzImage use 'bzImage' as kernel image
+    -append cmdline use 'cmdline' as kernel command line
+    -initrd file    use 'file' as initial ram disk
+    -dtb    file    use 'file' as device tree image
+
+    USB options:
+    -usb            enable the USB driver (will be the default soon)
+    -usbdevice name add the host or guest USB device 'name'
+@end example
+
 ETEXI
 
 DEF("version", 0, QEMU_OPTION_version,
@@ -27,6 +86,19 @@ STEXI
 Display version information and exit
 ETEXI
 
+STEXI
+@end table
+ETEXI
+DEFHEADING()
+#endif
+
+#if defined(QEMU_HELP_SELECT_STANDARD) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_STANDARD
+DEFHEADING(Standard options:)
+STEXI
+@table @option
+ETEXI
+
 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
     "-machine [type=]name[,prop[=value][,...]]\n"
     "                selects emulated machine ('-machine help' for list)\n"
@@ -410,7 +482,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_BLOCK) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_BLOCK
 DEFHEADING(Block device options:)
 STEXI
 @table @option
@@ -798,7 +873,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_USB) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_USB
 DEFHEADING(USB options:)
 STEXI
 @table @option
@@ -862,7 +940,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_DISPLAY) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_DISPLAY
 DEFHEADING(Display options:)
 STEXI
 @table @option
@@ -1329,7 +1410,10 @@ STEXI
 @end table
 ETEXI
 ARCHHEADING(, QEMU_ARCH_I386)
+#endif
 
+#if defined(QEMU_HELP_SELECT_MACHINE) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_MACHINE
 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
 STEXI
 @table @option
@@ -1441,7 +1525,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_NETWORK) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_NETWORK
 DEFHEADING(Network options:)
 STEXI
 @table @option
@@ -1995,7 +2082,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_CHARACTER) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_CHARACTER
 DEFHEADING(Character device options:)
 STEXI
 
@@ -2273,7 +2363,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_URL) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_URL
 DEFHEADING(Device URL Syntax:)
 STEXI
 
@@ -2482,7 +2575,10 @@ ETEXI
 STEXI
 @end table
 ETEXI
+#endif
 
+#if defined(QEMU_HELP_SELECT_BT) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_BT
 DEFHEADING(Bluetooth(R) options:)
 STEXI
 @table @option
@@ -2557,7 +2653,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_TPM) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_TPM
 #ifdef CONFIG_TPM
 DEFHEADING(TPM device options:)
 
@@ -2632,7 +2731,10 @@ ETEXI
 DEFHEADING()
 
 #endif
+#endif
 
+#if defined(QEMU_HELP_SELECT_KERNEL) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_KERNEL
 DEFHEADING(Linux/Multiboot boot specific:)
 STEXI
 
@@ -2688,7 +2790,10 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
+#endif
 
+#if defined(QEMU_HELP_SELECT_EXPERT) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_EXPERT
 DEFHEADING(Debug/Expert options:)
 STEXI
 @table @option
@@ -3518,7 +3623,10 @@ STEXI
 Dump json-encoded vmstate information for current machine type to file
 in @var{file}
 ETEXI
+#endif
 
+#if defined(QEMU_HELP_SELECT_OBJECT) || !defined(QEMU_HELP_SELECT)
+#undef QEMU_HELP_SELECT_OBJECT
 DEFHEADING(Generic object creation)
 
 DEF("object", HAS_ARG, QEMU_OPTION_object,
@@ -3571,7 +3679,7 @@ to the RNG daemon.
 @end table
 
 ETEXI
-
+#endif
 
 HXCOMM This is the last statement. Insert new options before this line!
 STEXI
diff --git a/vl.c b/vl.c
index a4fa7e5..3da663f 100644
--- a/vl.c
+++ b/vl.c
@@ -1911,24 +1911,166 @@ static void version(void)
     printf("QEMU emulator version " QEMU_VERSION QEMU_PKGVERSION ", Copyright (c) 2003-2008 Fabrice Bellard\n");
 }
 
-static void help(int exitcode)
+#define QEMU_HELP_SELECT
+static void help_help(void)
 {
+#define QEMU_HELP_SELECT_HELP
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_standard(void)
+{
+#define QEMU_HELP_SELECT_STANDARD
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_block(void)
+{
+#define QEMU_HELP_SELECT_BLOCK
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_usb(void)
+{
+#define QEMU_HELP_SELECT_USB
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_display(void)
+{
+#define QEMU_HELP_SELECT_DISPLAY
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_machine(void)
+{
+#define QEMU_HELP_SELECT_MACHINE
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_network(void)
+{
+#define QEMU_HELP_SELECT_NETWORK
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_character(void)
+{
+#define QEMU_HELP_SELECT_CHARACTER
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_url(void)
+{
+#define QEMU_HELP_SELECT_URL
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_bt(void)
+{
+#define QEMU_HELP_SELECT_BT
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+#ifdef CONFIG_TPM
+static void help_tpm(void)
+{
+#define QEMU_HELP_SELECT_TPM
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+#endif
+static void help_kernel(void)
+{
+#define QEMU_HELP_SELECT_KERNEL
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_expert(void)
+{
+#define QEMU_HELP_SELECT_EXPERT
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+static void help_object(void)
+{
+#define QEMU_HELP_SELECT_OBJECT
+#define QEMU_OPTIONS_GENERATE_HELP
+#include "qemu-options-wrapper.h"
+}
+#undef QEMU_HELP_SELECT
+
+#define SUBHELP(n) { .name = #n, .handler = help_##n }
+typedef struct {
+    const char *name;
+    void (*handler)(void);
+} QEMUHelpOptions;
+
+static QEMUHelpOptions help_handler[] = {
+    SUBHELP(help),
+    SUBHELP(standard),
+    SUBHELP(block),
+    SUBHELP(usb),
+    SUBHELP(display),
+    SUBHELP(machine),
+    SUBHELP(network),
+    SUBHELP(character),
+    SUBHELP(url),
+    SUBHELP(bt),
+#ifdef CONFIG_TPM
+    SUBHELP(tpm),
+#endif
+    SUBHELP(kernel),
+    SUBHELP(expert),
+    SUBHELP(object),
+    { NULL, NULL }
+};
+
+static void help(const char *optarg, int exitcode)
+{
+    const char *p, *e;
+    size_t l;
+    int i;
+
     version();
     printf("usage: %s [options] [disk_image]\n\n"
            "'disk_image' is a raw hard disk image for IDE hard disk 0\n\n",
             error_get_progname());
 
+    if (optarg == NULL) {
 #define QEMU_OPTIONS_GENERATE_HELP
 #include "qemu-options-wrapper.h"
 
-    printf("\nDuring emulation, the following keys are useful:\n"
-           "ctrl-alt-f      toggle full screen\n"
-           "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");
+        printf("\nDuring emulation, the following keys are useful:\n"
+               "ctrl-alt-f      toggle full screen\n"
+               "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");
+
+        exit(exitcode);
+    }
 
-    exit(exitcode);
+    p = optarg;
+    while (*p) {
+        e = strchr(p, ',');
+        l = !e ? strlen(p) : (size_t) (e - p);
+        for (i = 0; help_handler[i].handler; i++) {
+            if (l != strlen(help_handler[i].name)) {
+                continue;
+            }
+            if (strncmp(help_handler[i].name, p, l) == 0) {
+                break;
+            }
+        }
+        if (help_handler[i].handler) {
+            help_handler[i].handler();
+        } else {
+            printf("Unknown help option \"%.*s\"\n", (int)l, p);
+        }
+        p += l + (e != NULL);
+   }
+   exit(exitcode);
 }
 
 #define HAS_ARG 0x0001
@@ -3326,7 +3468,7 @@ int main(int argc, char **argv, char **envp)
                 select_soundhw (optarg);
                 break;
             case QEMU_OPTION_h:
-                help(0);
+                help(optarg, 0);
                 break;
             case QEMU_OPTION_version:
                 version();
-- 
2.1.0

Re: [Qemu-devel] [PATCH v4 2/3] help: fix typo

[Eric Blake]

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

On 09/04/2015 01:30 PM, Laurent Vivier wrote:
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
>  qemu-options.hx | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

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

Subject line might have been more obvious as 'help: add missing newline'

> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 77f5853..ab1af02 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3510,7 +3510,7 @@ DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
>      "                Output vmstate information in JSON format to file.\n"
>      "                Use the scripts/vmstate-static-checker.py file to\n"
>      "                check for possible regressions in migration code\n"
> -    "                by comparing two such vmstate dumps.",
> +    "                by comparing two such vmstate dumps.\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -dump-vmstate @var{file}
> 

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH v4 1/3] vl: Add a flags to define parameters with optional arguments.

[Eric Blake]

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

On 09/04/2015 01:30 PM, Laurent Vivier wrote:
> The goal is to be able to use '-help' alone, or with
> a sub-section, i.e. '-help network,usb'.

Uggh. I hate reinventing the wheel.  We aren't using getopt_long_only();
but if we were, the ONLY way to specify optional arguments to a long
option is by using the = sign, and not by space separation.

That is, '-help=network,usb' would work, but '-help network,usb' would
NOT be seen as arguments to -help.

While I'd really rather we just use getopt_long_only(), that's a much
bigger change.  But we should at least mirror its semantics, because it
is VERY confusing to have subtly different command-line behavior than
most apps out there.

> 
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
>  vl.c | 20 +++++++++++++++-----
>  1 file changed, 15 insertions(+), 5 deletions(-)
> 

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH v4 1/3] vl: Add a flags to define parameters with optional arguments.

[Eric Blake]

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

On 09/04/2015 01:42 PM, Eric Blake wrote:
> On 09/04/2015 01:30 PM, Laurent Vivier wrote:
>> The goal is to be able to use '-help' alone, or with
>> a sub-section, i.e. '-help network,usb'.
> 
> Uggh. I hate reinventing the wheel.  We aren't using getopt_long_only();
> but if we were, the ONLY way to specify optional arguments to a long
> option is by using the = sign, and not by space separation.

Also, we tend to avoid trailing '.' in subject lines.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH v4 1/3] vl: Add a flags to define parameters with optional arguments.

[Stefan Weil]

Am 04.09.2015 um 21:42 schrieb Eric Blake:
> On 09/04/2015 01:30 PM, Laurent Vivier wrote:
>> The goal is to be able to use '-help' alone, or with
>> a sub-section, i.e. '-help network,usb'.
> Uggh. I hate reinventing the wheel.  We aren't using getopt_long_only();
> but if we were, the ONLY way to specify optional arguments to a long
> option is by using the = sign, and not by space separation.
>
> That is, '-help=network,usb' would work, but '-help network,usb' would
> NOT be seen as arguments to -help.
>
> While I'd really rather we just use getopt_long_only(), that's a much
> bigger change.  But we should at least mirror its semantics, because it
> is VERY confusing to have subtly different command-line behavior than
> most apps out there.

Wasn't there a plan for a version jump (QEMU v3) with the next release?

Then we could really go a step towards getopt_long_only
and require options written like --help instead of -help.
Today both variants work, so we would have to remove
support for the -help form.

Stefan

Re: [Qemu-devel] [PATCH v4 1/3] vl: Add a flags to define parameters with optional arguments.

[Eric Blake]

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

On 09/04/2015 01:55 PM, Stefan Weil wrote:
> Am 04.09.2015 um 21:42 schrieb Eric Blake:
>> On 09/04/2015 01:30 PM, Laurent Vivier wrote:
>>> The goal is to be able to use '-help' alone, or with
>>> a sub-section, i.e. '-help network,usb'.
>> Uggh. I hate reinventing the wheel.  We aren't using getopt_long_only();
>> but if we were, the ONLY way to specify optional arguments to a long
>> option is by using the = sign, and not by space separation.
>>
>> That is, '-help=network,usb' would work, but '-help network,usb' would
>> NOT be seen as arguments to -help.
>>
>> While I'd really rather we just use getopt_long_only(), that's a much
>> bigger change.  But we should at least mirror its semantics, because it
>> is VERY confusing to have subtly different command-line behavior than
>> most apps out there.
> 
> Wasn't there a plan for a version jump (QEMU v3) with the next release?

I don't know; but feature-wise, if MTTCG and introspection both land in
the next release, that would be major enough in my book to be worth
naming things 3.0 if people like it.

> 
> Then we could really go a step towards getopt_long_only
> and require options written like --help instead of -help.

getopt_long_only() is an awkward interface. Most apps should use
getopt_long() instead.  What getopt_long_only() does is allow you to use
'-long' or any unambiguous prefix instead of '--long', provided that
'-l' is not a short option.  Note that we have '-h' as an alias for
long-option help, we'd run into fixable issues (since getopt_long_only()
allows unambiguous abbreviations, getting rid of short -h would allow
'-h' to become unambiguous for long option '--help', as long as no other
long option starts with h [oops, we have -hda]; on top of that, you can
also explicitly list '--h' as a long option, which would then make it
take preference over any other substring of a longer name).  So it would
still be possible to switch to getopt_long_only() while still keeping
support for '-help' to work.

Meanwhile, where we'd run into trouble is the fact that '-m' is
different than '-machine'; if we use getopt_long(), then '-machine'
would break.

> Today both variants work, so we would have to remove
> support for the -help form.

Well, even if we don't remove support for '-help', we could at least
update our documentation to mention that '--long' forms already work,
and that they are the favored spelling (as we may want to eventually get
rid of -short forms down the road).  But I agree that gratuitously
breaking existing -short form command lines without ample warning time
is not the right approach to take, and don't know if we have given
enough warning, regardless of whether the next release is named 2.5 or 3.0.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH v4 3/3] Use help sub-sections to create sub-help options

[Eric Blake]

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

On 09/04/2015 01:30 PM, Laurent Vivier wrote:
> As '-help' output is 400 lines long it is not easy
> to find information, but generally we know from
> which area we want the information.
> 
> As sections already exist in the help description,
> add some options to only display the wanted section.
> 
> '-help' now can take an optional parameter, which is
> a comma separated list of sections to display:
> 
>     standard  display standard options
>     block     display block options
>     usb       display usb options
>     display   display display options
>     machine   display machine options
>     network   display network options
>     character display character options
>     url       display url options
>     bt        display bt options
>     tpm       display tpm options
>     kernel    display kernel options
>     expert    display expert options
>     object    display object options
> 
> '-help' without option displays all help sections.

No, that's not quite what I suggested.

-help without options should display AT MOST one screen-ful: start with
the usage: header (I don't know if version information has to stay,
since it is also present in --version, but it doesn't hurt as it is only
one line), and conclude with details about how to get more help.

Or, based on your patch, it should be something like:

> $ qemu-kvm -help
> QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
> usage: qemu-system-x86_64 [options] [disk_image]
> 
> 'disk_image' is a raw hard disk image for IDE hard disk 0
> 
> Help/version options:
> -h|-help [section][,...]
> list help options.
> You can provide the list of sections to display.
> available sections are:
> standard,block,usb,display,machine,network,character,
> url,bt,tpm,kernel,expert,object
> -version display version information and exit
> 
> For full details, try -help=all.

--help=help (or --help=sections, or whatever you name it) could be a
synonym for bare --help.

--help=all should display ALL sections, without having to spell out each
section by name.  And the LAST thing displayed should be the --help=help
section (so I don't have to invoke a pager to see how to limit the
output to the subsections I'm interested in).

--help=LIST for any other comma-separated LIST should produce those
particular sections.  I don't care if you reorder the sections (that is,
if --help=block,usb and --help=usb,block produce the same output, or if
they produce sections in swapped order, is up to you).

> 
>     $ x86_64-softmmu/qemu-system-x86_64 -help kernel,usb

Also, I think you need '=' not ' ' between -help and the list; but other
than that,

>     QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
>     usage: qemu-system-x86_64 [options] [disk_image]
> 
>     'disk_image' is a raw hard disk image for IDE hard disk 0
> 
>     Linux/Multiboot boot specific:
>     -kernel bzImage use 'bzImage' as kernel image
>     -append cmdline use 'cmdline' as kernel command line
>     -initrd file    use 'file' as initial ram disk
>     -dtb    file    use 'file' as device tree image
> 
>     USB options:
>     -usb            enable the USB driver (will be the default soon)
>     -usbdevice name add the host or guest USB device 'name'

this is indeed a nice example of how limiting to subsections can be useful.

> 
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
>  qemu-options.hx | 120 +++++++++++++++++++++++++++++++++++++++---
>  vl.c            | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  2 files changed, 265 insertions(+), 15 deletions(-)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


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

Re: [Qemu-devel] [PATCH v4 2/3] help: fix typo

[Michael Tokarev]

Applied to -trivial, with subject line change as suggested by Eric.
Thanks!

/mjt