[libvirt] [PATCH v2] Provide a useful README file
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@redhat.com> --- In v2: - Use markdown syntax - Use README.md file - Symlink README to README.md - Include travis build status README | 14 +---------- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 13 deletions(-) mode change 100644 => 120000 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 3d5167d..0000000 --- a/README +++ /dev/null @@ -1,13 +0,0 @@ - - LibVirt : simple API for virtualization - - Libvirt is a C toolkit to interact with the virtualization capabilities -of recent versions of Linux (and other OSes). It is free software -available under the GNU Lesser General Public License. Virtualization of -the Linux Operating System means the ability to run multiple instances of -Operating Systems concurrently on a single hardware system where the basic -resources are driven by a Linux instance. The library aim at providing -long term stable C API initially for the Xen paravirtualization but -should be able to integrate other virtualization mechanisms if needed. - -Daniel Veillard <veillard@redhat.com> diff --git a/README b/README new file mode 120000 index 0000000..42061c0 --- /dev/null +++ b/README @@ -0,0 +1 @@ +README.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c2bd2f8 --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +[](https://travis-ci.org/libvirt/libvirt) + +Libvirt API for virtualization +============================== + +Libvirt provides a portable, long term stable C API for managing the +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. + +For some of these hypervisors, it provides a stateful management +daemon runs on the virtualization host allowing access to the API +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 +mappings into object systems such as GObject, CIM and SNMP. + +Further information about the libvirt project can be found on the +website: + +* <https://libvirt.org> + +License +------- + +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 +Public License, version 2.1 (or later). See the files COPYING.LESSER +and COPYING for full license terms & conditions. + +Installation +------------ + +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 +``` + +While to build & install as an unprivileged user + +``` +# ./configure --prefix=$HOME/usr +# make +# make install +``` + + +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. + +Contributing +------------ + +The libvirt project welcomes contributors from all. For most components +the best way to contributor is to send patches to the primary development +mailing list, using the 'git send-email' command. Further guidance on this +can be found in the HACKING file, or the project website + +* <https://libvirt.org/contribute.html> + +Contact +------- + +The libvirt project has two primary mailing lists: + + * libvir-list@redhat.com (**for development**) + * libvirt-users@redhat.com (**for users**) + +Further details on contacting the project are available on the website + +* <https://libvirt.org/contact.html> -- 2.9.3
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@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/BHyve/bhyve/ s/VMWare/VMware/g 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 ;) s/Php/PHP/ [...]
+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/,// 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
s/normal/usual/
+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.
s/dependancies/dependencies/ [...]
+The libvirt project welcomes contributors from all. For most components +the best way to contributor is to send patches to the primary development
s/contributor/contribute/ 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 font. [...]
+The libvirt project has two primary mailing lists: + + * libvir-list@redhat.com (**for development**) + * libvirt-users@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
On Mon, 2017-05-22 at 14:00 +0200, Andrea Bolognani wrote:
+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.
Of course I meant with a *lowercase* L here :) -- Andrea Bolognani / Red Hat / Virtualization
On Mon, May 22, 2017 at 02:00:01PM +0200, Andrea Bolognani wrote:
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@redhat.com> --- In v2: - Use markdown syntax - Use README.md file
My preference would be to call this README.markdown instead.
While it appears github supports both names, README.md appears more commonly used to me - indeed github's own markup repor uses that name https://github.com/github/markup/blob/master/README.md
[...]
+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.
To me it looks pretty odd to not captialize a word at the start of the sentence. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Mon, 2017-05-22 at 16:17 +0100, Daniel P. Berrange wrote:
My preference would be to call this README.markdown instead. While it appears github supports both names, README.md appears more commonly used to me - indeed github's own markup repor uses that name https://github.com/github/markup/blob/master/README.md
Okay, let's go with the widespread extension then. [...]
To me it looks pretty odd to not captialize a word at the start of the sentence.
To me it looks weird when libvirt is capitalized, but fair enough, it doesn't really matter at the end of the day :) Feel free to CC me when posting a v3 that fixes the typos and includes README.md in the release archive. -- Andrea Bolognani / Red Hat / Virtualization
participants (2)
-
Andrea Bolognani -
Daniel P. Berrange