X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/c7ec30256e47ed749d2a280805afe605c0e56453..5e09a3098d47371b7d105e7f5f571a72532a03d7:/doc/devnotes.rst diff --git a/doc/devnotes.rst b/doc/devnotes.rst index 2fcc7d8..c5594e8 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,27 +118,58 @@ 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 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. +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 +`_). Packaging notes =============== -Ganeti is mostly developped and tested on `Debian +Ganeti is mostly developed and tested on `Debian `_-based distributions, while still keeping -adoptability to other Linux distributions in mind. +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