This document describes the software architecture of the
guestfs-browser, useful if you want to hack on it.

Patches
-------

Patches should be sent to the virt-tools mailing list:
http://www.redhat.com/mailman/listinfo/virt-tools-list

About OCaml
-----------

First of all about OCaml: Read the tutorial and other resources
available from this site:

  http://caml.inria.fr/
  http://mirror.ocamlcore.org/ocaml-tutorial.org/index.html
  # http://ocaml-tutorial.org/

If you are using emacs, install tuareg-mode instead of using the
built-in emacs mode (which sucks).  vi users have a good built-in
OCaml mode already.

All OCaml packages required are available in all good Linux
distributions, well, Fedora, Debian and Ubuntu anyway.  If you are
using some other distribution, or Mac OS X or Windows, have a look at
GODI.

In OCaml, a module such as 'Slave' is defined by its interface in
'slave.mli' (note lowercase first letter), and its implementation
in 'slave.ml'.

In general terms, always start by reading the .mli file (if it exists)
in order to understand the module and before opening the .ml file.

Threads and messages
--------------------

Because libvirt and libguestfs API calls are usually long-running, we
have to use threads, making these API calls in one thread, while
another thread keeps the display updated.  In guestfs-browser we use
two threads, and send messages between them.  The main thread keeps
the display updated and runs the glib main loop.  The slave thread
issues libvirt and libguestfs API calls serially.  There is a FIFO
queue of commands, from the main thread to the slave thread.  When
each command finishes, a reply is delivered back to the main thread by
adding an idle event to the glib main loop, see:

  http://library.gnome.org/devel/gtk-faq/stable/x499.html

If a command fails, it causes the input command queue to be cleared.
In this case a failure response is added to the main loop which causes
some error message to appear in the display.

The main thread cannot directly access the libvirt or libguestfs
handles, but instead it must send messages.  (In older versions of
libvirt, and all versions of libguestfs, these handles were not thread
safe, and in any case we don't want the main thread to block because
it performs some long-running operation by accident).

The slave thread is defined in the Slave module (interface:
'slave.mli') and the slave.ml implementation.  The Slave module also
defines what commands are possible.  Every other module and file is
part of the main thread except for a few utility modules.

The main thread starts in the module Main.

Code style
----------

Most modules alias short names for some common libvirt and libguestfs
modules, eg:

  module C = Libvirt.Connect
  module G = Guestfs

So when you see a function such as 'C.connect_readonly', it's really
the function 'connect_readonly' in the [nested] module
'Libvirt.Connect'.