Statistics
| Branch: | Tag: | Revision:

root / doc / devnotes.rst @ 9110fb4a

History | View | Annotate | Download (8.3 kB)

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
- `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
24
  dependencies
25
- `pep8 <https://github.com/jcrocholl/pep8/>`_
26
- `PyYAML <http://pyyaml.org/>`_
27

    
28
For older developement (Ganeti < 2.4) ``docbook`` was used instead of
29
``pandoc``.
30

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

    
34
    $ pylint --version
35
    pylint 0.26.0,
36
    astng 0.24.1, common 0.58.3
37

    
38
The same with pep8, other versions may give you errors::
39

    
40
     $ pep8 --version
41
     1.3.3
42

    
43
Both these versions are the ones shipped with Ubuntu 13.04.
44

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

    
48
Installation of all dependencies listed here::
49

    
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 \
56
               pylint==0.26.0 \
57
               pep8==1.3.3 \
58
               mock==1.0.1 \
59
               coverage
60

    
61
For Haskell development, again all things from the quick install
62
document, plus:
63

    
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>`_
72
  library, version 2.x
73
- the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
74
  1.2.x)
75
- the `test-framework
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
80
  it
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
85

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

    
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 \
94
        hscolour hlint
95

    
96
Or alternatively via ``cabal``::
97

    
98
  $ cabal install QuickCheck HUnit \
99
          test-framework test-framework-quickcheck2 test-framework-hunit \
100
          temporary hscolour hlint shelltestrunner
101

    
102

    
103
Configuring for development
104
---------------------------
105

    
106
Run the following command (only use ``PYTHON=...`` if you need to use a
107
different python version)::
108

    
109
  $ ./autogen.sh && \
110
    ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
111

    
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.
118

    
119
Style guide
120
-----------
121

    
122
Please adhere to the :doc:`dev-codestyle` while writing code for Ganeti.
123

    
124
Haskell development notes
125
-------------------------
126

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

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

    
132
  $ make hlint
133

    
134
This is not enabled by default (as the htools component is
135
optional). The above command will generate both output on the terminal
136
and, if any warnings are found, also an HTML report at
137
``doc/hs-lint.html``.
138

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

    
142
  $ make HEXTRA="-ddump-splices"
143

    
144
Or, more interactively::
145

    
146
  $ ghci
147
  λ> :set -ddump-splices
148
  λ> :l src/Ganeti/Objects.hs
149

    
150
And you will get the spliced code as the module is loaded.
151

    
152
To build profiling code you must install the ``ghc-prof`` (or
153
``gch6-prof``) package, and all the relevant libraries with their
154
``-prof`` counterparts. If installing libraries through cabal the config
155
file should include ``library-profiling: True`` or the ``-p`` flag
156
should be used. Any library already installed can be updated by passing
157
``--reinstall`` as well.
158

    
159
Due to the way TemplateHaskell works, it's not straightforward to
160
build profiling code. The recommended way is to run ``make hs-prof``,
161
or alternatively the manual sequence is::
162

    
163
  $ make clean
164
  $ make src/htools HEXTRA="-osuf .o"
165
  $ rm src/htools
166
  $ make src/htools HEXTRA="-osuf .prof_o -prof -auto-all"
167

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

    
171
The binary files generated by compilation and the profiling/coverage
172
files can "break" tab-completion in the sources; they can be ignored,
173
for example, in bash via ``.bashrc``::
174

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

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

    
180
Running individual tests
181
~~~~~~~~~~~~~~~~~~~~~~~~
182

    
183
When developing code, running the entire test suite can be
184
slow. Running individual tests is possible. There are different
185
Makefile targets for running individual Python and Haskell tests.
186

    
187
For Python tests::
188

    
189
  $ export PYTHONPATH=$PWD
190
  $ python ./test/py/ganeti.%mytest%
191

    
192
For Haskell tests::
193

    
194
  $ make hs-test-%pattern%
195

    
196
Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
197
matching any test whose name contains ``comma``), a test pattern
198
denoting a group (ending with a slash, e.g. ``Utils/``), or more
199
complex glob pattern. For more details, search for glob patterns in
200
the documentation of `test-framework
201
<http://batterseapower.github.com/test-framework/>`_).
202

    
203
For individual Haskell shelltests::
204

    
205
  $ make hs-shell-%name%
206

    
207
which runs the test ``test/hs/shelltests/htools-%name%.test``. For
208
example, to run the test ``test/hs/shelltests/htools-balancing.test``,
209
use::
210

    
211
  $ make hs-shell-balancing
212

    
213
For combined Haskell shelltests::
214

    
215
  $ make hs-shell-{%name1%,%name2%,...}
216

    
217
for example::
218

    
219
  $ make hs-shell-{balancing,basic}
220

    
221
Checking for the correct style of the NEWS file is also possible, by running::
222

    
223
  $ make check-news
224

    
225
Packaging notes
226
===============
227

    
228
Ganeti is mostly developed and tested on `Debian
229
<http://www.debian.org/>`_-based distributions, while still keeping
230
adaptability to other Linux distributions in mind.
231

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

    
236
``daemon-util``
237
---------------
238

    
239
This script, in the source code as ``daemons/daemon-util.in``, is used
240
to start/stop Ganeti and do a few other things related to system
241
daemons. It is recommended to use ``daemon-util`` also from the system's
242
init scripts. That way the code starting and stopping daemons is shared
243
and future changes have to be made in only one place.
244

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

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

    
254
.. vim: set textwidth=72 :