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 - `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
23 - `pep8 <https://github.com/jcrocholl/pep8/>`_
24 - `PyYAML <http://pyyaml.org/>`_
26 For older developement (Ganeti < 2.4) ``docbook`` was used instead
29 Note that for pylint, at the current moment the following versions
34 astng 0.23.1, common 0.58.0
36 The same with pep8, other versions may give you errors::
41 Both these versions are the ones shipped with Debian Wheezy.
43 To generate unittest coverage reports (``make coverage``), `coverage
44 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
46 Installation of all dependencies listed here::
48 $ apt-get install python-setuptools automake git fakeroot
49 $ apt-get install pandoc python-epydoc graphviz
50 $ apt-get install python-yaml
51 $ cd / && sudo easy_install \
53 logilab-astng==0.23.1 \
54 logilab-common==0.58.0 \
59 For Haskell development, again all things from the quick install
62 - `haddock <http://www.haskell.org/haddock/>`_, documentation
63 generator (equivalent to epydoc for Python)
64 - `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
65 used for documentation (it's source-code pretty-printing)
66 - `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
67 linter (equivalent to pylint for Python), recommended version 1.8 or
68 above (tested with 1.8.15)
69 - the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
71 - the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
74 <http://batterseapower.github.com/test-framework/>`_ libraries,
75 tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
76 0.2.7, ``test-framework-quickcheck2``: 0.2.12.1
77 - ``hpc``, which comes with the compiler, so you should already have
79 - `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
80 running shell-based unit-tests
81 - `temporary <https://github.com/batterseapower/temporary/>`_ library,
82 tested with version 1.1.2.3
84 Under Debian Wheezy or later, these can be installed (on top of the
85 required ones from the quick install document) via::
87 $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
88 libghc-test-framework-dev \
89 libghc-test-framework-quickcheck2-dev \
90 libghc-test-framework-hunit-dev \
91 libghc-temporary-dev \
94 Or alternatively via ``cabal``::
96 $ cabal install QuickCheck HUnit \
97 test-framework test-framework-quickcheck2 test-framework-hunit \
98 temporary hscolour hlint shelltestrunner
101 Configuring for development
102 ---------------------------
104 Run the following command (only use ``PYTHON=...`` if you need to use a
105 different python version)::
108 ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
110 Note that doing development on a machine which already has Ganeti
111 installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
112 (see Issue 170 for a bit of history/details; in general it works if
113 the installed and developed versions are very similar, and/or if
114 PYTHONPATH is customised correctly). As such, in general it's
115 recommended to use a "clean" machine for ganeti development.
117 Haskell development notes
118 -------------------------
120 There are a few things which can help writing or debugging the Haskell
123 You can run the Haskell linter :command:`hlint` via::
127 This is not enabled by default (as the htools component is
128 optional). The above command will generate both output on the terminal
129 and, if any warnings are found, also an HTML report at
130 ``doc/hs-lint.html``.
132 When writing or debugging TemplateHaskell code, it's useful to see
133 what the splices are converted to. This can be done via::
135 $ make HEXTRA="-ddump-splices"
137 Or, more interactively::
140 λ> :set -ddump-splices
141 λ> :l src/Ganeti/Objects.hs
143 And you will get the spliced code as the module is loaded.
145 To build profiling code you must install the ``ghc-prof`` (or
146 ``gch6-prof``) package, and all the relevant libraries with their
147 ``-prof`` counterparts. If installing libraries through cabal the config
148 file should include ``library-profiling: True`` or the ``-p`` flag
149 should be used. Any library already installed can be updated by passing
150 ``--reinstall`` as well.
152 Due to the way TemplateHaskell works, it's not straightforward to
153 build profiling code. The recommended way is to run ``make hs-prof``,
154 or alternatively the manual sequence is::
157 $ make src/htools HEXTRA="-osuf .o"
159 $ make src/htools HEXTRA="-osuf .prof_o -prof -auto-all"
161 This will build the binary twice, per the TemplateHaskell
162 documentation, the second one with profiling enabled.
164 The binary files generated by compilation and the profiling/coverage
165 files can "break" tab-completion in the sources; they can be ignored,
166 for example, in bash via ``.bashrc``::
168 FIGNORE='.o:.hi:.prof_o:.tix'
170 or in emacs via ``completion-ignored-extensions`` (run ``M-x
171 customize-var completion-ignored-extensions``).
173 Running individual tests
174 ~~~~~~~~~~~~~~~~~~~~~~~~
176 When developing code, running the entire test suite can be
177 slow. Running individual tests is possible easily for unit-tests, less
178 so for shell-tests (but these are faster, so it shouldn't be needed).
182 $ export PYTHONPATH=$PWD
183 $ python ./test/py/ganeti.%mytest%
187 $ make test/hs/htest && ./test/hs/htest -t %pattern%
189 Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
190 matching any test whose name contains ``comma``), a test pattern
191 denoting a group (ending with a slash, e.g. ``Utils/``), or more
192 complex glob pattern. For more details, see the documentation (on the
193 `test-framework homepage
194 <http://batterseapower.github.com/test-framework/>`_).
199 Ganeti is mostly developed and tested on `Debian
200 <http://www.debian.org/>`_-based distributions, while still keeping
201 adaptability to other Linux distributions in mind.
203 The ``doc/examples/`` directory contains a number of potentially useful
204 scripts and configuration files. Some of them might need adjustment
210 This script, in the source code as ``daemons/daemon-util.in``, is used
211 to start/stop Ganeti and do a few other things related to system
212 daemons. It is recommended to use ``daemon-util`` also from the system's
213 init scripts. That way the code starting and stopping daemons is shared
214 and future changes have to be made in only one place.
216 ``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
217 ``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
218 not remove support for the ``EXTRA_*_ARGS`` variables for starting
219 daemons. Some parts of Ganeti use them to pass additional arguments when
222 The ``reload_ssh_keys`` function can be adjusted to use another command
223 for reloading the OpenSSH daemon's host keys.
225 .. vim: set textwidth=72 :