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