summaryrefslogtreecommitdiffstats
path: root/README
blob: 8ae896e1a1da0021ecbdde16b99214088eab0828 (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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
ocaml-libvirt
----------------------------------------------------------------------

Copyright (C) 2007-2008 Richard W.M. Jones, Red Hat Inc.
http://libvirt.org/ocaml/
http://libvirt.org/

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


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

PLEASE NOTE: The list of requirements looks long but you DO NOT NEED
all of these packages, so pay careful attention to what is required
('R') and what is optional ('O').

ALSO NOTE: Binaries are available for many platforms.  You only need
the packages below if you want to build from source.

                    W h a t   y o u   w a n t   t o   b u i l d

                |Bindings, |Docs,    |virt-top |virt-ctrl |Windows
                |examples, |manpages |         |          |version
                |mlvirsh   |         |         |          |
  --------------+----------+---------+---------+----------+---------
  GNU make      | R        | R       | R       | R        | R
                |          |         |         |          |
  gcc           | R        |         | R       | R        | R
                |          |         |         |          |
  libvirt       | R        |         | R       | R        | R
                | >= 0.2.1 |         |         |          |
                |          |         |         |          |
  ocaml         | R        |         | R       | R        | R
                | >= 3.08  |         |         |          |
                |          |         |         |          |
  findlib       | HR       | R       | HR      | HR       | n/a
                |          |         |         |          |
  MinGW + MSYS  |          |         |         |          | R
  --------------+----------+---------+---------+----------+---------
  ocamldoc      |          | R       |         |          | O
                |          |         |         |          |
  perldoc       |          | O       |         |          |
  --------------+----------+---------+---------+----------+---------
  ocaml-curses  |          |         | R       |          |
                |          |         |         |          |
  Extlib        |          |         | R       |          |
                |          |         |         |          |
  xml-light     |          |         | O       |          |
                |          |         |         |          |
  ocaml-calendar|          |         | O       |          |
                |          |         |         |          |
  ocaml CSV     |          |         | O       |          |
  --------------+----------+---------+---------+----------+---------
  GTK2          |          |         |         | R        | O
                |          |         |         |          |
  lablgtk2      |          |         |         | R        | O
                |          |         |         | >= 2.10.0|
  ocaml-dbus    |          |         |         | O        |
                |          |         |         | >= 0.06  |
  gnome-icon-theme         |         |         | O        |
  --------------+----------+---------+---------+----------+---------
  NSIS          |          |         |         |          | O
  --------------+----------+---------+---------+----------+---------

   R = required
   HR = highly recommended (use if possible)
   O = optional (just improves functionality, but not required)
   n/a = not available

Where to get the packages:

  libvirt >= 0.2.1 from http://libvirt.org/ (get the latest version available)
                     or packaged in Debian, Ubuntu and Fedora

  ocaml >= 3.08    from http://caml.inria.fr/
                     or packaged in Debian, Ubuntu and Fedora

  findlib          from http://www.ocaml-programming.de/packages/
                     or packaged in Debian, Ubuntu and Fedora as 'ocaml-findlib'

  MinGW + MSYS     from http://www.mingw.org/ (only needed for Windows)

  ocamldoc         part of OCaml itself
                     or part of the ocaml package in Debian, Ubuntu
                     or packaged in Fedora as 'ocaml-ocamldoc'

  perldoc          part of Perl
                     or packaged in Debian, Ubuntu and Fedora

  ocaml-curses     from http://www.nongnu.org/ocaml-tmk/
                     or packaged in Debian, Ubuntu as 'libcurses-ocaml-dev'
                     or packaged in Fedora as 'ocaml-curses-devel'

  Extlib           from http://ocaml-lib.sourceforge.net/
                     or packaged in Debian, Unbuntu as 'libextlib-ocaml-dev'
                     or packaged in Fedora as 'ocaml-extlib-devel'

  xml-light        from http://tech.motion-twin.com/doc/xml-light/
                     or packaged in Debian, Ubuntu as 'libxml-light-ocaml-dev'
                     or packaged in Fedora as 'ocaml-xml-light-devel'

  ocaml CSV        from http://merjis.com/developers/csv
                     or packaged in Debian, Ubuntu as 'libcsv-ocaml-dev'
                     or packaged in Fedora as 'ocaml-csv-devel'

  ocaml-calendar   from http://www.lri.fr/~signoles/prog.en.html
                     or packaged in Debian, Ubuntu as 'libcalendar-ocaml-dev'
                     or packaged in Fedora as 'ocaml-calendar-devel'

  GTK2             from http://gtk.org/
                     or packaged in Debian, Ubuntu and Fedora

  lablgtk2 >= 2.10.0
                   from http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html
                     or packaged in Debian, Ubuntu as 'liblablgtk2-ocaml-dev'
                     or packaged in Fedora 9 as 'ocaml-lablgtk-devel'

  gnome-icon-theme part of GNOME

  ocaml-dbus >= 0.06
                   from http://tab.snarc.org/projects/ocaml_dbus/
                     or packaged in Fedora 9 as 'ocaml-dbus-devel'
                     (not yet available for Debian or Ubuntu AFAIK)

  NSIS             from http://nsis.sf.net


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', 'virt-top.opt'
and 'virt-ctrl.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


Windows
----------------------------------------------------------------------

I have built libvirt (the bindings), examples, mlvirsh and virt-ctrl
on Windows using the MinGW port of OCaml.  It's quite likely that it
will also work under VC++, but I have not tested this.

You should make sure that your $PATH (environment variable) contains
the names of the directories containing all required DLLs, in
particular you will require:

  libvirt-*.dll		(from libvirt)
  libgnutls-*.dll	(from GnuTLS)
  libgcrypt-*.dll
  libgpg-error-*.dll
  libtasn1-*.dll
  libxdr.dll		(from libxdr)
  libxml2-*.dll		(from libxml2)
  and, a multitude of DLLs from GTK if you want to run virt-ctrl

You can use a tool such as Dependency Walker to find/check the
locations of dependent libraries.

To build the Windows installer, you will need NSIS.  Then do:

  ./configure --with-nsis=/c/Progra~1/NSIS
  make all opt
  make wininstaller

This should build a Windows binary installer called
ocaml-libvirt-$VERSION.exe which includes the bindings, all required
DLLs and all programs that can be built under Windows.


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%


virt-ctrl
----------------------------------------------------------------------

'virt-ctrl' (originally called 'mlvirtmanager') is a reimplementation
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
----------------------------------------------------------------------

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.
virt-ctrl/		'virt-ctrl' graphical tool.
virt-top/		'virt-top' tool.
virt-df/		'virt-df' tool.