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 - `graphviz <http://www.graphviz.org/>`_
21 - the `en_US.UTF-8` locale must be enabled on the system
22 - `pylint <http://www.logilab.org/857>`_ and its associated
24 - `pep8 <https://github.com/jcrocholl/pep8/>`_
25 - `PyYAML <http://pyyaml.org/>`_
27 For older developement (Ganeti < 2.4) ``docbook`` was used instead of
30 Note that for pylint, at the current moment the following versions
35 astng 0.23.1, common 0.58.0
37 The same with pep8, other versions may give you errors::
42 Both these versions are the ones shipped with Debian Wheezy.
44 To generate unittest coverage reports (``make coverage``), `coverage
45 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
47 Installation of all dependencies listed here::
49 $ apt-get install python-setuptools automake git fakeroot
50 $ apt-get install pandoc python-epydoc graphviz
51 $ apt-get install python-yaml python-mock
52 $ cd / && sudo easy_install \
54 logilab-astng==0.23.1 \
55 logilab-common==0.58.0 \
60 For Haskell development, again all things from the quick install
63 - `haddock <http://www.haskell.org/haddock/>`_, documentation
64 generator (equivalent to epydoc for Python)
65 - `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
66 used for documentation (it's source-code pretty-printing)
67 - `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
68 linter (equivalent to pylint for Python), recommended version 1.8 or
69 above (tested with 1.8.15)
70 - the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
72 - the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
75 <http://batterseapower.github.com/test-framework/>`_ libraries,
76 tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
77 0.2.7, ``test-framework-quickcheck2``: 0.2.12.1
78 - ``hpc``, which comes with the compiler, so you should already have
80 - `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
81 running shell-based unit-tests
82 - `temporary <https://github.com/batterseapower/temporary/>`_ library,
83 tested with version 1.1.2.3
85 Under Debian Wheezy or later, these can be installed (on top of the
86 required ones from the quick install document) via::
88 $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
89 libghc-test-framework-dev \
90 libghc-test-framework-quickcheck2-dev \
91 libghc-test-framework-hunit-dev \
92 libghc-temporary-dev \
95 Or alternatively via ``cabal``::
97 $ cabal install QuickCheck HUnit \
98 test-framework test-framework-quickcheck2 test-framework-hunit \
99 temporary hscolour hlint shelltestrunner
102 Configuring for development
103 ---------------------------
105 Run the following command (only use ``PYTHON=...`` if you need to use a
106 different python version)::
109 ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
111 Note that doing development on a machine which already has Ganeti
112 installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
113 (see Issue 170 for a bit of history/details; in general it works if
114 the installed and developed versions are very similar, and/or if
115 PYTHONPATH is customised correctly). As such, in general it's
116 recommended to use a "clean" machine for ganeti development.
118 Haskell development notes
119 -------------------------
121 There are a few things which can help writing or debugging the Haskell
124 You can run the Haskell linter :command:`hlint` via::
128 This is not enabled by default (as the htools component is
129 optional). The above command will generate both output on the terminal
130 and, if any warnings are found, also an HTML report at
131 ``doc/hs-lint.html``.
133 When writing or debugging TemplateHaskell code, it's useful to see
134 what the splices are converted to. This can be done via::
136 $ make HEXTRA="-ddump-splices"
138 Or, more interactively::
141 λ> :set -ddump-splices
142 λ> :l src/Ganeti/Objects.hs
144 And you will get the spliced code as the module is loaded.
146 To build profiling code you must install the ``ghc-prof`` (or
147 ``gch6-prof``) package, and all the relevant libraries with their
148 ``-prof`` counterparts. If installing libraries through cabal the config
149 file should include ``library-profiling: True`` or the ``-p`` flag
150 should be used. Any library already installed can be updated by passing
151 ``--reinstall`` as well.
153 Due to the way TemplateHaskell works, it's not straightforward to
154 build profiling code. The recommended way is to run ``make hs-prof``,
155 or alternatively the manual sequence is::
158 $ make src/htools HEXTRA="-osuf .o"
160 $ make src/htools HEXTRA="-osuf .prof_o -prof -auto-all"
162 This will build the binary twice, per the TemplateHaskell
163 documentation, the second one with profiling enabled.
165 The binary files generated by compilation and the profiling/coverage
166 files can "break" tab-completion in the sources; they can be ignored,
167 for example, in bash via ``.bashrc``::
169 FIGNORE='.o:.hi:.prof_o:.tix'
171 or in emacs via ``completion-ignored-extensions`` (run ``M-x
172 customize-var completion-ignored-extensions``).
174 Running individual tests
175 ~~~~~~~~~~~~~~~~~~~~~~~~
177 When developing code, running the entire test suite can be
178 slow. Running individual tests is possible. There are different
179 Makefile targets for running individual Python and Haskell tests.
183 $ export PYTHONPATH=$PWD
184 $ python ./test/py/ganeti.%mytest%
188 $ make hs-test-%pattern%
190 Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
191 matching any test whose name contains ``comma``), a test pattern
192 denoting a group (ending with a slash, e.g. ``Utils/``), or more
193 complex glob pattern. For more details, search for glob patterns in
194 the documentation of `test-framework
195 <http://batterseapower.github.com/test-framework/>`_).
197 For individual Haskell shelltests::
199 $ make hs-shell-%name%
201 which runs the test ``test/hs/shelltests/htools-%name%.test``. For
202 example, to run the test ``test/hs/shelltests/htools-balancing.test``,
205 $ make hs-shell-balancing
207 For combined Haskell shelltests::
209 $ make hs-shell-{%name1%,%name2%,...}
213 $ make hs-shell-{balancing,basic}
218 Ganeti is mostly developed and tested on `Debian
219 <http://www.debian.org/>`_-based distributions, while still keeping
220 adaptability to other Linux distributions in mind.
222 The ``doc/examples/`` directory contains a number of potentially useful
223 scripts and configuration files. Some of them might need adjustment
229 This script, in the source code as ``daemons/daemon-util.in``, is used
230 to start/stop Ganeti and do a few other things related to system
231 daemons. It is recommended to use ``daemon-util`` also from the system's
232 init scripts. That way the code starting and stopping daemons is shared
233 and future changes have to be made in only one place.
235 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
236 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
237 not remove support for the ``EXTRA_*_ARGS`` variables for starting
238 daemons. Some parts of Ganeti use them to pass additional arguments when
241 The ``reload_ssh_keys`` function can be adjusted to use another command
242 for reloading the OpenSSH daemon's host keys.
244 .. vim: set textwidth=72 :