HACKING

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