X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/3603605abbc93e1d6dc3be60f118726d621f5377..3008f56cbb58ef3d70db6006d89eb279b2deb165:/doc/devnotes.rst
diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index 2d2a2cf..014f2cd 100644
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -1,33 +1,57 @@
Developer notes
===============
+.. highlight:: shell-example
+
Build dependencies
------------------
-Most dependencies from :doc:`install-quick`, plus (for Python):
+Most dependencies from :doc:`install-quick`, including ``qemu-img``
+(marked there as optional) plus (for Python):
- `GNU make `_
- `GNU tar `_
- `Gzip `_
- `pandoc `_
+- `python-epydoc `_
- `python-sphinx `_
- (tested with version 0.6.1)
+ (tested with version 1.1.3)
- `graphviz `_
- the `en_US.UTF-8` locale must be enabled on the system
- `pylint `_ and its associated
dependencies
- `pep8 `_
+For older developement (Ganeti < 2.4) ``docbook`` was used instead
+``pandoc``.
+
Note that for pylint, at the current moment the following versions
-need to be used::
+must be used::
$ pylint --version
pylint 0.21.1,
astng 0.20.1, common 0.50.3
+The same with pep8, other versions may give you errors::
+
+ $ pep8 --version
+ 1.2
+
To generate unittest coverage reports (``make coverage``), `coverage
`_ needs to be installed.
+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 \
+ pep8==1.2 \
+ coverage
+
For Haskell development, again all things from the quick install
document, plus:
@@ -40,25 +64,41 @@ document, plus:
above (tested with 1.8.15)
- the `QuickCheck `_
library, version 2.x
+- the `HUnit `_ library (tested with
+ 1.2.x)
+- the `test-framework
+ `_ libraries,
+ tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
+ 0.2.7, ``test-framework-quickcheck2``: 0.2.12
- ``hpc``, which comes with the compiler, so you should already have
it
+- `shelltestrunner `_, used for
+ running shell-based unit-tests
+
+Under Debian Wheezy or later, these can be installed (on top of the
+required ones from the quick install document) via::
-Under Debian, these can be installed (on top of the required ones from
-the quick install document) via::
+ $ 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
- apt-get install libghc-quickcheck2-dev hscolour hlint
+Or alternatively via ``cabal``::
+
+ $ cabal install QuickCheck HUnit \
+ test-framework test-framework-quickcheck2 test-framework-hunit \
+ hscolour hlint shelltestrunner
Configuring for development
---------------------------
-.. highlight:: sh
-
Run the following command (only use ``PYTHON=...`` if you need to use a
different python version)::
- ./autogen.sh && \
- ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
+ $ ./autogen.sh && \
+ ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
Haskell development notes
-------------------------
@@ -68,7 +108,7 @@ code.
You can run the Haskell linter :command:`hlint` via::
- make hlint
+ $ make hlint
This is not enabled by default (as the htools component is
optional). The above command will generate both output on the terminal
@@ -78,15 +118,16 @@ and, if any warnings are found, also an HTML report at
When writing or debugging TemplateHaskell code, it's useful to see
what the splices are converted to. This can be done via::
- make HEXTRA="-ddump-splices"
+ $ make HEXTRA="-ddump-splices"
Due to the way TemplateHaskell works, it's not straightforward to
-build profiling code. The recommended way is::
+build profiling code. The recommended way is to run ``make hs-prof``,
+or alternatively the manual sequence is::
- make clean
- make htools/htools HEXTRA="-osuf .o"
- rm htools/htools
- make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
+ $ make clean
+ $ make htools/htools HEXTRA="-osuf .o"
+ $ rm htools/htools
+ $ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
This will build the binary twice, per the TemplateHaskell
documentation, the second one with profiling enabled.