root / doc / devnotes.rst @ a41a1eec
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 : |