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
  78 Under Debian Wheezy or later, these can be installed (on top of the
  79 required ones from the quick install document) via::
  80
  81   $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
  82         libghc-test-framework-dev \
  83         libghc-test-framework-quickcheck2-dev \
  84         libghc-test-framework-hunit-dev \
  85         hscolour hlint
  86
  87 Or alternatively via ``cabal``::
  88
  89   $ cabal install QuickCheck HUnit \
  90           test-framework test-framework-quickcheck2 test-framework-hunit \
  91           hscolour hlint shelltestrunner
  92
  93
  94 Configuring for development
  95 ---------------------------
  96
  97 Run the following command (only use ``PYTHON=...`` if you need to use a
  98 different python version)::
  99
 100   $ ./autogen.sh && \
 101     ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
 102
 103 Note that doing development on a machine which already has Ganeti
 104 installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
 105 (see Issue 170 for a bit of history/details; in general it works if
 106 the installed and developed versions are very similar, and/or if
 107 PYTHONPATH is customised correctly). As such, in general it's
 108 recommended to use a "clean" machine for ganeti development.
 109
 110 Haskell development notes
 111 -------------------------
 112
 113 There are a few things which can help writing or debugging the Haskell
 114 code.
 115
 116 You can run the Haskell linter :command:`hlint` via::
 117
 118   $ make hlint
 119
 120 This is not enabled by default (as the htools component is
 121 optional). The above command will generate both output on the terminal
 122 and, if any warnings are found, also an HTML report at
 123 ``doc/hs-lint.html``.
 124
 125 When writing or debugging TemplateHaskell code, it's useful to see
 126 what the splices are converted to. This can be done via::
 127
 128   $ make HEXTRA="-ddump-splices"
 129
 130 Due to the way TemplateHaskell works, it's not straightforward to
 131 build profiling code. The recommended way is to run ``make hs-prof``,
 132 or alternatively the manual sequence is::
 133
 134   $ make clean
 135   $ make htools/htools HEXTRA="-osuf .o"
 136   $ rm htools/htools
 137   $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
 138
 139 This will build the binary twice, per the TemplateHaskell
 140 documentation, the second one with profiling enabled.
 141
 142 The binary files generated by compilation and the profiling/coverage
 143 files can "break" tab-completion in the sources; they can be ignored,
 144 for example, in bash via ``.bashrc``::
 145
 146   FIGNORE='.o:.hi:.prof_o:.tix'
 147
 148 or in emacs via ``completion-ignored-extensions`` (run ``M-x
 149 customize-var completion-ignored-extensions``).
 150
 151 Running individual tests
 152 ~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 When developing code, running the entire test suite can be
 155 slow. Running individual tests is possible easily for unit-tests, less
 156 so for shell-tests (but these are faster, so it shouldn't be needed).
 157
 158 For Python tests::
 159
 160   $ export PYTHONPATH=$PWD
 161   $ python ./test/ganeti.%mytest%
 162
 163 For Haskell tests::
 164
 165   $ make htest/test && ./htest/test -t %pattern%
 166
 167 Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
 168 matching any test whose name contains ``comma``), a test pattern
 169 denoting a group (ending with a slash, e.g. ``Utils/``), or more
 170 complex glob pattern. For more details, see the documentation (on the
 171 `test-framework homepage
 172 <http://batterseapower.github.com/test-framework/>`_).
 173
 174 Packaging notes
 175 ===============
 176
 177 Ganeti is mostly developed and tested on `Debian
 178 <http://www.debian.org/>`_-based distributions, while still keeping
 179 adaptability to other Linux distributions in mind.
 180
 181 The ``doc/examples/`` directory contains a number of potentially useful
 182 scripts and configuration files. Some of them might need adjustment
 183 before use.
 184
 185 ``daemon-util``
 186 ---------------
 187
 188 This script, in the source code as ``daemons/daemon-util.in``, is used
 189 to start/stop Ganeti and do a few other things related to system
 190 daemons. It is recommended to use ``daemon-util`` also from the system's
 191 init scripts. That way the code starting and stopping daemons is shared
 192 and future changes have to be made in only one place.
 193
 194 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
 195 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
 196 not remove support for the ``EXTRA_*_ARGS`` variables for starting
 197 daemons. Some parts of Ganeti use them to pass additional arguments when
 198 starting a daemon.
 199
 200 The ``reload_ssh_keys`` function can be adjusted to use another command
 201 for reloading the OpenSSH daemon's host keys.
 202
 203 .. vim: set textwidth=72 :