X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/94338f0ab62226c9329d8f829146acb44b5f0ec8..43c16a8a1adfd543751fcaf60ad4c8e04cf83688:/doc/devnotes.rst
diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index e794469..48544fb 100644
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -1,32 +1,102 @@
Developer notes
===============
+.. highlight:: shell-example
+
Build dependencies
------------------
-Most dependencies from :doc:`install-quick`, plus:
+Most dependencies from :doc:`install-quick`, plus (for Python):
- `GNU make `_
- `GNU tar `_
- `Gzip `_
-- `Docbook tools `_
- (docbook2html and docbook2man)
+- `pandoc `_
- `python-sphinx `_
(tested with version 0.6.1)
- `graphviz `_
+- the `en_US.UTF-8` locale must be enabled on the system
+- `pylint `_ and its associated
+ dependencies
+- `pep8 `_
+
+Note that for pylint, at the current moment the following versions
+must be used::
+
+ $ pylint --version
+ pylint 0.21.1,
+ astng 0.20.1, common 0.50.3
+
+To generate unittest coverage reports (``make coverage``), `coverage
+`_ needs to be installed.
+
+For Haskell development, again all things from the quick install
+document, plus:
+
+- `haddock `_, documentation
+ generator (equivalent to epydoc for Python)
+- `HsColour `_, again
+ used for documentation (it's source-code pretty-printing)
+- `hlint `_, a source code
+ linter (equivalent to pylint for Python), recommended version 1.8 or
+ above (tested with 1.8.15)
+- the `QuickCheck `_
+ library, version 2.x
+- ``hpc``, which comes with the compiler, so you should already have
+ it
+- `shelltestrunner `_, used for
+ running unit-tests
+
+Under Debian Wheezy or later, these can be installed (on top of the
+required ones from the quick install document) via::
+
+ $ apt-get install libghc-quickcheck2-dev hscolour hlint
+
+Or alternatively via ``cabal``::
+
+ $ cabal install quickcheck 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 PYTHON=python2.4 \
- --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
+ $ ./autogen.sh && \
+ ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
+
+Haskell development notes
+-------------------------
+
+There are a few things which can help writing or debugging the Haskell
+code.
+
+You can run the Haskell linter :command:`hlint` via::
+
+ $ make hlint
+
+This is not enabled by default (as the htools component is
+optional). The above command will generate both output on the terminal
+and, if any warnings are found, also an HTML report at
+``doc/hs-lint.html``.
+
+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"
+
+Due to the way TemplateHaskell works, it's not straightforward to
+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"
+
+This will build the binary twice, per the TemplateHaskell
+documentation, the second one with profiling enabled.
Packaging notes
@@ -45,7 +115,7 @@ before use.
This script, in the source code as ``daemons/daemon-util.in``, is used
to start/stop Ganeti and do a few other things related to system
-daemons. Is is recommended to use ``daemon-util`` also from the system's
+daemons. It is recommended to use ``daemon-util`` also from the system's
init scripts. That way the code starting and stopping daemons is shared
and future changes have to be made in only one place.