HACKING

   1 This file contains some tips for hacking on this code.
   2
   3 General OCaml advice:
   4
   5 (1) The *.mli file describes the interface of the module.  It's a good
   6     idea to look at this file first, then at *.ml (the implementation).
   7
   8 (2) Emacs users: use tuareg-mode for editing OCaml.
   9
  10 (3) http://www.ocaml-tutorial.org/
  11
  12 (4) http://camltastic.blogspot.com/2008/08/3-things-that-will-confuse-you-when.html
  13
  14 The code is structured into these files:
  15
  16   virt_top_utils.mli / virt_top_utils.ml
  17
  18     String functions and other small utility functions.  This is
  19     included directly into virt_top.ml.
  20
  21   virt_top_version.ml
  22
  23     The version number (automatically generated by configure).
  24
  25   virt_top.mli / virt_top.ml
  26
  27     This is the virt-top program.
  28
  29     The two interesting functions are called 'collect' and 'redraw'.
  30
  31     'collect' collects all the information about domains, etc.
  32
  33     'redraw' updates the display on each frame.
  34
  35     Another interesting function is 'start_up' which handles all
  36     start-up stuff, eg. command line arguments, connecting to the
  37     hypervisor, enabling curses.
  38
  39     The function 'main_loop' runs the main loop and has sub-functions
  40     to deal with keypresses, help screens and so on.
  41
  42   virt_top_xml.ml
  43
  44     Any code which needs the optional xml-light library goes
  45     in here.  Mainly for parsing domain XML descriptions to get
  46     the list of block devices and network interfaces.
  47
  48     The reason for having it in a separate file is so that we
  49     don't depend on xml-light.
  50
  51   virt_top_csv.ml
  52
  53     Any code which needs the optional ocaml-csv library goes
  54     in here.  This implements the --csv command line option.
  55
  56   virt_top_calendar1.ml
  57   virt_top_calendar2.ml
  58
  59     Any code which needs the optional ocaml-calendar library
  60     goes in here.  This implements the --end-time command line
  61     option.  Note there are two incompatible versions of the
  62     ocaml-calendar library, which is why we have two
  63     implementations.  The Makefile works out which one to use.
  64
  65   virt_top_gettext.ml
  66
  67     Gettext interaction (this is generated by ./configure).
  68
  69   virt_top_main.ml
  70
  71     This is just a small bit of code to glue the modules above
  72     together.
  73
  74 The man-page is generated from the single file:
  75
  76   virt-top.pod
  77
  78 which generates (using perldoc) the following:
  79
  80   virt-top.1
  81   virt-top.txt