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