- `python-epydoc <http://epydoc.sourceforge.net/>`_
- `python-sphinx <http://sphinx.pocoo.org/>`_
(tested with version 1.1.3)
+- `python-mock <http://www.voidspace.org.uk/python/mock/>`_
+ (tested with version 1.0.1)
- `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/>`_
+- `PyYAML <http://pyyaml.org/>`_
-For older developement (Ganeti < 2.4) ``docbook`` was used instead
+For older developement (Ganeti < 2.4) ``docbook`` was used instead of
``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
+ pylint 0.26.0,
+ astng 0.24.1, common 0.58.3
The same with pep8, other versions may give you errors::
$ pep8 --version
- 1.2
+ 1.3.3
+
+Both these versions are the ones shipped with Ubuntu 13.04.
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 \
+ $ apt-get install python-setuptools automake git fakeroot
+ $ apt-get install pandoc python-epydoc graphviz python-sphinx
+ $ apt-get install python-yaml
+ $ cd / && easy_install \
+ logilab-astng==0.24.1 \
+ logilab-common==0.58.3 \
+ pylint==0.26.0 \
+ pep8==1.3.3 \
+ mock==1.0.1 \
coverage
For Haskell development, again all things from the quick install
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)
+ above (tested with 1.8.43)
- the `QuickCheck <http://hackage.haskell.org/package/QuickCheck>`_
library, version 2.x
- the `HUnit <http://hunit.sourceforge.net/>`_ library (tested with
- 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
+ 0.2.7, ``test-framework-quickcheck2``: 0.2.12.1
- ``hpc``, which comes with the compiler, so you should already have
it
- `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
running shell-based unit-tests
+- `temporary <https://github.com/batterseapower/temporary/>`_ library,
+ tested with version 1.1.2.3
Under Debian Wheezy or later, these can be installed (on top of the
required ones from the quick install document) via::
libghc-test-framework-dev \
libghc-test-framework-quickcheck2-dev \
libghc-test-framework-hunit-dev \
+ libghc-temporary-dev shelltestrunner \
hscolour hlint
Or alternatively via ``cabal``::
$ cabal install QuickCheck HUnit \
test-framework test-framework-quickcheck2 test-framework-hunit \
- hscolour hlint shelltestrunner
+ temporary hscolour hlint shelltestrunner
Configuring for development
$ ./autogen.sh && \
./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
+Note that doing development on a machine which already has Ganeti
+installed is problematic, as ``PYTHONPATH`` behaviour can be confusing
+(see Issue 170 for a bit of history/details; in general it works if
+the installed and developed versions are very similar, and/or if
+PYTHONPATH is customised correctly). As such, in general it's
+recommended to use a "clean" machine for ganeti development.
+
+Style guide
+-----------
+
+Please adhere to the :doc:`dev-codestyle` while writing code for Ganeti.
+
Haskell development notes
-------------------------
$ make HEXTRA="-ddump-splices"
+Or, more interactively::
+
+ $ ghci
+ λ> :set -ddump-splices
+ λ> :l src/Ganeti/Objects.hs
+
+And you will get the spliced code as the module is loaded.
+
+To build profiling code you must install the ``ghc-prof`` (or
+``gch6-prof``) package, and all the relevant libraries with their
+``-prof`` counterparts. If installing libraries through cabal the config
+file should include ``library-profiling: True`` or the ``-p`` flag
+should be used. Any library already installed can be updated by passing
+``--reinstall`` as well.
+
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"
+ $ make src/htools HEXTRA="-osuf .o"
+ $ rm src/htools
+ $ make src/htools HEXTRA="-osuf .prof_o -prof -auto-all"
This will build the binary twice, per the TemplateHaskell
documentation, the second one with profiling enabled.
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. There are different
+Makefile targets for running individual Python and Haskell tests.
+
+For Python tests::
+
+ $ export PYTHONPATH=$PWD
+ $ python ./test/py/ganeti.%mytest%
+
+For Haskell tests::
+
+ $ make hs-test-%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, search for glob patterns in
+the documentation of `test-framework
+<http://batterseapower.github.com/test-framework/>`_).
+
+For individual Haskell shelltests::
+
+ $ make hs-shell-%name%
+
+which runs the test ``test/hs/shelltests/htools-%name%.test``. For
+example, to run the test ``test/hs/shelltests/htools-balancing.test``,
+use::
+
+ $ make hs-shell-balancing
+
+For combined Haskell shelltests::
+
+ $ make hs-shell-{%name1%,%name2%,...}
+
+for example::
+
+ $ make hs-shell-{balancing,basic}
+
+Checking for the correct style of the NEWS file is also possible, by running::
+
+ $ make check-news
+
Packaging notes
===============