HACKING file, update (C) messages.

[virt-top.git] / HACKING

diff --git a/HACKING b/HACKING
new file mode 100644 (file)
index 0000000..bce40a9
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,81 @@
+This file contains some tips for hacking on this code.
+
+General OCaml advice:
+
+(1) The *.mli file describes the interface of the module.  It's a good
+    idea to look at this file first, then at *.ml (the implementation).
+
+(2) Emacs users: use tuareg-mode for editing OCaml.
+
+(3) http://www.ocaml-tutorial.org/
+
+(4) http://camltastic.blogspot.com/2008/08/3-things-that-will-confuse-you-when.html
+
+The code is structured into these files:
+
+  virt_top_utils.mli / virt_top_utils.ml
+
+    String functions and other small utility functions.  This is
+    included directly into virt_top.ml.
+
+  virt_top_version.ml
+
+    The version number (automatically generated by configure).
+
+  virt_top.mli / virt_top.ml
+
+    This is the virt-top program.
+
+    The two interesting functions are called 'collect' and 'redraw'.
+
+    'collect' collects all the information about domains, etc.
+
+    'redraw' updates the display on each frame.
+
+    Another interesting function is 'start_up' which handles all
+    start-up stuff, eg. command line arguments, connecting to the
+    hypervisor, enabling curses.
+
+    The function 'main_loop' runs the main loop and has sub-functions
+    to deal with keypresses, help screens and so on.
+
+  virt_top_xml.ml
+
+    Any code which needs the optional xml-light library goes
+    in here.  Mainly for parsing domain XML descriptions to get
+    the list of block devices and network interfaces.
+
+    The reason for having it in a separate file is so that we
+    don't depend on xml-light.
+
+  virt_top_csv.ml
+
+    Any code which needs the optional ocaml-csv library goes
+    in here.  This implements the --csv command line option.
+
+  virt_top_calendar1.ml
+  virt_top_calendar2.ml
+
+    Any code which needs the optional ocaml-calendar library
+    goes in here.  This implements the --end-time command line
+    option.  Note there are two incompatible versions of the
+    ocaml-calendar library, which is why we have two
+    implementations.  The Makefile works out which one to use.
+
+  virt_top_gettext.ml
+
+    Gettext interaction (this is generated by ./configure).
+
+  virt_top_main.ml
+
+    This is just a small bit of code to glue the modules above
+    together.
+
+The man-page is generated from the single file:
+
+  virt-top.pod
+
+which generates (using perldoc) the following:
+
+  virt-top.1
+  virt-top.txt