Statistics
| Branch: | Tag: | Revision:

root / doc / devnotes.rst @ 4355b2de

History | View | Annotate | Download (7.4 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
- `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
22
  dependencies
23
- `pep8 <https://github.com/jcrocholl/pep8/>`_
24

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

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

    
31
    $ pylint --version
32
    pylint 0.21.1,
33
    astng 0.20.1, common 0.50.3
34

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

    
37
     $ pep8 --version
38
     1.2
39

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

    
43
Installation of all dependencies listed here::
44

    
45
     $ apt-get install python-setuptools
46
     $ apt-get install pandoc python-epydoc graphviz
47
     $ cd / && sudo easy_install \
48
               sphinx \
49
               logilab-astng==0.20.1 \
50
               logilab-common==0.50.3 \
51
               pylint==0.21.1 \
52
               pep8==1.2 \
53
               coverage
54

    
55
For Haskell development, again all things from the quick install
56
document, plus:
57

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

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

    
83
  $ apt-get install libghc-quickcheck2-dev libghc-hunit-dev \
84
        libghc-test-framework-dev \
85
        libghc-test-framework-quickcheck2-dev \
86
        libghc-test-framework-hunit-dev \
87
        libghc-temporary-dev \
88
        hscolour hlint
89

    
90
Or alternatively via ``cabal``::
91

    
92
  $ cabal install QuickCheck HUnit \
93
          test-framework test-framework-quickcheck2 test-framework-hunit \
94
          temporary hscolour hlint shelltestrunner
95

    
96

    
97
Configuring for development
98
---------------------------
99

    
100
Run the following command (only use ``PYTHON=...`` if you need to use a
101
different python version)::
102

    
103
  $ ./autogen.sh && \
104
    ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
105

    
106
Note that doing development on a machine which already has Ganeti
107
installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
108
(see Issue 170 for a bit of history/details; in general it works if
109
the installed and developed versions are very similar, and/or if
110
PYTHONPATH is customised correctly). As such, in general it's
111
recommended to use a "clean" machine for ganeti development.
112

    
113
Haskell development notes
114
-------------------------
115

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

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

    
121
  $ make hlint
122

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

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

    
131
  $ make HEXTRA="-ddump-splices"
132

    
133
To build profiling code you must install the ``ghc-prof`` (or
134
``gch6-prof``) package, and all the relevant libraries with their
135
``-prof`` counterparts. If installing libraries through cabal the config
136
file should include ``library-profiling: True`` or the ``-p`` flag
137
should be used. Any library already installed can be updated by passing
138
``--reinstall`` as well.
139

    
140
Due to the way TemplateHaskell works, it's not straightforward to
141
build profiling code. The recommended way is to run ``make hs-prof``,
142
or alternatively the manual sequence is::
143

    
144
  $ make clean
145
  $ make htools/htools HEXTRA="-osuf .o"
146
  $ rm htools/htools
147
  $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
148

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

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

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

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

    
161
Running individual tests
162
~~~~~~~~~~~~~~~~~~~~~~~~
163

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

    
168
For Python tests::
169

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

    
173
For Haskell tests::
174

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

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

    
184
Packaging notes
185
===============
186

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

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

    
195
``daemon-util``
196
---------------
197

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

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

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

    
213
.. vim: set textwidth=72 :