12:24 p.m.
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