[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCH 0/4] generate SYNTAX section of "virsh help CMD" output



This started when I noticed that a lot of virsh help output was
out of date.  Dan Berrange suggested to generate the SYNTAX line
automatically based on existing option descriptions, since they tell us
what arguments/types each command accepts and can (usually) tell us when
options or arguments are optional.

Doing this exposed several inaccurate SYNTAX lines,
as well as some inaccurate option descriptions.  But since
the option description structs are currently used only
to generate the text of ./virsh help's OPTIONS section,
it's not terribly important.

Other than changes to help output, this change induces some
minor user-visible changes:

It is currently undocumented that virsh accepts "-h C1 C2 C3..."
and treats it like "virsh help C1", ignoring C2 C3...

This change disables that feature (to clean up a few interfaces and to
make automatic help SYNTAX generation simpler) and makes virsh diagnose
any unused arguments with --help (-h), so now, this command fails rather
than trying to interpret "A" as a command:

  $ virsh -h -c test:///default A
  virsh: error: extra argument 'A'. See --help.

To view the other changes induced by this patch, I've run the
following commands:

  v='virsh -c test:///default'
  cmd=$(eval $v help|sed -n 's/^    \([^ ][^ ]*\) .*/\1/p')
  for i in $(echo $cmd); do
    diff -ubBw -L $i.orig -L $i.new <(eval $v help $i) <(eval ./$v help $i)
  done

They use diff to compare e.g., the output of my just-built ./virsh
and the installed-in-PATH "virsh" program.

Note that there is currently no way via options to indicate that one
of two or more options must be selected, so the automatically generated
syntax string list both as independent options.

Here are the induced help changes:
[code diffs coming in separate messages]

--- attach-disk.orig
+++ attach-disk.new
@@ -2,7 +2,7 @@
     attach-disk - attach disk device

   SYNOPSIS
-    attach-disk <domain> <source> <target> [--driver <driver>] [--subdriver <subdriver>] [--type <type>] [--mode <mode>]
+    attach-disk <domain> <source> <target> [--driver <string>] [--subdriver <string>] [--type <string>] [--mode <string>]

   DESCRIPTION
     Attach new disk device.
@@ -11,9 +11,9 @@
     <domain>         domain name, id or uuid
     <source>         source of disk device
     <target>         target of disk device
-    <driver>         driver of disk device
-    <subdriver>      subdriver of disk device
-    <type>           target device type
-    <mode>           mode of device reading and writing
+    --driver <string>  driver of disk device
+    --subdriver <string>  subdriver of disk device
+    --type <string>  target device type
+    --mode <string>  mode of device reading and writing


--- attach-interface.orig
+++ attach-interface.new
@@ -2,7 +2,7 @@
     attach-interface - attach network interface

   SYNOPSIS
-    attach-interface <domain> <type> <source> [--target <target>] [--mac <mac>] [--script <script>]
+    attach-interface <domain> <type> <source> [<target>] [<mac>] [<script>]

   DESCRIPTION
     Attach new network interface.
--- autostart.orig
+++ autostart.new
@@ -2,7 +2,7 @@
     autostart - autostart a domain

   SYNOPSIS
-    autostart [--disable] <domain>
+    autostart <domain> [--disable]

   DESCRIPTION
     Configure a domain to be automatically started at boot.
--- connect.orig
+++ connect.new
@@ -2,7 +2,7 @@
     connect - (re)connect to hypervisor

   SYNOPSIS
-    connect [name] [--readonly]
+    connect [<name>] [--readonly]

   DESCRIPTION
     Connect to local hypervisor. This is built-in command after shell start up.
--- create.orig
+++ create.new
@@ -2,7 +2,7 @@
     create - create a domain from an XML file

   SYNOPSIS
-    create a domain from an XML <file>
+    create <file>

   DESCRIPTION
     Create a domain.
--- start.orig
+++ start.new
@@ -8,6 +8,6 @@
     Start a domain.

   OPTIONS
-    <name>           name of the inactive domain
+    <domain>         name of the inactive domain


--- detach-interface.orig
+++ detach-interface.new
@@ -2,7 +2,7 @@
     detach-interface - detach network interface

   SYNOPSIS
-    detach-interface <domain> <type> [--mac <mac>]
+    detach-interface <domain> <type> [--mac <string>]

   DESCRIPTION
     Detach network interface.
@@ -10,6 +10,6 @@
   OPTIONS
     <domain>         domain name, id or uuid
     <type>           network interface type
-    <mac>            MAC address
+    --mac <string>   MAC address


--- define.orig
+++ define.new
@@ -2,7 +2,7 @@
     define - define (but don't start) a domain from an XML file

   SYNOPSIS
-    define a domain from an XML <file>
+    define <file>

   DESCRIPTION
     Define a domain.
--- domblkstat.orig
+++ domblkstat.new
@@ -2,7 +2,7 @@
     domblkstat - get device block stats for a domain

   SYNOPSIS
-    domblkstat <domain> <dev>
+    domblkstat <domain> <device>

   DESCRIPTION
     Get device block stats for a running domain.
--- domifstat.orig
+++ domifstat.new
@@ -2,7 +2,7 @@
     domifstat - get network interface stats for a domain

   SYNOPSIS
-    domifstat <domain> <dev>
+    domifstat <domain> <interface>

   DESCRIPTION
     Get network interface stats for a running domain.
--- find-storage-pool-sources.orig
+++ find-storage-pool-sources.new
@@ -2,7 +2,7 @@
     find-storage-pool-sources - discover potential storage pool sources

   SYNOPSIS
-    find-storage-pool-sources <type> [srcSpec]
+    find-storage-pool-sources <type> [<srcSpec>]

   DESCRIPTION
     Returns XML <sources> document.
--- find-storage-pool-sources-as.orig
+++ find-storage-pool-sources-as.new
@@ -2,7 +2,7 @@
     find-storage-pool-sources-as - find potential storage pool sources

   SYNOPSIS
-    find-storage-pool-sources-as <type> [options]
+    find-storage-pool-sources-as <type> [<host>] [<port>]

   DESCRIPTION
     Returns XML <sources> document.
--- list.orig
+++ list.new
@@ -2,7 +2,7 @@
     list - list domains

   SYNOPSIS
-    list [--inactive | --all]
+    list [--inactive] [--all]

   DESCRIPTION
     Returns list of domains.
--- migrate.orig
+++ migrate.new
@@ -2,7 +2,7 @@
     migrate - migrate domain to another host

   SYNOPSIS
-    migrate [--live] <domain> <desturi> [<migrateuri>]
+    migrate [--live] <domain> <desturi> [<migrateuri>] [<dname>]

   DESCRIPTION
     Migrate domain to another host.  Add --live for live migration.
--- net-autostart.orig
+++ net-autostart.new
@@ -2,7 +2,7 @@
     net-autostart - autostart a network

   SYNOPSIS
-    net-autostart [--disable] <network>
+    net-autostart <network> [--disable]

   DESCRIPTION
     Configure a network to be automatically started at boot.
--- net-list.orig
+++ net-list.new
@@ -2,7 +2,7 @@
     net-list - list networks

   SYNOPSIS
-    net-list [ --inactive | --all ]
+    net-list [--inactive] [--all]

   DESCRIPTION
     Returns list of networks.
--- net-start.orig
+++ net-start.new
@@ -2,7 +2,7 @@
     net-start - start a (previously defined) inactive network

   SYNOPSIS
-    net-start <network>
+    net-start <name>

   DESCRIPTION
     Start a network.
--- nodedev-list.orig
+++ nodedev-list.new
@@ -2,7 +2,7 @@
     nodedev-list - enumerate devices on this host

   SYNOPSIS
-    nodedev-list [--cap <capability>]
+    nodedev-list [--cap <string>]

   OPTIONS
     --cap <string>   capability name
--- pool-autostart.orig
+++ pool-autostart.new
@@ -2,7 +2,7 @@
     pool-autostart - autostart a pool

   SYNOPSIS
-    pool-autostart [--disable] <pool>
+    pool-autostart <pool> [--disable]

   DESCRIPTION
     Configure a pool to be automatically started at boot.
--- pool-create-as.orig
+++ pool-create-as.new
@@ -2,7 +2,7 @@
     pool-create-as - create a pool from a set of args

   SYNOPSIS
-    pool-create-as <name> <type>
+    pool-create-as <name> <type> [<source-host>] [<source-path>] [<source-dev>] [<target>]

   DESCRIPTION
     Create a pool.
--- pool-define-as.orig
+++ pool-define-as.new
@@ -2,7 +2,7 @@
     pool-define-as - define a pool from a set of args

   SYNOPSIS
-    pool-define-as <name> <type>
+    pool-define-as <name> <type> [<source-host>] [<source-path>] [<source-dev>] [<source-name>] [<target>]

   DESCRIPTION
     Define a pool.
--- pool-edit.orig
+++ pool-edit.new
@@ -2,7 +2,7 @@
     pool-edit - edit XML configuration for a storage pool

   SYNOPSIS
-    pool-edit <domain>
+    pool-edit <pool>

   DESCRIPTION
     Edit the XML configuration for a storage pool.
--- pool-list.orig
+++ pool-list.new
@@ -2,7 +2,7 @@
     pool-list - list pools

   SYNOPSIS
-    pool-list [ --inactive | --all ]
+    pool-list [--inactive] [--all]

   DESCRIPTION
     Returns list of pools.
--- pool-start.orig
+++ pool-start.new
@@ -8,6 +8,6 @@
     Start a pool.

   OPTIONS
-    <name>           name of the inactive pool
+    <pool>           name of the inactive pool


--- restore.orig
+++ restore.new
@@ -2,7 +2,7 @@
     restore - restore a domain from a saved state in a file

   SYNOPSIS
-    restore a domain from <file>
+    restore <file>

   DESCRIPTION
     Restore a domain.
--- schedinfo.orig
+++ schedinfo.new
@@ -2,7 +2,7 @@
     schedinfo - show/set scheduler parameters

   SYNOPSIS
-    schedinfo <domain>
+    schedinfo <domain> [--set <string>] [--weight <number>] [--cap <number>]

   DESCRIPTION
     Show/Set scheduler parameters.
--- vol-create.orig
+++ vol-create.new
@@ -2,7 +2,7 @@
     vol-create - create a vol from an XML file

   SYNOPSIS
-    vol-create <file>
+    vol-create <pool> <file>

   DESCRIPTION
     Create a vol.
--- vol-create-as.orig
+++ vol-create-as.new
@@ -2,7 +2,7 @@
     vol-create-as - create a volume from a set of args

   SYNOPSIS
-    vol-create-as <pool> <name> <capacity>
+    vol-create-as <pool> <name> <capacity> [--allocation <string>] [--format <string>]

   DESCRIPTION
     Create a vol.
@@ -11,7 +11,7 @@
     <pool>           pool name
     <name>           name of the volume
     <capacity>       size of the vol with optional k,M,G,T suffix
-    <allocation>     initial allocation size with optional k,M,G,T suffix
-    <format>         file format type raw,bochs,qcow,qcow2,vmdk
+    --allocation <string>  initial allocation size with optional k,M,G,T suffix
+    --format <string>  file format type raw,bochs,qcow,qcow2,vmdk


--- vol-delete.orig
+++ vol-delete.new
@@ -2,7 +2,7 @@
     vol-delete - delete a vol

   SYNOPSIS
-    vol-delete <vol>
+    vol-delete [--pool <string>] <vol>

   DESCRIPTION
     Delete a given vol.
--- vol-dumpxml.orig
+++ vol-dumpxml.new
@@ -2,7 +2,7 @@
     vol-dumpxml - vol information in XML

   SYNOPSIS
-    vol-dumpxml <vol>
+    vol-dumpxml [--pool <string>] <vol>

   DESCRIPTION
     Output the vol information as an XML dump to stdout.
--- vol-info.orig
+++ vol-info.new
@@ -2,7 +2,7 @@
     vol-info - storage vol information

   SYNOPSIS
-    vol-info <vol>
+    vol-info [--pool <string>] <vol>

   DESCRIPTION
     Returns basic information about the storage vol.
--- vol-path.orig
+++ vol-path.new
@@ -2,7 +2,7 @@
     vol-path - convert a vol UUID to vol path

   SYNOPSIS
-    vol-path <pool> <vol>
+    vol-path [--pool <string>] <vol>

   OPTIONS
     --pool <string>  pool name or uuid


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]