devnotes.rst 6.49 KB
Newer Older
1
2
3
Developer notes
===============

4
5
.. highlight:: shell-example

6
7
8
Build dependencies
------------------

9
10
Most dependencies from :doc:`install-quick`, including ``qemu-img``
(marked there as optional) plus (for Python):
11

Michael Hanselmann's avatar
Michael Hanselmann committed
12
13
14
- `GNU make <http://www.gnu.org/software/make/>`_
- `GNU tar <http://www.gnu.org/software/tar/>`_
- `Gzip <http://www.gnu.org/software/gzip/>`_
Iustin Pop's avatar
Iustin Pop committed
15
- `pandoc <http://johnmacfarlane.net/pandoc/>`_
16
- `python-epydoc <http://epydoc.sourceforge.net/>`_
Michael Hanselmann's avatar
Michael Hanselmann committed
17
- `python-sphinx <http://sphinx.pocoo.org/>`_
18
  (tested with version 1.1.3)
Michael Hanselmann's avatar
Michael Hanselmann committed
19
- `graphviz <http://www.graphviz.org/>`_
Guido Trotter's avatar
Guido Trotter committed
20
- the `en_US.UTF-8` locale must be enabled on the system
21
22
- `pylint <http://www.logilab.org/857>`_ and its associated
  dependencies
23
- `pep8 <https://github.com/jcrocholl/pep8/>`_
24

25
26
27
For older developement (Ganeti < 2.4) ``docbook`` was used instead
``pandoc``.

28
Note that for pylint, at the current moment the following versions
29
must be used::
30
31
32
33

    $ pylint --version
    pylint 0.21.1,
    astng 0.20.1, common 0.50.3
34

35
36
37
The same with pep8, other versions may give you errors::

     $ pep8 --version
Iustin Pop's avatar
Iustin Pop committed
38
     1.2
39

40
41
42
To generate unittest coverage reports (``make coverage``), `coverage
<http://pypi.python.org/pypi/coverage>`_ needs to be installed.

43
44
45
46
47
48
49
50
51
Installation of all dependencies listed here::

     $ apt-get install python-setuptools
     $ apt-get install pandoc python-epydoc graphviz
     $ cd / && sudo easy_install \
               sphinx \
               logilab-astng==0.20.1 \
               logilab-common==0.50.3 \
               pylint==0.21.1 \
Iustin Pop's avatar
Iustin Pop committed
52
               pep8==1.2 \
53
54
               coverage

55
56
57
58
59
60
61
62
For Haskell development, again all things from the quick install
document, plus:

- `haddock <http://www.haskell.org/haddock/>`_, documentation
  generator (equivalent to epydoc for Python)
- `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
  used for documentation (it's source-code pretty-printing)
- `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
Iustin Pop's avatar
Iustin Pop committed
63
64
  linter (equivalent to pylint for Python), recommended version 1.8 or
  above (tested with 1.8.15)
65
- the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
Iustin Pop's avatar
Iustin Pop committed
66
  library, version 2.x
67
68
69
70
71
72
- the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
  1.2.x)
- the `test-framework
  <http://batterseapower.github.com/test-framework/>`_ libraries,
  tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
  0.2.7, ``test-framework-quickcheck2``: 0.2.12
73
74
- ``hpc``, which comes with the compiler, so you should already have
  it
75
- `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
76
  running shell-based unit-tests
77
78
79

Under Debian Wheezy or later, these can be installed (on top of the
required ones from the quick install document) via::
80

81
82
83
84
85
  $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
        libghc-test-framework-dev \
        libghc-test-framework-quickcheck2-dev \
        libghc-test-framework-hunit-dev \
        hscolour hlint
86

87
88
Or alternatively via ``cabal``::

89
90
91
  $ cabal install QuickCheck HUnit \
          test-framework test-framework-quickcheck2 test-framework-hunit \
          hscolour hlint shelltestrunner
92

93

94
95
96
Configuring for development
---------------------------

97
98
99
Run the following command (only use ``PYTHON=...`` if you need to use a
different python version)::

100
101
  $ ./autogen.sh && \
    ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
102

Iustin Pop's avatar
Iustin Pop committed
103
104
105
106
107
108
109
110
Haskell development notes
-------------------------

There are a few things which can help writing or debugging the Haskell
code.

You can run the Haskell linter :command:`hlint` via::

111
  $ make hlint
Iustin Pop's avatar
Iustin Pop committed
112

Iustin Pop's avatar
Iustin Pop committed
113
114
115
This is not enabled by default (as the htools component is
optional). The above command will generate both output on the terminal
and, if any warnings are found, also an HTML report at
Iustin Pop's avatar
Iustin Pop committed
116
117
118
119
120
``doc/hs-lint.html``.

When writing or debugging TemplateHaskell code, it's useful to see
what the splices are converted to. This can be done via::

121
  $ make HEXTRA="-ddump-splices"
Iustin Pop's avatar
Iustin Pop committed
122
123

Due to the way TemplateHaskell works, it's not straightforward to
124
125
build profiling code. The recommended way is to run ``make hs-prof``,
or alternatively the manual sequence is::
Iustin Pop's avatar
Iustin Pop committed
126

127
128
129
130
  $ make clean
  $ make htools/htools HEXTRA="-osuf .o"
  $ rm htools/htools
  $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
Iustin Pop's avatar
Iustin Pop committed
131
132
133
134

This will build the binary twice, per the TemplateHaskell
documentation, the second one with profiling enabled.

135
136
137
138
139
140
141
142
The binary files generated by compilation and the profiling/coverage
files can "break" tab-completion in the sources; they can be ignored,
for example, in bash via ``.bashrc``::

  FIGNORE='.o:.hi:.prof_o:.tix'

or in emacs via ``completion-ignored-extensions`` (run ``M-x
customize-var completion-ignored-extensions``).
143

144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
Running individual tests
~~~~~~~~~~~~~~~~~~~~~~~~

When developing code, running the entire test suite can be
slow. Running individual tests is possible easily for unit-tests, less
so for shell-tests (but these are faster, so it shouldn't be needed).

For Python tests::

  $ export PYTHONPATH=$PWD
  $ python ./test/ganeti.%mytest%

For Haskell tests::

  $ make htest/test && ./htest/test -t %pattern%

Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
matching any test whose name contains ``comma``), a test pattern
denoting a group (ending with a slash, e.g. ``Utils/``), or more
complex glob pattern. For more details, see the documentation (on the
`test-framework homepage
<http://batterseapower.github.com/test-framework/>`_).

167
168
169
Packaging notes
===============

170
Ganeti is mostly developed and tested on `Debian
171
<http://www.debian.org/>`_-based distributions, while still keeping
172
adaptability to other Linux distributions in mind.
173
174
175
176
177
178
179
180
181
182

The ``doc/examples/`` directory contains a number of potentially useful
scripts and configuration files. Some of them might need adjustment
before use.

``daemon-util``
---------------

This script, in the source code as ``daemons/daemon-util.in``, is used
to start/stop Ganeti and do a few other things related to system
183
daemons. It is recommended to use ``daemon-util`` also from the system's
184
185
186
187
188
189
190
191
192
193
194
195
init scripts. That way the code starting and stopping daemons is shared
and future changes have to be made in only one place.

``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
not remove support for the ``EXTRA_*_ARGS`` variables for starting
daemons. Some parts of Ganeti use them to pass additional arguments when
starting a daemon.

The ``reload_ssh_keys`` function can be adjusted to use another command
for reloading the OpenSSH daemon's host keys.

196
.. vim: set textwidth=72 :