4 .. highlight:: shell-example
9 Most dependencies from :doc:`install-quick`, including ``qemu-img``
10 (marked there as optional) plus (for Python):
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 - `python-mock <http://www.voidspace.org.uk/python/mock/>`_
20 (tested with version 1.0.1)
21 - `graphviz <http://www.graphviz.org/>`_
22 - the `en_US.UTF-8` locale must be enabled on the system
23 - `pylint <http://www.logilab.org/857>`_ and its associated
25 - `pep8 <https://github.com/jcrocholl/pep8/>`_
26 - `PyYAML <http://pyyaml.org/>`_
28 For older developement (Ganeti < 2.4) ``docbook`` was used instead of
31 Note that for pylint, at the current moment the following versions
36 astng 0.24.1, common 0.58.3
38 The same with pep8, other versions may give you errors::
43 Both these versions are the ones shipped with Ubuntu 13.04.
45 To generate unittest coverage reports (``make coverage``), `coverage
46 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
48 Installation of all dependencies listed here::
50 $ apt-get install python-setuptools automake git fakeroot
51 $ apt-get install pandoc python-epydoc graphviz python-sphinx
52 $ apt-get install python-yaml
53 $ cd / && easy_install \
54 logilab-astng==0.24.1 \
55 logilab-common==0.58.3 \
61 For Haskell development, again all things from the quick install
64 - `haddock <http://www.haskell.org/haddock/>`_, documentation
65 generator (equivalent to epydoc for Python)
66 - `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
67 used for documentation (it's source-code pretty-printing)
68 - `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
69 linter (equivalent to pylint for Python), recommended version 1.8 or
70 above (tested with 1.8.43)
71 - the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
73 - the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
76 <http://batterseapower.github.com/test-framework/>`_ libraries,
77 tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
78 0.2.7, ``test-framework-quickcheck2``: 0.2.12.1
79 - ``hpc``, which comes with the compiler, so you should already have
81 - `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
82 running shell-based unit-tests
83 - `temporary <https://github.com/batterseapower/temporary/>`_ library,
84 tested with version 1.1.2.3
86 Under Debian Wheezy or later, these can be installed (on top of the
87 required ones from the quick install document) via::
89 $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
90 libghc-test-framework-dev \
91 libghc-test-framework-quickcheck2-dev \
92 libghc-test-framework-hunit-dev \
93 libghc-temporary-dev shelltestrunner \
96 Or alternatively via ``cabal``::
98 $ cabal install QuickCheck HUnit \
99 test-framework test-framework-quickcheck2 test-framework-hunit \
100 temporary hscolour hlint shelltestrunner
103 Configuring for development
104 ---------------------------
106 Run the following command (only use ``PYTHON=...`` if you need to use a
107 different python version)::
110 ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
112 Note that doing development on a machine which already has Ganeti
113 installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
114 (see Issue 170 for a bit of history/details; in general it works if
115 the installed and developed versions are very similar, and/or if
116 PYTHONPATH is customised correctly). As such, in general it's
117 recommended to use a "clean" machine for ganeti development.
119 Haskell development notes
120 -------------------------
122 There are a few things which can help writing or debugging the Haskell
125 You can run the Haskell linter :command:`hlint` via::
129 This is not enabled by default (as the htools component is
130 optional). The above command will generate both output on the terminal
131 and, if any warnings are found, also an HTML report at
132 ``doc/hs-lint.html``.
134 When writing or debugging TemplateHaskell code, it's useful to see
135 what the splices are converted to. This can be done via::
137 $ make HEXTRA="-ddump-splices"
139 Or, more interactively::
142 λ> :set -ddump-splices
143 λ> :l src/Ganeti/Objects.hs
145 And you will get the spliced code as the module is loaded.
147 To build profiling code you must install the ``ghc-prof`` (or
148 ``gch6-prof``) package, and all the relevant libraries with their
149 ``-prof`` counterparts. If installing libraries through cabal the config
150 file should include ``library-profiling: True`` or the ``-p`` flag
151 should be used. Any library already installed can be updated by passing
152 ``--reinstall`` as well.
154 Due to the way TemplateHaskell works, it's not straightforward to
155 build profiling code. The recommended way is to run ``make hs-prof``,
156 or alternatively the manual sequence is::
159 $ make src/htools HEXTRA="-osuf .o"
161 $ make src/htools HEXTRA="-osuf .prof_o -prof -auto-all"
163 This will build the binary twice, per the TemplateHaskell
164 documentation, the second one with profiling enabled.
166 The binary files generated by compilation and the profiling/coverage
167 files can "break" tab-completion in the sources; they can be ignored,
168 for example, in bash via ``.bashrc``::
170 FIGNORE='.o:.hi:.prof_o:.tix'
172 or in emacs via ``completion-ignored-extensions`` (run ``M-x
173 customize-var completion-ignored-extensions``).
175 Running individual tests
176 ~~~~~~~~~~~~~~~~~~~~~~~~
178 When developing code, running the entire test suite can be
179 slow. Running individual tests is possible. There are different
180 Makefile targets for running individual Python and Haskell tests.
184 $ export PYTHONPATH=$PWD
185 $ python ./test/py/ganeti.%mytest%
189 $ make hs-test-%pattern%
191 Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
192 matching any test whose name contains ``comma``), a test pattern
193 denoting a group (ending with a slash, e.g. ``Utils/``), or more
194 complex glob pattern. For more details, search for glob patterns in
195 the documentation of `test-framework
196 <http://batterseapower.github.com/test-framework/>`_).
198 For individual Haskell shelltests::
200 $ make hs-shell-%name%
202 which runs the test ``test/hs/shelltests/htools-%name%.test``. For
203 example, to run the test ``test/hs/shelltests/htools-balancing.test``,
206 $ make hs-shell-balancing
208 For combined Haskell shelltests::
210 $ make hs-shell-{%name1%,%name2%,...}
214 $ make hs-shell-{balancing,basic}
216 Checking for the correct style of the NEWS file is also possible, by running::
223 Ganeti is mostly developed and tested on `Debian
224 <http://www.debian.org/>`_-based distributions, while still keeping
225 adaptability to other Linux distributions in mind.
227 The ``doc/examples/`` directory contains a number of potentially useful
228 scripts and configuration files. Some of them might need adjustment
234 This script, in the source code as ``daemons/daemon-util.in``, is used
235 to start/stop Ganeti and do a few other things related to system
236 daemons. It is recommended to use ``daemon-util`` also from the system's
237 init scripts. That way the code starting and stopping daemons is shared
238 and future changes have to be made in only one place.
240 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
241 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
242 not remove support for the ``EXTRA_*_ARGS`` variables for starting
243 daemons. Some parts of Ganeti use them to pass additional arguments when
246 The ``reload_ssh_keys`` function can be adjusted to use another command
247 for reloading the OpenSSH daemon's host keys.
249 .. vim: set textwidth=72 :