README

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