X-Git-Url: http://git.annexia.org/?p=virt-top.git;a=blobdiff_plain;f=README;h=7fb972623b8bd5029060659a60ba084a279ec709;hp=3bcaa7ec8e75de9a76a9a667de81d3086e413451;hb=748302caa93af2c412bcd30dad5787a5a24e9af5;hpb=f2bb550da8353a7ab11d487b947ed702aa9a838f diff --git a/README b/README old mode 100755 new mode 100644 index 3bcaa7e..7fb9726 --- a/README +++ b/README @@ -1,7 +1,7 @@ ocaml-libvirt ---------------------------------------------------------------------- -Copyright (C) 2007 Richard W.M. Jones, Red Hat Inc. +Copyright (C) 2007-2008 Richard W.M. Jones, Red Hat Inc. http://libvirt.org/ocaml/ http://libvirt.org/ @@ -12,55 +12,136 @@ known functionality to OCaml programs. Requirements ---------------------------------------------------------------------- -To build the bindings, examples, 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/) - -Optional, but highly recommended: - - findlib (from http://www.ocaml-programming.de/packages/) - -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/) - Extlib (from http://ocaml-lib.sourceforge.net/) - xml-light (from http://tech.motion-twin.com/doc/xml-light/) - ocaml CSV library (from http://merjis.com/developers/csv) - ocaml-calendar (http://www.lri.fr/~signoles/prog.en.html) - - [Only ocaml-curses and Extlib are 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) - -To build a Windows installer (optional): - - NSIS (http://nsis.sf.net) - -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. +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 |virt-df |Windows + |examples, |manpages | | | |version + |mlvirsh | | | | | + --------------+----------+---------+---------+----------+----------+------ + GNU make | R | R | R | R | R | R + | | | | | | + gcc | R | | R | R | R | R + | | | | | | + libvirt | R | | R | R | R | R + | >= 0.2.1 | | | | | + | | | | | | + ocaml | R | | R | R | R | R + | >= 3.08 | | | | >= 3.10 | + | | | | | | + findlib | HR | R | HR | HR | HR | Note [1] + | | | | | | + ocaml-gettext | O | O | O | O | O | Note [2] + | | | | | | + MinGW + MSYS | | | | | | R + --------------+----------+---------+---------+----------+----------+------ + ocamldoc | | R | | | | O + | | | | | | + perldoc | | O | | | | + --------------+----------+---------+---------+----------+----------+------ + ocaml-curses | | | R | | | + | | | | | | + Extlib | | | R | | R | + | | | | | | + xml-light | | | O | | R | + | | | | | | + ocaml-calendar| | | O | | | + | | | | | | + ocaml CSV | | | O | | | + | | | | | | + bitmatch | | | | | R | + --------------+----------+---------+---------+----------+----------+------ + 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 + +Note [1]: Findlib was recently ported to Windows and in future we may +require it because it will let us remove a lot of hacks from the +Makefiles. + +Note [2]: It's not clear if ocaml-gettext works on Windows. + +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' + + ocaml-gettext from http://www.le-gall.net/sylvain+violaine/ocaml-gettext.html + + patch for OCaml 3.10: + http://www.annexia.org/tmp/ocaml-gettext-0.2.0-20080321.patch + (This should appear in ocaml-gettext 0.3.0 shortly). + + 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' + + bitmatch from http://et.redhat.com/~rjones/bitmatch/ + + 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 @@ -76,7 +157,8 @@ Building make doc # Build HTML documentation in html/ subdirectory. -Then have a look at the programs 'mlvirsh.opt' and 'mlvirtmanager.opt'. +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 @@ -88,9 +170,25 @@ contains the build directory. eg: Windows ---------------------------------------------------------------------- -I have built libvirt (the bindings), examples, mlvirsh and -mlvirtmanager 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. +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: @@ -122,47 +220,20 @@ At the time of writing: % size 15% 13% -mlvirtmanager +virt-ctrl ---------------------------------------------------------------------- -'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. +'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 ---------------------------------------------------------------------- -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. @@ -175,5 +246,6 @@ Subdirectories libvirt/ The OCaml bindings. examples/ Some example programs using the bindings. mlvirsh/ 'mlvirsh' command line tool. -mlvirtmanager/ 'mlvirtmanager' graphical tool. +virt-ctrl/ 'virt-ctrl' graphical tool. virt-top/ 'virt-top' tool. +virt-df/ 'virt-df' tool.