README

   1 $Id: README,v 1.11 2007/08/23 09:36:04 rjones Exp $
   2
   3 ocaml-libvirt
   4 ----------------------------------------------------------------------
   5
   6 Copyright (C) 2007 Richard W.M. Jones, Red Hat Inc.
   7 http://et.redhat.com/~rjones/ocaml-libvirt/
   8 http://libvirt.org/
   9
  10 This is a complete set of OCaml bindings around libvirt, exposing all
  11 known functionality to OCaml programs.
  12
  13
  14 Requirements
  15 ----------------------------------------------------------------------
  16
  17 To build the bindings and mlvirsh (required):
  18
  19   GNU make, gcc
  20   libvirt >= 0.2.1 (from http://libvirt.org/,
  21                     get the latest version if you can)
  22   ocaml >= 3.08 (from http://caml.inria.fr/)
  23   findlib (from http://www.ocaml-programming.de/packages/)
  24   Extlib (from http://ocaml-lib.sourceforge.net/)
  25
  26 To build the OCaml interface documentation (optional):
  27
  28   ocamldoc (part of OCaml itself)
  29
  30 To build virt-top (optional):
  31
  32   ocaml-curses (from http://www.nongnu.org/ocaml-tmk/)
  33   xml-light (from http://tech.motion-twin.com/doc/xml-light/)
  34   ocaml CSV library (from http://merjis.com/developers/csv)
  35
  36   [Only ocaml-curses is required for building virt-top.  The other
  37   packages are not required, but you will get reduced functionality].
  38
  39 To build mlvirtmanager (optional):
  40
  41   GTK2 (from http://gtk.org/)
  42   lablgtk2 (from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html)
  43
  44 To build the manpages (optional):
  45
  46   perldoc (part of Perl)
  47
  48 OCaml packages are available for Fedora 7 and above (ocaml,
  49 ocaml-findlib, ocaml-findlib-devel, ocaml-ocamldoc, ocaml-extlib,
  50 ocaml-extlib-devel, ocaml-lablgtk, ocaml-lablgtk-devel, ocaml-curses,
  51 ocaml-xml-light, ocaml-csv).
  52
  53   http://www.annexia.org/tmp/ocaml/
  54   http://fedoraproject.org/wiki/SIGs/OCaml
  55
  56 Debian/Ubuntu have all the packages you require.
  57
  58
  59 Building
  60 ----------------------------------------------------------------------
  61
  62   ./configure           # Checks that you have all the required bits.
  63
  64   make all              # Builds the bytecode version of libs/programs.
  65   make opt              # Builds the native code version of libs/programs.
  66
  67   make install          # Install in OCaml directory, and the binaries
  68                         # in $prefix/bin.
  69
  70   make doc              # Build HTML documentation in html/ subdirectory.
  71
  72 Then have a look at the programs 'mlvirsh.opt' and 'mlvirtmanager.opt'.
  73
  74 Note: If you want to run the programs without first installing, you
  75 may need to set your $LD_LIBRARY_PATH environment variable so it
  76 contains the build directory.  eg:
  77
  78   LD_LIBRARY_PATH=libvirt/ mlvirsh/mlvirsh.opt
  79
  80
  81 mlvirsh
  82 ----------------------------------------------------------------------
  83
  84 'mlvirsh' is an almost complete reimplementation of virsh, which is
  85 mostly command compatible (there are a very few commands missing, and
  86 some commands have a slightly different syntax, but broadly speaking
  87 they are equivalent programs except that one is written in C and the
  88 other in OCaml).
  89
  90 At the time of writing:
  91
  92               wc -c  wc -l
  93
  94   virsh     126,056  4,641
  95   mlvirsh    19,427    598
  96
  97   % size        15%    13%
  98
  99
 100 mlvirtmanager
 101 ----------------------------------------------------------------------
 102
 103 'mlvirtmanager' is a demonstration implementation of virt-manager in
 104 OCaml.  It is not feature-complete by any means, but does allow you to
 105 show the running domains and start and stop defined domains.  The main
 106 functionality _missing_ is the ability to define new virtual machines,
 107 change the resources allocated to domains, or show the machine
 108 console.
 109
 110
 111 Programming
 112 ----------------------------------------------------------------------
 113
 114 The interface is described in 'libvirt.mli'.  The main modules are
 115 Libvirt.Connect, Libvirt.Domain and Libvirt.Network, corresponding
 116 respectively to the virConnect*, virDomain*, and virNetwork*
 117 functions.  For brevity I usually rename these modules like this:
 118
 119   module C = Libvirt.Connect
 120   module D = Libvirt.Domain
 121   module N = Libvirt.Network
 122
 123 To get a connection handle, do:
 124
 125   let name = "xen:///"
 126   let conn = C.connect ~name ()
 127
 128 To list domains, do:
 129
 130   let n = C.num_of_domains conn
 131   let ids = C.list_domains conn n
 132   let domains = Array.map (D.lookup_by_id conn) ids
 133   let () =
 134     Array.iter (
 135       fun dom ->
 136         printf "%5d %s\n" (D.get_id dom) (D.get_name dom)
 137     ) domains
 138
 139 (See also the program list_domains.ml).
 140
 141 For documentation on these bindings, read libvirt.mli and/or 'make
 142 doc' and browse the HTML documentation in the html/ subdirectory.
 143
 144 For documentation on libvirt itself, see http://libvirt.org/html/
 145
 146
 147 Subdirectories
 148 ----------------------------------------------------------------------
 149
 150 libvirt/                The OCaml bindings.
 151 examples/               Some example programs using the bindings.
 152 mlvirsh/                'mlvirsh' command line tool.
 153 mlvirtmanager/          'mlvirtmanager' graphical tool.
 154 virt-top/               'virt-top' tool.