[libvirt] [libvirt-designer][PATCH v2] Create manpage for virtxml

Mon Sep 24 15:40:00 UTC 2012

ACK

Christophe

On Thu, Sep 20, 2012 at 04:18:34PM +0200, Michal Privoznik wrote:
> ---
> 
> diff to v1:
> -move content from virtxml.pod to virtxml.c
> -wording and spelling as pointed out by Christophe
> 
>  .gitignore               |    1 +
>  examples/Makefile.am     |    9 +++
>  examples/virtxml.c       |  127 ++++++++++++++++++++++++++++++++++++++++++++++
>  libvirt-designer.spec.in |    1 +
>  4 files changed, 138 insertions(+), 0 deletions(-)
> 
> diff --git a/.gitignore b/.gitignore
> index 4272672..03b75ce 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -52,3 +52,4 @@ docs/*.interfaces
>  docs/*.prerequisites
>  docs/*.signals
>  docs/*.types
> +examples/*.1
> diff --git a/examples/Makefile.am b/examples/Makefile.am
> index 32549a0..ae2667e 100644
> --- a/examples/Makefile.am
> +++ b/examples/Makefile.am
> @@ -18,6 +18,15 @@ virtxml_LDFLAGS = \
>  		$(LIBVIRT_GCONFIG_LIBS) \
>  		$(LIBVIRT_GOBJECT_LIBS)
>  
> +POD2MAN = pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)"
> +
> +%.1: %.c Makefile
> +	$(AM_V_GEN)$(POD2MAN) $< $@
> +
>  if WITH_EXAMPLES
>  bin_PROGRAMS = virtxml
> +
> +man1_MANS = virtxml.1
> +
> +CLEANFILES = $(man1_MANS)
>  endif
> diff --git a/examples/virtxml.c b/examples/virtxml.c
> index c582d0b..2918ee0 100644
> --- a/examples/virtxml.c
> +++ b/examples/virtxml.c
> @@ -606,3 +606,130 @@ cleanup:
>          gvir_connection_close(conn);
>      return ret;
>  }
> +
> +/*
> +=pod
> +
> +
> +=head1 NAME
> +
> +virtxml - Generate domain XML
> +
> +=head1 SYNOPSIS
> +
> +B<virtxml> [I<OPTION>]...
> +
> +=head1 DESCRIPTION
> +
> +B<virtxml> is a command line tool for generating XML documents for
> +libvirt domains. However, it cooperates with libosinfo database to guess
> +the correct combination of attributes (e.g. disk driver, NIC model).
> +
> +B<virtxml> does not feed libvirt with generated XML though. For now,
> +it's a proof of concept.
> +
> +=head1 OPTIONS
> +
> +The basic structure of arguments passed to B<virtxml> is:
> +
> +  virtxml [-c URI] [OPTION] [OPTION] ...
> +
> +However, arguments have no pre-defined order so users can type them
> +in any order they like.
> +
> +=head2 General Options
> +
> +=over 2
> +
> +=item -c URI, --connect=URI
> +
> +The libvirt connection URI which is used for querying capabilities of the
> +host.
> +
> +=item --list-os
> +
> +List IDs of operating systems known to libosinfo
> +
> +=item --list-platform
> +
> +List IDs of platforms known to libosinfo
> +
> +=item -o OS, --os=OS
> +
> +Specify operating system that will be run on the domain. I<OS> is an ID
> +which can be obtained via B<--list-os>.
> +
> +=item -p PLATFORM, --platform=PLATFORM
> +
> +Specify platform (hypervisor) under which the domain will run. I<PLATFORM>
> +is and ID which can be obtained via I<--list-platform>.
> +
> +=item -a ARCH, --architecture=ARCH
> +
> +Set domain's architecture
> +
> +=item -d PATH[,FORMAT] --disk=PATH[,FORMAT]
> +
> +Add I<PATH> as a disk to the domain. To specify its format (e.g. raw,
> +qcow2, phy) use I<FORMAT>.
> +
> +=item -i NETWORK[,ARG=VAL]
> +
> +Add an interface of type network with I<NETWORK> source. Moreover, some
> +other configuration knobs can be set (possible I<ARG>s): I<mac>,
> +I<link>={up|down}
> +
> +=item -r RESOURCE, --resources=RESOURCES
> +
> +Set I<minimal> or I<recommended> resources on the domain XML. By default,
> +the I<recommended> is used.
> +
> +=back
> +
> +Usually, both B<--os> and B<--platform> are required as they are needed to
> +make the right decision on driver, model, ...  when adding a new device.
> +However, when adding a disk which is an installation medium (e.g. a CD-ROM or
> +DVD), B<virtxml> tries to guess the OS. Something similar is done with
> +platform. Usually, the platform is guessed from the connection URI.
> +
> +=head1 EXAMPLES
> +
> +Domain with Fedora 17 from locally stored ISO and one NIC with mac
> +00:11:22:33:44:55 and link set down:
> +
> +  # virtxml -d Fedora-17-x86_64-Live-KDE.iso \
> +            -i default,mac=00:11:22:33:44:55,link=down
> +
> +To add multiple devices just use appropriate argument multiple times:
> +
> +  # virtxml -d /tmp/Fedora-17-x86_64-Live-KDE.iso,raw \
> +            -d /var/lib/libvirt/images/f17.img,qcow2 \
> +            -i default,mac=00:11:22:33:44:55,link=down \
> +            -i blue_network \
> +            -r minimal
> +
> +=head1 AUTHORS
> +
> +Written by Michal Privoznik, Daniel P. Berrange and team of other
> +contributors. See the AUTHORS file in the source distribution for the
> +complete list of credits.
> +
> +=head1 BUGS
> +
> +Report any bugs discovered to the libvirt community via the mailing
> +list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
> +Alternatively report bugs to your software distributor / vendor.
> +
> +=head1 COPYRIGHT
> +
> +Copyright (C) 2012 Red Hat, Inc. and various contributors.
> +This is free software. You may redistribute copies of it under the terms of
> +the GNU General Public License C<http://www.gnu.org/licenses/gpl.html>. There
> +is NO WARRANTY, to the extent permitted by law.
> +
> +=head1 SEE ALSO
> +
> +C<virsh(1)>, C<virt-clone(1)>, C<virt-manager(1)>, the project website C<http://virt-manager.org>
> +
> +=cut
> +*/
> diff --git a/libvirt-designer.spec.in b/libvirt-designer.spec.in
> index 1d5f4b6..ede7185 100644
> --- a/libvirt-designer.spec.in
> +++ b/libvirt-designer.spec.in
> @@ -78,6 +78,7 @@ rm -rf $RPM_BUILD_ROOT
>  %files
>  %defattr(-,root,root,-)
>  %{_bindir}/virtxml
> +%{_mandir}/man1/virtxml.1*
>  
>  %files libs
>  %defattr(-,root,root,-)
> -- 
> 1.7.8.6
> 
> --
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120924/e7a1da89/attachment-0001.sig>