summaryrefslogtreecommitdiffstats
path: root/README
blob: 800458d86eb2ca04f94fcae91840d2cd6ebdeb3f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
$Id: README,v 1.11 2007/08/23 09:36:04 rjones Exp $

ocaml-libvirt
----------------------------------------------------------------------

Copyright (C) 2007 Richard W.M. Jones, Red Hat Inc.
http://et.redhat.com/~rjones/ocaml-libvirt/
http://libvirt.org/

This is a complete set of OCaml bindings around libvirt, exposing all
known functionality to OCaml programs.


Requirements
----------------------------------------------------------------------

To build the bindings and mlvirsh (required):

  GNU make, gcc
  libvirt >= 0.2.1 (from http://libvirt.org/,
  	     	    get the latest version if you can)
  ocaml >= 3.08 (from http://caml.inria.fr/)
  findlib (from http://www.ocaml-programming.de/packages/)
  Extlib (from http://ocaml-lib.sourceforge.net/)

To build the OCaml interface documentation (optional):

  ocamldoc (part of OCaml itself)

To build virt-top (optional):

  ocaml-curses (from http://www.nongnu.org/ocaml-tmk/)
  xml-light (from http://tech.motion-twin.com/doc/xml-light/)
  ocaml CSV library (from http://merjis.com/developers/csv)

  [Only ocaml-curses is required for building virt-top.  The other
  packages are not required, but you will get reduced functionality].

To build mlvirtmanager (optional):

  GTK2 (from http://gtk.org/)
  lablgtk2 (from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html)

To build the manpages (optional):

  perldoc (part of Perl)

OCaml packages are available for Fedora 7 and above (ocaml,
ocaml-findlib, ocaml-findlib-devel, ocaml-ocamldoc, ocaml-extlib,
ocaml-extlib-devel, ocaml-lablgtk, ocaml-lablgtk-devel, ocaml-curses,
ocaml-xml-light, ocaml-csv).

  http://www.annexia.org/tmp/ocaml/
  http://fedoraproject.org/wiki/SIGs/OCaml

Debian/Ubuntu have all the packages you require.


Building
----------------------------------------------------------------------

  ./configure           # Checks that you have all the required bits.

  make all		# Builds the bytecode version of libs/programs.
  make opt		# Builds the native code version of libs/programs.

  make install          # Install in OCaml directory, and the binaries
       			# in $prefix/bin.

  make doc              # Build HTML documentation in html/ subdirectory.

Then have a look at the programs 'mlvirsh.opt' and 'mlvirtmanager.opt'.

Note: If you want to run the programs without first installing, you
may need to set your $LD_LIBRARY_PATH environment variable so it
contains the build directory.  eg:

  LD_LIBRARY_PATH=libvirt/ mlvirsh/mlvirsh.opt


mlvirsh
----------------------------------------------------------------------

'mlvirsh' is an almost complete reimplementation of virsh, which is
mostly command compatible (there are a very few commands missing, and
some commands have a slightly different syntax, but broadly speaking
they are equivalent programs except that one is written in C and the
other in OCaml).

At the time of writing:

              wc -c  wc -l

  virsh     126,056  4,641
  mlvirsh    19,427    598

  % size        15%    13%


mlvirtmanager
----------------------------------------------------------------------

'mlvirtmanager' is a demonstration implementation of virt-manager in
OCaml.  It is not feature-complete by any means, but does allow you to
show the running domains and start and stop defined domains.  The main
functionality _missing_ is the ability to define new virtual machines,
change the resources allocated to domains, or show the machine
console.


Programming
----------------------------------------------------------------------

The interface is described in 'libvirt.mli'.  The main modules are
Libvirt.Connect, Libvirt.Domain and Libvirt.Network, corresponding
respectively to the virConnect*, virDomain*, and virNetwork*
functions.  For brevity I usually rename these modules like this:

  module C = Libvirt.Connect
  module D = Libvirt.Domain
  module N = Libvirt.Network

To get a connection handle, do:

  let name = "xen:///"
  let conn = C.connect ~name ()

To list domains, do:

  let n = C.num_of_domains conn
  let ids = C.list_domains conn n
  let domains = Array.map (D.lookup_by_id conn) ids
  let () =
    Array.iter (
      fun dom ->
        printf "%5d %s\n" (D.get_id dom) (D.get_name dom)
    ) domains

(See also the program list_domains.ml).

For documentation on these bindings, read libvirt.mli and/or 'make
doc' and browse the HTML documentation in the html/ subdirectory.

For documentation on libvirt itself, see http://libvirt.org/html/


Subdirectories
----------------------------------------------------------------------

libvirt/		The OCaml bindings.
examples/		Some example programs using the bindings.
mlvirsh/		'mlvirsh' command line tool.
mlvirtmanager/		'mlvirtmanager' graphical tool.
virt-top/		'virt-top' tool.