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 In general terms, always start by reading the .mli file (if it exists)
  26 in order to understand the module and before opening the .ml file.
  27
  28 Threads and messages
  29 --------------------
  30
  31 Because libvirt and libguestfs API calls are usually long-running, we
  32 have to use threads, making these API calls in one thread, while
  33 another thread keeps the display updated.  In Guestfs Browser we use
  34 two threads, and send messages between them.  The main thread keeps
  35 the display updated and runs the glib main loop.  The slave thread
  36 issues libvirt and libguestfs API calls serially.  There is a FIFO
  37 queue of commands, from the main thread to the slave thread.  When
  38 each command finishes, a reply is delivered back to the main thread by
  39 adding an idle event to the glib main loop, see:
  40
  41   http://library.gnome.org/devel/gtk-faq/stable/x499.html
  42
  43 If a command fails, it causes the input command queue to be cleared.
  44 In this case a failure response is added to the main loop which causes
  45 some error message to appear in the display.
  46
  47 The main thread cannot directly access the libvirt or libguestfs
  48 handles, but instead it must send messages.  (In older versions of
  49 libvirt, and all versions of libguestfs, these handles were not thread
  50 safe, and in any case we don't want the main thread to block because
  51 it performs some long-running operation by accident).
  52
  53 The slave thread is defined in the Slave module (interface:
  54 'slave.mli') and all slave_* files.  The Slave module also defines
  55 what commands are possible.  Every other module and file is part of
  56 the main thread except for a few utility / library modules.
  57
  58 The main thread starts in the module Main.
  59
  60 Code style
  61 ----------
  62
  63 Most modules alias short names for some common libvirt and libguestfs
  64 modules, eg:
  65
  66   module C = Libvirt.Connect
  67   module G = Guestfs
  68
  69 So when you see a function such as 'C.connect_readonly', it's really
  70 the function 'connect_readonly' in the [nested] module
  71 'Libvirt.Connect'.