summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorrjones@localhost <rjones@localhost>2007-08-30 17:38:09 +0100
committerrjones@localhost <rjones@localhost>2007-08-30 17:38:09 +0100
commita8b837d5018c488a130fcbea425904817a862210 (patch)
tree44fc8f4a58d6e1651053c4c40d32b3816add43fa /README
downloadvirt-top-a8b837d5018c488a130fcbea425904817a862210.zip
virt-top-a8b837d5018c488a130fcbea425904817a862210.tar.gz
virt-top-a8b837d5018c488a130fcbea425904817a862210.tar.xz
Initial import from CVS.
Diffstat (limited to 'README')
-rw-r--r--README154
1 files changed, 154 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..800458d
--- /dev/null
+++ b/README
@@ -0,0 +1,154 @@
+$Id: README,v 1.11 2007/08/23 09:36:04 rjones Exp $
+
+ocaml-libvirt
+----------------------------------------------------------------------
+
+Copyright (C) 2007 Richard W.M. Jones, Red Hat Inc.
+http://et.redhat.com/~rjones/ocaml-libvirt/
+http://libvirt.org/
+
+This is a complete set of OCaml bindings around libvirt, exposing all
+known functionality to OCaml programs.
+
+
+Requirements
+----------------------------------------------------------------------
+
+To build the bindings and mlvirsh (required):
+
+ GNU make, gcc
+ libvirt >= 0.2.1 (from http://libvirt.org/,
+ get the latest version if you can)
+ ocaml >= 3.08 (from http://caml.inria.fr/)
+ findlib (from http://www.ocaml-programming.de/packages/)
+ Extlib (from http://ocaml-lib.sourceforge.net/)
+
+To build the OCaml interface documentation (optional):
+
+ ocamldoc (part of OCaml itself)
+
+To build virt-top (optional):
+
+ ocaml-curses (from http://www.nongnu.org/ocaml-tmk/)
+ xml-light (from http://tech.motion-twin.com/doc/xml-light/)
+ ocaml CSV library (from http://merjis.com/developers/csv)
+
+ [Only ocaml-curses is required for building virt-top. The other
+ packages are not required, but you will get reduced functionality].
+
+To build mlvirtmanager (optional):
+
+ GTK2 (from http://gtk.org/)
+ lablgtk2 (from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html)
+
+To build the manpages (optional):
+
+ perldoc (part of Perl)
+
+OCaml packages are available for Fedora 7 and above (ocaml,
+ocaml-findlib, ocaml-findlib-devel, ocaml-ocamldoc, ocaml-extlib,
+ocaml-extlib-devel, ocaml-lablgtk, ocaml-lablgtk-devel, ocaml-curses,
+ocaml-xml-light, ocaml-csv).
+
+ http://www.annexia.org/tmp/ocaml/
+ http://fedoraproject.org/wiki/SIGs/OCaml
+
+Debian/Ubuntu have all the packages you require.
+
+
+Building
+----------------------------------------------------------------------
+
+ ./configure # Checks that you have all the required bits.
+
+ make all # Builds the bytecode version of libs/programs.
+ make opt # Builds the native code version of libs/programs.
+
+ make install # Install in OCaml directory, and the binaries
+ # in $prefix/bin.
+
+ make doc # Build HTML documentation in html/ subdirectory.
+
+Then have a look at the programs 'mlvirsh.opt' and 'mlvirtmanager.opt'.
+
+Note: If you want to run the programs without first installing, you
+may need to set your $LD_LIBRARY_PATH environment variable so it
+contains the build directory. eg:
+
+ LD_LIBRARY_PATH=libvirt/ mlvirsh/mlvirsh.opt
+
+
+mlvirsh
+----------------------------------------------------------------------
+
+'mlvirsh' is an almost complete reimplementation of virsh, which is
+mostly command compatible (there are a very few commands missing, and
+some commands have a slightly different syntax, but broadly speaking
+they are equivalent programs except that one is written in C and the
+other in OCaml).
+
+At the time of writing:
+
+ wc -c wc -l
+
+ virsh 126,056 4,641
+ mlvirsh 19,427 598
+
+ % size 15% 13%
+
+
+mlvirtmanager
+----------------------------------------------------------------------
+
+'mlvirtmanager' is a demonstration implementation of virt-manager in
+OCaml. It is not feature-complete by any means, but does allow you to
+show the running domains and start and stop defined domains. The main
+functionality _missing_ is the ability to define new virtual machines,
+change the resources allocated to domains, or show the machine
+console.
+
+
+Programming
+----------------------------------------------------------------------
+
+The interface is described in 'libvirt.mli'. The main modules are
+Libvirt.Connect, Libvirt.Domain and Libvirt.Network, corresponding
+respectively to the virConnect*, virDomain*, and virNetwork*
+functions. For brevity I usually rename these modules like this:
+
+ module C = Libvirt.Connect
+ module D = Libvirt.Domain
+ module N = Libvirt.Network
+
+To get a connection handle, do:
+
+ let name = "xen:///"
+ let conn = C.connect ~name ()
+
+To list domains, do:
+
+ let n = C.num_of_domains conn
+ let ids = C.list_domains conn n
+ let domains = Array.map (D.lookup_by_id conn) ids
+ let () =
+ Array.iter (
+ fun dom ->
+ printf "%5d %s\n" (D.get_id dom) (D.get_name dom)
+ ) domains
+
+(See also the program list_domains.ml).
+
+For documentation on these bindings, read libvirt.mli and/or 'make
+doc' and browse the HTML documentation in the html/ subdirectory.
+
+For documentation on libvirt itself, see http://libvirt.org/html/
+
+
+Subdirectories
+----------------------------------------------------------------------
+
+libvirt/ The OCaml bindings.
+examples/ Some example programs using the bindings.
+mlvirsh/ 'mlvirsh' command line tool.
+mlvirtmanager/ 'mlvirtmanager' graphical tool.
+virt-top/ 'virt-top' tool.