HACKING file, update (C) messages.
[virt-top.git] / README
diff --git a/README b/README
index 8ae896e..0e56218 100644 (file)
--- a/README
+++ b/README
-ocaml-libvirt
+virt-top
 ----------------------------------------------------------------------
 
 ----------------------------------------------------------------------
 
-Copyright (C) 2007-2008 Richard W.M. Jones, Red Hat Inc.
+Copyright (C) 2007-2009 Richard W.M. Jones, Red Hat Inc.
+http://et.redhat.com/~rjones/virt-top/
 http://libvirt.org/ocaml/
 http://libvirt.org/
 
 http://libvirt.org/ocaml/
 http://libvirt.org/
 
-This is a complete set of OCaml bindings around libvirt, exposing all
-known functionality to OCaml programs.
+virt-top is a top-like utility for showing stats of virtualized
+domains. Many keys and command line options are the same as for
+ordinary top.
 
 
-
-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
+It uses libvirt so it capable of showing stats across a variety of
+different virtualization systems.
 
 
 Building
 
 
 Building
@@ -132,103 +19,7 @@ Building
 
   ./configure           # Checks that you have all the required bits.
 
 
   ./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
-----------------------------------------------------------------------
+  make all             # Builds the bytecode version of the program.
+  make opt             # Builds the native code version of the program.
 
 
-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.
+Then have a look at the program 'virt-top/virt-top.opt'.