Statistics
| Branch: | Tag: | Revision:

root / doc / devnotes.rst @ fc6075dd

History | View | Annotate | Download (4.9 kB)

1 832aef24 Michael Hanselmann
Developer notes
2 832aef24 Michael Hanselmann
===============
3 832aef24 Michael Hanselmann
4 727ee1ec Iustin Pop
.. highlight:: shell-example
5 727ee1ec Iustin Pop
6 b2fc7ea1 Michael Hanselmann
Build dependencies
7 b2fc7ea1 Michael Hanselmann
------------------
8 b2fc7ea1 Michael Hanselmann
9 fc6075dd Agata Murawska
Most dependencies from :doc:`install-quick`, including ``qemu-img``
10 fc6075dd Agata Murawska
(marked there as optional) plus (for Python):
11 cbf3d64b Michael Hanselmann
12 c27ba1cc Michael Hanselmann
- `GNU make <http://www.gnu.org/software/make/>`_
13 c27ba1cc Michael Hanselmann
- `GNU tar <http://www.gnu.org/software/tar/>`_
14 c27ba1cc Michael Hanselmann
- `Gzip <http://www.gnu.org/software/gzip/>`_
15 18e2b6e4 Iustin Pop
- `pandoc <http://johnmacfarlane.net/pandoc/>`_
16 fc6075dd Agata Murawska
- `python-epydoc <http://epydoc.sourceforge.net/>`_
17 c27ba1cc Michael Hanselmann
- `python-sphinx <http://sphinx.pocoo.org/>`_
18 fc6075dd Agata Murawska
  (tested with version 1.1.3)
19 c27ba1cc Michael Hanselmann
- `graphviz <http://www.graphviz.org/>`_
20 1de45c78 Guido Trotter
- the `en_US.UTF-8` locale must be enabled on the system
21 77a180f6 Iustin Pop
- `pylint <http://www.logilab.org/857>`_ and its associated
22 77a180f6 Iustin Pop
  dependencies
23 08366664 Michael Hanselmann
- `pep8 <https://github.com/jcrocholl/pep8/>`_
24 77a180f6 Iustin Pop
25 fc6075dd Agata Murawska
For older developement (Ganeti < 2.4) ``docbook`` was used instead
26 fc6075dd Agata Murawska
``pandoc``.
27 fc6075dd Agata Murawska
28 77a180f6 Iustin Pop
Note that for pylint, at the current moment the following versions
29 727ee1ec Iustin Pop
must be used::
30 77a180f6 Iustin Pop
31 77a180f6 Iustin Pop
    $ pylint --version
32 77a180f6 Iustin Pop
    pylint 0.21.1,
33 77a180f6 Iustin Pop
    astng 0.20.1, common 0.50.3
34 b2fc7ea1 Michael Hanselmann
35 fc6075dd Agata Murawska
The same with pep8, other versions may give you errors::
36 fc6075dd Agata Murawska
37 fc6075dd Agata Murawska
     $ pep8 --version
38 fc6075dd Agata Murawska
     0.6.1
39 fc6075dd Agata Murawska
40 27e336af Michael Hanselmann
To generate unittest coverage reports (``make coverage``), `coverage
41 27e336af Michael Hanselmann
<http://pypi.python.org/pypi/coverage>`_ needs to be installed.
42 27e336af Michael Hanselmann
43 fc6075dd Agata Murawska
Installation of all dependencies listed here::
44 fc6075dd Agata Murawska
45 fc6075dd Agata Murawska
     $ apt-get install python-setuptools
46 fc6075dd Agata Murawska
     $ apt-get install pandoc python-epydoc graphviz
47 fc6075dd Agata Murawska
     $ cd / && sudo easy_install \
48 fc6075dd Agata Murawska
               sphinx \
49 fc6075dd Agata Murawska
               logilab-astng==0.20.1 \
50 fc6075dd Agata Murawska
               logilab-common==0.50.3 \
51 fc6075dd Agata Murawska
               pylint==0.21.1 \
52 fc6075dd Agata Murawska
               pep8==0.6.1 \
53 fc6075dd Agata Murawska
               coverage
54 fc6075dd Agata Murawska
55 77a180f6 Iustin Pop
For Haskell development, again all things from the quick install
56 77a180f6 Iustin Pop
document, plus:
57 77a180f6 Iustin Pop
58 77a180f6 Iustin Pop
- `haddock <http://www.haskell.org/haddock/>`_, documentation
59 77a180f6 Iustin Pop
  generator (equivalent to epydoc for Python)
60 77a180f6 Iustin Pop
- `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
61 77a180f6 Iustin Pop
  used for documentation (it's source-code pretty-printing)
62 77a180f6 Iustin Pop
- `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
63 3603605a Iustin Pop
  linter (equivalent to pylint for Python), recommended version 1.8 or
64 3603605a Iustin Pop
  above (tested with 1.8.15)
65 77a180f6 Iustin Pop
- the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
66 8e4f6d56 Iustin Pop
  library, version 2.x
67 fd0bc853 Iustin Pop
- ``hpc``, which comes with the compiler, so you should already have
68 fd0bc853 Iustin Pop
  it
69 727ee1ec Iustin Pop
- `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
70 727ee1ec Iustin Pop
  running unit-tests
71 727ee1ec Iustin Pop
72 727ee1ec Iustin Pop
Under Debian Wheezy or later, these can be installed (on top of the
73 727ee1ec Iustin Pop
required ones from the quick install document) via::
74 fd0bc853 Iustin Pop
75 727ee1ec Iustin Pop
  $ apt-get install libghc-quickcheck2-dev hscolour hlint
76 fd0bc853 Iustin Pop
77 727ee1ec Iustin Pop
Or alternatively via ``cabal``::
78 727ee1ec Iustin Pop
79 727ee1ec Iustin Pop
  $ cabal install quickcheck hscolour hlint shelltestrunner
80 77a180f6 Iustin Pop
81 b2fc7ea1 Michael Hanselmann
82 832aef24 Michael Hanselmann
Configuring for development
83 832aef24 Michael Hanselmann
---------------------------
84 832aef24 Michael Hanselmann
85 d17e74b4 Iustin Pop
Run the following command (only use ``PYTHON=...`` if you need to use a
86 d17e74b4 Iustin Pop
different python version)::
87 d17e74b4 Iustin Pop
88 727ee1ec Iustin Pop
  $ ./autogen.sh && \
89 727ee1ec Iustin Pop
    ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
90 558fd122 Michael Hanselmann
91 ef958f2a Iustin Pop
Haskell development notes
92 ef958f2a Iustin Pop
-------------------------
93 ef958f2a Iustin Pop
94 ef958f2a Iustin Pop
There are a few things which can help writing or debugging the Haskell
95 ef958f2a Iustin Pop
code.
96 ef958f2a Iustin Pop
97 ef958f2a Iustin Pop
You can run the Haskell linter :command:`hlint` via::
98 ef958f2a Iustin Pop
99 727ee1ec Iustin Pop
  $ make hlint
100 ef958f2a Iustin Pop
101 3603605a Iustin Pop
This is not enabled by default (as the htools component is
102 3603605a Iustin Pop
optional). The above command will generate both output on the terminal
103 3603605a Iustin Pop
and, if any warnings are found, also an HTML report at
104 ef958f2a Iustin Pop
``doc/hs-lint.html``.
105 ef958f2a Iustin Pop
106 ef958f2a Iustin Pop
When writing or debugging TemplateHaskell code, it's useful to see
107 ef958f2a Iustin Pop
what the splices are converted to. This can be done via::
108 ef958f2a Iustin Pop
109 727ee1ec Iustin Pop
  $ make HEXTRA="-ddump-splices"
110 ef958f2a Iustin Pop
111 ef958f2a Iustin Pop
Due to the way TemplateHaskell works, it's not straightforward to
112 c7ec3025 Iustin Pop
build profiling code. The recommended way is to run ``make hs-prof``,
113 c7ec3025 Iustin Pop
or alternatively the manual sequence is::
114 ef958f2a Iustin Pop
115 727ee1ec Iustin Pop
  $ make clean
116 727ee1ec Iustin Pop
  $ make htools/htools HEXTRA="-osuf .o"
117 727ee1ec Iustin Pop
  $ rm htools/htools
118 727ee1ec Iustin Pop
  $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
119 ef958f2a Iustin Pop
120 ef958f2a Iustin Pop
This will build the binary twice, per the TemplateHaskell
121 ef958f2a Iustin Pop
documentation, the second one with profiling enabled.
122 ef958f2a Iustin Pop
123 94338f0a Michael Hanselmann
124 94338f0a Michael Hanselmann
Packaging notes
125 94338f0a Michael Hanselmann
===============
126 94338f0a Michael Hanselmann
127 94338f0a Michael Hanselmann
Ganeti is mostly developped and tested on `Debian
128 94338f0a Michael Hanselmann
<http://www.debian.org/>`_-based distributions, while still keeping
129 94338f0a Michael Hanselmann
adoptability to other Linux distributions in mind.
130 94338f0a Michael Hanselmann
131 94338f0a Michael Hanselmann
The ``doc/examples/`` directory contains a number of potentially useful
132 94338f0a Michael Hanselmann
scripts and configuration files. Some of them might need adjustment
133 94338f0a Michael Hanselmann
before use.
134 94338f0a Michael Hanselmann
135 94338f0a Michael Hanselmann
``daemon-util``
136 94338f0a Michael Hanselmann
---------------
137 94338f0a Michael Hanselmann
138 94338f0a Michael Hanselmann
This script, in the source code as ``daemons/daemon-util.in``, is used
139 94338f0a Michael Hanselmann
to start/stop Ganeti and do a few other things related to system
140 77a180f6 Iustin Pop
daemons. It is recommended to use ``daemon-util`` also from the system's
141 94338f0a Michael Hanselmann
init scripts. That way the code starting and stopping daemons is shared
142 94338f0a Michael Hanselmann
and future changes have to be made in only one place.
143 94338f0a Michael Hanselmann
144 94338f0a Michael Hanselmann
``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
145 94338f0a Michael Hanselmann
``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
146 94338f0a Michael Hanselmann
not remove support for the ``EXTRA_*_ARGS`` variables for starting
147 94338f0a Michael Hanselmann
daemons. Some parts of Ganeti use them to pass additional arguments when
148 94338f0a Michael Hanselmann
starting a daemon.
149 94338f0a Michael Hanselmann
150 94338f0a Michael Hanselmann
The ``reload_ssh_keys`` function can be adjusted to use another command
151 94338f0a Michael Hanselmann
for reloading the OpenSSH daemon's host keys.
152 94338f0a Michael Hanselmann
153 558fd122 Michael Hanselmann
.. vim: set textwidth=72 :