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