[libvirt] [PATCH v2] Provide a useful README file

Andrea Bolognani abologna at redhat.com
Mon May 22 12:00:01 UTC 2017

On Tue, 2017-05-16 at 13:29 +0100, Daniel P. Berrange wrote:
> The current README file contents has almost no useful info, and that
> which does exist is very outdated.
> Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> ---
> In v2:
>  - Use markdown syntax
>  - Use README.md file

My preference would be to call this README.markdown instead.

>  - Symlink README to README.md

You didn't add the new file to EXTRA_DIST or similar though,
so the release archives won't include it.

> +Libvirt API for virtualization
> +==============================
> +
> +Libvirt provides a portable, long term stable C API for managing the

I like using "libvirt" with a capital L consistently, even
when it's at the beginning of a sentence. I think there might
be style rules agains it, though.

> +virtualization technologies provided by many operating systems. It
> +includes support for QEMU, KVM, Xen, LXC, BHyve, Virtuozzo, VMWare
> +vCenter and ESX, VMWare Desktop, Hyper-V, VirtualBox and PowerHyp.

s/PowerHyp/PHYP/ or s/PowerHyp/the POWER Hypervisor/

> +For some of these hypervisors, it provides a stateful management
> +daemon runs on the virtualization host allowing access to the API

s/runs/which runs/

> +both by non-privileged local users and remote users.
> +
> +Layered packages provide bindings of the Libvirt C API into other
> +languages including Python, Perl, Php, Go, Java, OCaml, as well as

s/Libvirt/libvirt/   unquestionably here ;)

> +The libvirt C API is distributed under the terms of GNU Lesser General
> +Public License, version 2.1 (or later). Some parts of the code that are
> +not part of the C library, may have the more restricted GNU General

s/restricted/restrictive/ perhaps?

> +Libvirt uses the GNU Autotools build system, so in general can be built
> +and installed with the normal commands. For example, to build in a manner


> +that is suitable for installing as root, use:
> +
> +```
> +# ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
> +# make
> +# sudo make install
> +```

s/#/$/g   to make it clear that all those commands can
          (should) be run as a regular user. Same below

> +The libvirt code relies on a large number of 3rd party libraries. These will
> +be detected during execution of the configure script and a summary printed
> +which lists any missing (optional) dependancies.


> +The libvirt project welcomes contributors from all. For most components
> +the best way to contributor is to send patches to the primary development


The "welcomes contributors from all" parts looks icky, but
I'm unable to come up with a good alternative at the moment.

> +mailing list, using the 'git send-email' command. Further guidance on this
> +can be found in the HACKING file, or the project website

You can use `git send-email` and `HACKING` so that the
resulting document will render those parts using a monospace

> +The libvirt project has two primary mailing lists:
> +
> + * libvir-list at redhat.com (**for development**)
> + * libvirt-users at redhat.com (**for users**)

I think libvirt-users should be first, and I would also change
the comment for libvirt-list to "for development only" to make
the distinction even clearer.

Andrea Bolognani / Red Hat / Virtualization

More information about the libvir-list mailing list