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`, including ``qemu-img``
  10 (marked there as optional) plus (for Python):
  11
  12 - `GNU make <http://www.gnu.org/software/make/>`_
  13 - `GNU tar <http://www.gnu.org/software/tar/>`_
  14 - `Gzip <http://www.gnu.org/software/gzip/>`_
  15 - `pandoc <http://johnmacfarlane.net/pandoc/>`_
  16 - `python-epydoc <http://epydoc.sourceforge.net/>`_
  17 - `python-sphinx <http://sphinx.pocoo.org/>`_
  18   (tested with version 1.1.3)
  19 - `graphviz <http://www.graphviz.org/>`_
  20 - the `en_US.UTF-8` locale must be enabled on the system
  21 - `pylint <http://www.logilab.org/857>`_ and its associated
  22   dependencies
  23 - `pep8 <https://github.com/jcrocholl/pep8/>`_
  24
  25 For older developement (Ganeti < 2.4) ``docbook`` was used instead
  26 ``pandoc``.
  27
  28 Note that for pylint, at the current moment the following versions
  29 must be used::
  30
  31     $ pylint --version
  32     pylint 0.21.1,
  33     astng 0.20.1, common 0.50.3
  34
  35 The same with pep8, other versions may give you errors::
  36
  37      $ pep8 --version
  38      1.2
  39
  40 To generate unittest coverage reports (``make coverage``), `coverage
  41 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
  42
  43 Installation of all dependencies listed here::
  44
  45      $ apt-get install python-setuptools
  46      $ apt-get install pandoc python-epydoc graphviz
  47      $ cd / && sudo easy_install \
  48                sphinx \
  49                logilab-astng==0.20.1 \
  50                logilab-common==0.50.3 \
  51                pylint==0.21.1 \
  52                pep8==1.2 \
  53                coverage
  54
  55 For Haskell development, again all things from the quick install
  56 document, plus:
  57
  58 - `haddock <http://www.haskell.org/haddock/>`_, documentation
  59   generator (equivalent to epydoc for Python)
  60 - `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
  61   used for documentation (it's source-code pretty-printing)
  62 - `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
  63   linter (equivalent to pylint for Python), recommended version 1.8 or
  64   above (tested with 1.8.15)
  65 - the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
  66   library, version 2.x
  67 - the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
  68   1.2.x)
  69 - the `test-framework
  70   <http://batterseapower.github.com/test-framework/>`_ libraries,
  71   tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
  72   0.2.7, ``test-framework-quickcheck2``: 0.2.12
  73 - ``hpc``, which comes with the compiler, so you should already have
  74   it
  75 - `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
  76   running shell-based unit-tests
  77 - `temporary <https://github.com/batterseapower/temporary/>`_ library,
  78   tested with version 1.1.2.3
  79
  80 Under Debian Wheezy or later, these can be installed (on top of the
  81 required ones from the quick install document) via::
  82
  83   $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
  84         libghc-test-framework-dev \
  85         libghc-test-framework-quickcheck2-dev \
  86         libghc-test-framework-hunit-dev \
  87         libghc-temporary-dev \
  88         hscolour hlint
  89
  90 Or alternatively via ``cabal``::
  91
  92   $ cabal install QuickCheck HUnit \
  93           test-framework test-framework-quickcheck2 test-framework-hunit \
  94           temporary hscolour hlint shelltestrunner
  95
  96
  97 Configuring for development
  98 ---------------------------
  99
 100 Run the following command (only use ``PYTHON=...`` if you need to use a
 101 different python version)::
 102
 103   $ ./autogen.sh && \
 104     ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
 105
 106 Note that doing development on a machine which already has Ganeti
 107 installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
 108 (see Issue 170 for a bit of history/details; in general it works if
 109 the installed and developed versions are very similar, and/or if
 110 PYTHONPATH is customised correctly). As such, in general it's
 111 recommended to use a "clean" machine for ganeti development.
 112
 113 Haskell development notes
 114 -------------------------
 115
 116 There are a few things which can help writing or debugging the Haskell
 117 code.
 118
 119 You can run the Haskell linter :command:`hlint` via::
 120
 121   $ make hlint
 122
 123 This is not enabled by default (as the htools component is
 124 optional). The above command will generate both output on the terminal
 125 and, if any warnings are found, also an HTML report at
 126 ``doc/hs-lint.html``.
 127
 128 When writing or debugging TemplateHaskell code, it's useful to see
 129 what the splices are converted to. This can be done via::
 130
 131   $ make HEXTRA="-ddump-splices"
 132
 133 To build profiling code you must install the ``ghc-prof`` (or
 134 ``gch6-prof``) package, and all the relevant libraries with their
 135 ``-prof`` counterparts. If installing libraries through cabal the config
 136 file should include ``library-profiling: True`` or the ``-p`` flag
 137 should be used. Any library already installed can be updated by passing
 138 ``--reinstall`` as well.
 139
 140 Due to the way TemplateHaskell works, it's not straightforward to
 141 build profiling code. The recommended way is to run ``make hs-prof``,
 142 or alternatively the manual sequence is::
 143
 144   $ make clean
 145   $ make htools/htools HEXTRA="-osuf .o"
 146   $ rm htools/htools
 147   $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
 148
 149 This will build the binary twice, per the TemplateHaskell
 150 documentation, the second one with profiling enabled.
 151
 152 The binary files generated by compilation and the profiling/coverage
 153 files can "break" tab-completion in the sources; they can be ignored,
 154 for example, in bash via ``.bashrc``::
 155
 156   FIGNORE='.o:.hi:.prof_o:.tix'
 157
 158 or in emacs via ``completion-ignored-extensions`` (run ``M-x
 159 customize-var completion-ignored-extensions``).
 160
 161 Running individual tests
 162 ~~~~~~~~~~~~~~~~~~~~~~~~
 163
 164 When developing code, running the entire test suite can be
 165 slow. Running individual tests is possible easily for unit-tests, less
 166 so for shell-tests (but these are faster, so it shouldn't be needed).
 167
 168 For Python tests::
 169
 170   $ export PYTHONPATH=$PWD
 171   $ python ./test/ganeti.%mytest%
 172
 173 For Haskell tests::
 174
 175   $ make htest/test && ./htest/test -t %pattern%
 176
 177 Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
 178 matching any test whose name contains ``comma``), a test pattern
 179 denoting a group (ending with a slash, e.g. ``Utils/``), or more
 180 complex glob pattern. For more details, see the documentation (on the
 181 `test-framework homepage
 182 <http://batterseapower.github.com/test-framework/>`_).
 183
 184 Packaging notes
 185 ===============
 186
 187 Ganeti is mostly developed and tested on `Debian
 188 <http://www.debian.org/>`_-based distributions, while still keeping
 189 adaptability to other Linux distributions in mind.
 190
 191 The ``doc/examples/`` directory contains a number of potentially useful
 192 scripts and configuration files. Some of them might need adjustment
 193 before use.
 194
 195 ``daemon-util``
 196 ---------------
 197
 198 This script, in the source code as ``daemons/daemon-util.in``, is used
 199 to start/stop Ganeti and do a few other things related to system
 200 daemons. It is recommended to use ``daemon-util`` also from the system's
 201 init scripts. That way the code starting and stopping daemons is shared
 202 and future changes have to be made in only one place.
 203
 204 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
 205 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
 206 not remove support for the ``EXTRA_*_ARGS`` variables for starting
 207 daemons. Some parts of Ganeti use them to pass additional arguments when
 208 starting a daemon.
 209
 210 The ``reload_ssh_keys`` function can be adjusted to use another command
 211 for reloading the OpenSSH daemon's host keys.
 212
 213 .. vim: set textwidth=72 :