I guess it's long overdue at this point, but let's use it to explain how to properly use -query-capabilities.
Signed-off-by: Anthony Liguori <aligu...@us.ibm.com> --- docs/management-tools.md | 31 +++++++++++++++++++++++++++++++ 1 files changed, 31 insertions(+), 0 deletions(-) create mode 100644 docs/management-tools.md diff --git a/docs/management-tools.md b/docs/management-tools.md new file mode 100644 index 0000000..d879e48 --- /dev/null +++ b/docs/management-tools.md @@ -0,0 +1,31 @@ +Writing a QEMU Management Tool +============================== + +This is a guide on writing a QEMU management tool. This document outlines +which interfaces the QEMU project exports and will support long term. + +Specifying options +------------------ + +The preferred way for a management tool to specify options to QEMU is to create +a configuration file and use '-readconfig' on the command line. We prefer this +interface over direct use of command line options because this interface +supports introspection in a machine friendly way. + +Determining if an option is supported +------------------------------------- + +A management tool should use the '-query-capabilities' option to determine what +the capabilities of the current QEMU executable is. The 'config' section of +the resulting JSON object describes all of the config sections that are +currently supported. + +Many options currently fall into the 'system' section and some of these options +have complex syntax. Management tools should assume that these syntaxes will +never change and never be extended. Whenever there is a need to change or +extend this syntax, we will first convert the option to use a stand alone +section. + +While help text is available, the help text *should not* be parsed to attempt to +determine if the option has changed. The help text is exposed merely as a stop +gap to help libvirt transition to this new format. -- 1.7.5.4
