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 PLEASE NOTE: The list of requirements looks long but you DO NOT NEED
  16 all of these packages, so pay careful attention to what is required
  17 ('R') and what is optional ('O').
  18
  19 ALSO NOTE: Binaries are available for many platforms.  You only need
  20 the packages below if you want to build from source.
  21
  22                     W h a t   y o u   w a n t   t o   b u i l d
  23
  24                 |Bindings, |Docs,    |virt-top |virt-ctrl |Windows
  25                 |examples, |manpages |         |          |version
  26                 |mlvirsh   |         |         |          |
  27   --------------+----------+---------+---------+----------+---------
  28   GNU make      | R        | R       | R       | R        | R
  29                 |          |         |         |          |
  30   gcc           | R        |         | R       | R        | R
  31                 |          |         |         |          |
  32   libvirt       | R        |         | R       | R        | R
  33                 | >= 0.2.1 |         |         |          |
  34                 |          |         |         |          |
  35   ocaml         | R        |         | R       | R        | R
  36                 | >= 3.08  |         |         |          |
  37                 |          |         |         |          |
  38   findlib       | HR       | R       | HR      | HR       | n/a
  39                 |          |         |         |          |
  40   MinGW + MSYS  |          |         |         |          | R
  41   --------------+----------+---------+---------+----------+---------
  42   ocamldoc      |          | R       |         |          | O
  43                 |          |         |         |          |
  44   perldoc       |          | O       |         |          |
  45   --------------+----------+---------+---------+----------+---------
  46   ocaml-curses  |          |         | R       |          |
  47                 |          |         |         |          |
  48   Extlib        |          |         | R       |          |
  49                 |          |         |         |          |
  50   xml-light     |          |         | O       |          |
  51                 |          |         |         |          |
  52   ocaml-calendar|          |         | O       |          |
  53                 |          |         |         |          |
  54   ocaml CSV     |          |         | O       |          |
  55   --------------+----------+---------+---------+----------+---------
  56   GTK2          |          |         |         | R        | O
  57                 |          |         |         |          |
  58   lablgtk2      |          |         |         | R        | O
  59                 |          |         |         | >= 2.10.0|
  60   ocaml-dbus    |          |         |         | O        |
  61                 |          |         |         | >= 0.06  |
  62   gnome-icon-theme         |         |         | O        |
  63   --------------+----------+---------+---------+----------+---------
  64   NSIS          |          |         |         |          | O
  65   --------------+----------+---------+---------+----------+---------
  66
  67    R = required
  68    HR = highly recommended (use if possible)
  69    O = optional (just improves functionality, but not required)
  70    n/a = not available
  71
  72 Where to get the packages:
  73
  74   libvirt >= 0.2.1 from http://libvirt.org/ (get the latest version available)
  75                      or packaged in Debian, Ubuntu and Fedora
  76
  77   ocaml >= 3.08    from http://caml.inria.fr/
  78                      or packaged in Debian, Ubuntu and Fedora
  79
  80   findlib          from http://www.ocaml-programming.de/packages/
  81                      or packaged in Debian, Ubuntu and Fedora as 'ocaml-findlib'
  82
  83   MinGW + MSYS     from http://www.mingw.org/ (only needed for Windows)
  84
  85   ocamldoc         part of OCaml itself
  86                      or part of the ocaml package in Debian, Ubuntu
  87                      or packaged in Fedora as 'ocaml-ocamldoc'
  88
  89   perldoc          part of Perl
  90                      or packaged in Debian, Ubuntu and Fedora
  91
  92   ocaml-curses     from http://www.nongnu.org/ocaml-tmk/
  93                      or packaged in Debian, Ubuntu as 'libcurses-ocaml-dev'
  94                      or packaged in Fedora as 'ocaml-curses-devel'
  95
  96   Extlib           from http://ocaml-lib.sourceforge.net/
  97                      or packaged in Debian, Unbuntu as 'libextlib-ocaml-dev'
  98                      or packaged in Fedora as 'ocaml-extlib-devel'
  99
 100   xml-light        from http://tech.motion-twin.com/doc/xml-light/
 101                      or packaged in Debian, Ubuntu as 'libxml-light-ocaml-dev'
 102                      or packaged in Fedora as 'ocaml-xml-light-devel'
 103
 104   ocaml CSV        from http://merjis.com/developers/csv
 105                      or packaged in Debian, Ubuntu as 'libcsv-ocaml-dev'
 106                      or packaged in Fedora as 'ocaml-csv-devel'
 107
 108   ocaml-calendar   from http://www.lri.fr/~signoles/prog.en.html
 109                      or packaged in Debian, Ubuntu as 'libcalendar-ocaml-dev'
 110                      or packaged in Fedora as 'ocaml-calendar-devel'
 111
 112   GTK2             from http://gtk.org/
 113                      or packaged in Debian, Ubuntu and Fedora
 114
 115   lablgtk2 >= 2.10.0
 116                    from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html
 117                      or packaged in Debian, Ubuntu as 'liblablgtk2-ocaml-dev'
 118                      or packaged in Fedora 9 as 'ocaml-lablgtk-devel'
 119
 120   gnome-icon-theme part of GNOME
 121
 122   ocaml-dbus >= 0.06
 123                    from http://tab.snarc.org/projects/ocaml_dbus/
 124                      or packaged in Fedora 9 as 'ocaml-dbus-devel'
 125                      (not yet available for Debian or Ubuntu AFAIK)
 126
 127   NSIS             from http://nsis.sf.net
 128
 129
 130 Building
 131 ----------------------------------------------------------------------
 132
 133   ./configure           # Checks that you have all the required bits.
 134
 135   make all              # Builds the bytecode version of libs/programs.
 136   make opt              # Builds the native code version of libs/programs.
 137
 138   make install          # Install in OCaml directory, and the binaries
 139                         # in $prefix/bin.
 140
 141   make doc              # Build HTML documentation in html/ subdirectory.
 142
 143 Then have a look at the programs 'mlvirsh.opt', 'virt-top.opt'
 144 and 'virt-ctrl.opt'.
 145
 146 Note: If you want to run the programs without first installing, you
 147 may need to set your $LD_LIBRARY_PATH environment variable so it
 148 contains the build directory.  eg:
 149
 150   LD_LIBRARY_PATH=libvirt/ mlvirsh/mlvirsh.opt
 151
 152
 153 Windows
 154 ----------------------------------------------------------------------
 155
 156 I have built libvirt (the bindings), examples, mlvirsh and virt-ctrl
 157 on Windows using the MinGW port of OCaml.  It's quite likely that it
 158 will also work under VC++, but I have not tested this.
 159
 160 You should make sure that your $PATH (environment variable) contains
 161 the names of the directories containing all required DLLs, in
 162 particular you will require:
 163
 164   libvirt-*.dll         (from libvirt)
 165   libgnutls-*.dll       (from GnuTLS)
 166   libgcrypt-*.dll
 167   libgpg-error-*.dll
 168   libtasn1-*.dll
 169   libxdr.dll            (from libxdr)
 170   libxml2-*.dll         (from libxml2)
 171   and, a multitude of DLLs from GTK if you want to run virt-ctrl
 172
 173 You can use a tool such as Dependency Walker to find/check the
 174 locations of dependent libraries.
 175
 176 To build the Windows installer, you will need NSIS.  Then do:
 177
 178   ./configure --with-nsis=/c/Progra~1/NSIS
 179   make all opt
 180   make wininstaller
 181
 182 This should build a Windows binary installer called
 183 ocaml-libvirt-$VERSION.exe which includes the bindings, all required
 184 DLLs and all programs that can be built under Windows.
 185
 186
 187 mlvirsh
 188 ----------------------------------------------------------------------
 189
 190 'mlvirsh' is an almost complete reimplementation of virsh, which is
 191 mostly command compatible (there are a very few commands missing, and
 192 some commands have a slightly different syntax, but broadly speaking
 193 they are equivalent programs except that one is written in C and the
 194 other in OCaml).
 195
 196 At the time of writing:
 197
 198               wc -c  wc -l
 199
 200   virsh     126,056  4,641
 201   mlvirsh    19,427    598
 202
 203   % size        15%    13%
 204
 205
 206 virt-ctrl
 207 ----------------------------------------------------------------------
 208
 209 'virt-ctrl' (originally called 'mlvirtmanager') is a reimplementation
 210 of virt-manager in OCaml.  It is not feature-complete by any means,
 211 but does allow you to show the running domains and start and stop
 212 defined domains.  The main functionality _missing_ is the ability to
 213 define new virtual machines, change the resources allocated to
 214 domains, or show the machine console.
 215
 216
 217 Programming
 218 ----------------------------------------------------------------------
 219
 220 For documentation on these bindings, read libvirt.mli and/or 'make
 221 doc' and browse the HTML documentation in the html/ subdirectory.
 222
 223 For documentation on libvirt itself, see http://libvirt.org/html/
 224
 225
 226 Subdirectories
 227 ----------------------------------------------------------------------
 228
 229 libvirt/                The OCaml bindings.
 230 examples/               Some example programs using the bindings.
 231 mlvirsh/                'mlvirsh' command line tool.
 232 virt-ctrl/              'virt-ctrl' graphical tool.
 233 virt-top/               'virt-top' tool.
 234 virt-df/                'virt-df' tool.