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