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

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