code.grnet.gr Git - ganeti-local/blob - doc/devnotes.rst

   1 Developer notes
   2 ===============
   3
   4 Build dependencies
   5 ------------------
   6
   7 Most dependencies from :doc:`install-quick`, plus (for Python):
   8
   9 - `GNU make <http://www.gnu.org/software/make/>`_
  10 - `GNU tar <http://www.gnu.org/software/tar/>`_
  11 - `Gzip <http://www.gnu.org/software/gzip/>`_
  12 - `pandoc <http://johnmacfarlane.net/pandoc/>`_
  13 - `python-sphinx <http://sphinx.pocoo.org/>`_
  14   (tested with version 0.6.1)
  15 - `graphviz <http://www.graphviz.org/>`_
  16 - the `en_US.UTF-8` locale must be enabled on the system
  17 - `pylint <http://www.logilab.org/857>`_ and its associated
  18   dependencies
  19 - `pep8 <https://github.com/jcrocholl/pep8/>`_
  20
  21 Note that for pylint, at the current moment the following versions
  22 need to be used::
  23
  24     $ pylint --version
  25     pylint 0.21.1,
  26     astng 0.20.1, common 0.50.3
  27
  28 To generate unittest coverage reports (``make coverage``), `coverage
  29 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
  30
  31 For Haskell development, again all things from the quick install
  32 document, plus:
  33
  34 - `haddock <http://www.haskell.org/haddock/>`_, documentation
  35   generator (equivalent to epydoc for Python)
  36 - `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
  37   used for documentation (it's source-code pretty-printing)
  38 - `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
  39   linter (equivalent to pylint for Python), recommended version 1.8 or
  40   above (tested with 1.8.15)
  41 - the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
  42   library, version 2.x
  43 - ``hpc``, which comes with the compiler, so you should already have
  44   it
  45
  46 Under Debian, these can be installed (on top of the required ones from
  47 the quick install document) via::
  48
  49   apt-get install libghc-quickcheck2-dev hscolour hlint
  50
  51
  52 Configuring for development
  53 ---------------------------
  54
  55 .. highlight:: sh
  56
  57 Run the following command (only use ``PYTHON=...`` if you need to use a
  58 different python version)::
  59
  60   ./autogen.sh && \
  61   ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
  62
  63 Haskell development notes
  64 -------------------------
  65
  66 There are a few things which can help writing or debugging the Haskell
  67 code.
  68
  69 You can run the Haskell linter :command:`hlint` via::
  70
  71   make hlint
  72
  73 This is not enabled by default (as the htools component is
  74 optional). The above command will generate both output on the terminal
  75 and, if any warnings are found, also an HTML report at
  76 ``doc/hs-lint.html``.
  77
  78 When writing or debugging TemplateHaskell code, it's useful to see
  79 what the splices are converted to. This can be done via::
  80
  81   make HEXTRA="-ddump-splices"
  82
  83 Due to the way TemplateHaskell works, it's not straightforward to
  84 build profiling code. The recommended way is to run ``make hs-prof``,
  85 or alternatively the manual sequence is::
  86
  87   make clean
  88   make htools/htools HEXTRA="-osuf .o"
  89   rm htools/htools
  90   make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
  91
  92 This will build the binary twice, per the TemplateHaskell
  93 documentation, the second one with profiling enabled.
  94
  95
  96 Packaging notes
  97 ===============
  98
  99 Ganeti is mostly developped and tested on `Debian
 100 <http://www.debian.org/>`_-based distributions, while still keeping
 101 adoptability to other Linux distributions in mind.
 102
 103 The ``doc/examples/`` directory contains a number of potentially useful
 104 scripts and configuration files. Some of them might need adjustment
 105 before use.
 106
 107 ``daemon-util``
 108 ---------------
 109
 110 This script, in the source code as ``daemons/daemon-util.in``, is used
 111 to start/stop Ganeti and do a few other things related to system
 112 daemons. It is recommended to use ``daemon-util`` also from the system's
 113 init scripts. That way the code starting and stopping daemons is shared
 114 and future changes have to be made in only one place.
 115
 116 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
 117 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
 118 not remove support for the ``EXTRA_*_ARGS`` variables for starting
 119 daemons. Some parts of Ganeti use them to pass additional arguments when
 120 starting a daemon.
 121
 122 The ``reload_ssh_keys`` function can be adjusted to use another command
 123 for reloading the OpenSSH daemon's host keys.
 124
 125 .. vim: set textwidth=72 :