HACKING

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