X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/62947ebb897cc60ed35cf52f627dd4b77a3453d8..5e09a3098d47371b7d105e7f5f571a72532a03d7:/doc/devnotes.rst

diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index 8a81ab7..c5594e8 100644
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -1,16 +1,94 @@
 Developer notes
 ===============
 
+.. highlight:: shell-example
+
 Build dependencies
 ------------------
 
-Most dependencies from INSTALL, plus:
- - docbook2html, docbook2man from Docbook tools
-   http://sources.redhat.com/docbook-tools/
- - python-sphinx (tested with version 0.6.1) from
-   http://sphinx.pocoo.org/
- - graphviz
-   http://www.graphviz.org/
+Most dependencies from :doc:`install-quick`, including ``qemu-img``
+(marked there as optional) plus (for Python):
+
+- `GNU make <http://www.gnu.org/software/make/>`_
+- `GNU tar <http://www.gnu.org/software/tar/>`_
+- `Gzip <http://www.gnu.org/software/gzip/>`_
+- `pandoc <http://johnmacfarlane.net/pandoc/>`_
+- `python-epydoc <http://epydoc.sourceforge.net/>`_
+- `python-sphinx <http://sphinx.pocoo.org/>`_
+  (tested with version 1.1.3)
+- `graphviz <http://www.graphviz.org/>`_
+- the `en_US.UTF-8` locale must be enabled on the system
+- `pylint <http://www.logilab.org/857>`_ and its associated
+  dependencies
+- `pep8 <https://github.com/jcrocholl/pep8/>`_
+
+For older developement (Ganeti < 2.4) ``docbook`` was used instead
+``pandoc``.
+
+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
+
+The same with pep8, other versions may give you errors::
+
+     $ pep8 --version
+     1.2
+
+To generate unittest coverage reports (``make coverage``), `coverage
+<http://pypi.python.org/pypi/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:
+
+- `haddock <http://www.haskell.org/haddock/>`_, documentation
+  generator (equivalent to epydoc for Python)
+- `HsColour <http://hackage.haskell.org/package/hscolour>`_, again
+  used for documentation (it's source-code pretty-printing)
+- `hlint <http://community.haskell.org/~ndm/hlint/>`_, a source code
+  linter (equivalent to pylint for Python), recommended version 1.8 or
+  above (tested with 1.8.15)
+- the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
+  library, version 2.x
+- the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
+  1.2.x)
+- the `test-framework
+  <http://batterseapower.github.com/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 <http://joyful.com/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::
+
+  $ 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
+
+Or alternatively via ``cabal``::
+
+  $ cabal install QuickCheck HUnit \
+          test-framework test-framework-quickcheck2 test-framework-hunit \
+          hscolour hlint shelltestrunner
 
 
 Configuring for development
@@ -19,6 +97,100 @@ Configuring for development
 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.
+
+The binary files generated by compilation and the profiling/coverage
+files can "break" tab-completion in the sources; they can be ignored,
+for example, in bash via ``.bashrc``::
+
+  FIGNORE='.o:.hi:.prof_o:.tix'
+
+or in emacs via ``completion-ignored-extensions`` (run ``M-x
+customize-var completion-ignored-extensions``).
+
+Running individual tests
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When developing code, running the entire test suite can be
+slow. Running individual tests is possible easily for unit-tests, less
+so for shell-tests (but these are faster, so it shouldn't be needed).
+
+For Python tests::
+
+  $ export PYTHONPATH=$PWD
+  $ python ./test/ganeti.%mytest%
+
+For Haskell tests::
+
+  $ make htest/test && ./htest/test -t %pattern%
+
+Where ``pattern`` can be a simple test pattern (e.g. ``comma``,
+matching any test whose name contains ``comma``), a test pattern
+denoting a group (ending with a slash, e.g. ``Utils/``), or more
+complex glob pattern. For more details, see the documentation (on the
+`test-framework homepage
+<http://batterseapower.github.com/test-framework/>`_).
+
+Packaging notes
+===============
+
+Ganeti is mostly developed and tested on `Debian
+<http://www.debian.org/>`_-based distributions, while still keeping
+adaptability to other Linux distributions in mind.
+
+The ``doc/examples/`` directory contains a number of potentially useful
+scripts and configuration files. Some of them might need adjustment
+before use.
+
+``daemon-util``
+---------------
+
+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. 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.
+
+``daemon-util`` reads extra arguments from variables (``*_ARGS``) in
+``/etc/default/ganeti``. When modifying ``daemon-util``, keep in mind to
+not remove support for the ``EXTRA_*_ARGS`` variables for starting
+daemons. Some parts of Ganeti use them to pass additional arguments when
+starting a daemon.
+
+The ``reload_ssh_keys`` function can be adjusted to use another command
+for reloading the OpenSSH daemon's host keys.
+
+.. vim: set textwidth=72 :