HACKING

   1 This document describes the software architecture of the
   2 guestfs-browser, useful if you want to hack on it.
   3
   4 About OCaml
   5 -----------
   6
   7 First of all about OCaml: Read the tutorial and other resources
   8 available from this site:
   9
  10   http://caml.inria.fr/
  11   http://ocaml-tutorial.org/
  12
  13 If you are using emacs, install tuareg-mode instead of using the
  14 built-in emacs mode (which sucks).  vi users have a good built-in
  15 OCaml mode already.
  16
  17 All OCaml packages required are available in all good Linux
  18 distributions, well, Fedora, Debian and Ubuntu anyway.  If you are
  19 using some other distribution, or Mac OS X or Windows, have a look at
  20 GODI.
  21
  22 In OCaml, a module such as 'Slave' is defined by its interface in
  23 'slave.mli' (note lowercase first letter), and its implementation
  24 in 'slave.ml'.
  25
  26 In general terms, always start by reading the .mli file (if it exists)
  27 in order to understand the module and before opening the .ml file.
  28
  29 Threads and messages
  30 --------------------
  31
  32 Because libvirt and libguestfs API calls are usually long-running, we
  33 have to use threads, making these API calls in one thread, while
  34 another thread keeps the display updated.  In guestfs-browser we use
  35 two threads, and send messages between them.  The main thread keeps
  36 the display updated and runs the glib main loop.  The slave thread
  37 issues libvirt and libguestfs API calls serially.  There is a FIFO
  38 queue of commands, from the main thread to the slave thread.  When
  39 each command finishes, a reply is delivered back to the main thread by
  40 adding an idle event to the glib main loop, see:
  41
  42   http://library.gnome.org/devel/gtk-faq/stable/x499.html
  43
  44 If a command fails, it causes the input command queue to be cleared.
  45 In this case a failure response is added to the main loop which causes
  46 some error message to appear in the display.
  47
  48 The main thread cannot directly access the libvirt or libguestfs
  49 handles, but instead it must send messages.  (In older versions of
  50 libvirt, and all versions of libguestfs, these handles were not thread
  51 safe, and in any case we don't want the main thread to block because
  52 it performs some long-running operation by accident).
  53
  54 The slave thread is defined in the Slave module (interface:
  55 'slave.mli') and the slave.ml implementation.  The Slave module also
  56 defines what commands are possible.  Every other module and file is
  57 part of the main thread except for a few utility modules.
  58
  59 The main thread starts in the module Main.
  60
  61 Code style
  62 ----------
  63
  64 Most modules alias short names for some common libvirt and libguestfs
  65 modules, eg:
  66
  67   module C = Libvirt.Connect
  68   module Q = Queue
  69
  70 So when you see a function such as 'C.connect_readonly', it's really
  71 the function 'connect_readonly' in the [nested] module
  72 'Libvirt.Connect'.