README

   1 ocaml-libvirt
   2 ----------------------------------------------------------------------
   3
   4 Copyright (C) 2007-2008 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, examples, and mlvirsh (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
  22 Optional, but highly recommended:
  23
  24   findlib (from http://www.ocaml-programming.de/packages/)
  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   Extlib (from http://ocaml-lib.sourceforge.net/)
  34   xml-light (from http://tech.motion-twin.com/doc/xml-light/)
  35   ocaml CSV library (from http://merjis.com/developers/csv)
  36   ocaml-calendar (http://www.lri.fr/~signoles/prog.en.html)
  37
  38   [Only ocaml-curses and Extlib are required for building virt-top.
  39   The other packages are not required, but you will get reduced
  40   functionality].
  41
  42 To build virt-ctrl (optional):
  43
  44   GTK2 (from http://gtk.org/)
  45   lablgtk2 (from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html)
  46
  47 To build the manpages (optional):
  48
  49   perldoc (part of Perl)
  50
  51 To build a Windows installer (optional):
  52
  53   NSIS (http://nsis.sf.net)
  54
  55 OCaml packages are available for Fedora 7 and above (ocaml,
  56 ocaml-findlib, ocaml-findlib-devel, ocaml-ocamldoc, ocaml-extlib,
  57 ocaml-extlib-devel, ocaml-lablgtk, ocaml-lablgtk-devel, ocaml-curses,
  58 ocaml-xml-light, ocaml-csv).
  59
  60   http://www.annexia.org/tmp/ocaml/
  61   http://fedoraproject.org/wiki/SIGs/OCaml
  62
  63 Debian/Ubuntu have all the packages you require.
  64
  65
  66 Building
  67 ----------------------------------------------------------------------
  68
  69   ./configure           # Checks that you have all the required bits.
  70
  71   make all              # Builds the bytecode version of libs/programs.
  72   make opt              # Builds the native code version of libs/programs.
  73
  74   make install          # Install in OCaml directory, and the binaries
  75                         # in $prefix/bin.
  76
  77   make doc              # Build HTML documentation in html/ subdirectory.
  78
  79 Then have a look at the programs 'mlvirsh.opt' and 'virt-ctrl.opt'.
  80
  81 Note: If you want to run the programs without first installing, you
  82 may need to set your $LD_LIBRARY_PATH environment variable so it
  83 contains the build directory.  eg:
  84
  85   LD_LIBRARY_PATH=libvirt/ mlvirsh/mlvirsh.opt
  86
  87
  88 Windows
  89 ----------------------------------------------------------------------
  90
  91 I have built libvirt (the bindings), examples, mlvirsh and virt-ctrl
  92 on Windows using the MinGW port of OCaml.  It's quite likely that it
  93 will also work under VC++, but I have not tested this.
  94
  95 You should make sure that your $PATH (environment variable) contains
  96 the names of the directories containing all required DLLs, in
  97 particular you will require:
  98
  99   libvirt-*.dll         (from libvirt)
 100   libgnutls-*.dll       (from GnuTLS)
 101   libgcrypt-*.dll
 102   libgpg-error-*.dll
 103   libtasn1-*.dll
 104   libxdr.dll            (from libxdr)
 105   libxml2-*.dll         (from libxml2)
 106   and, a multitude of DLLs from GTK if you want to run virt-ctrl
 107
 108 You can use a tool such as Dependency Walker to find/check the
 109 locations of dependent libraries.
 110
 111 To build the Windows installer, you will need NSIS.  Then do:
 112
 113   ./configure --with-nsis=/c/Progra~1/NSIS
 114   make all opt
 115   make wininstaller
 116
 117 This should build a Windows binary installer called
 118 ocaml-libvirt-$VERSION.exe which includes the bindings, all required
 119 DLLs and all programs that can be built under Windows.
 120
 121
 122 mlvirsh
 123 ----------------------------------------------------------------------
 124
 125 'mlvirsh' is an almost complete reimplementation of virsh, which is
 126 mostly command compatible (there are a very few commands missing, and
 127 some commands have a slightly different syntax, but broadly speaking
 128 they are equivalent programs except that one is written in C and the
 129 other in OCaml).
 130
 131 At the time of writing:
 132
 133               wc -c  wc -l
 134
 135   virsh     126,056  4,641
 136   mlvirsh    19,427    598
 137
 138   % size        15%    13%
 139
 140
 141 virt-ctrl
 142 ----------------------------------------------------------------------
 143
 144 'virt-ctrl' (originally called 'mlvirtmanager') is a reimplementation
 145 of virt-manager in OCaml.  It is not feature-complete by any means,
 146 but does allow you to show the running domains and start and stop
 147 defined domains.  The main functionality _missing_ is the ability to
 148 define new virtual machines, change the resources allocated to
 149 domains, or show the machine console.
 150
 151
 152 Programming
 153 ----------------------------------------------------------------------
 154
 155 For documentation on these bindings, read libvirt.mli and/or 'make
 156 doc' and browse the HTML documentation in the html/ subdirectory.
 157
 158 For documentation on libvirt itself, see http://libvirt.org/html/
 159
 160
 161 Subdirectories
 162 ----------------------------------------------------------------------
 163
 164 libvirt/                The OCaml bindings.
 165 examples/               Some example programs using the bindings.
 166 mlvirsh/                'mlvirsh' command line tool.
 167 virt-ctrl/              'virt-ctrl' graphical tool.
 168 virt-top/               'virt-top' tool.
 169 virt-df/                'virt-df' tool.