X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/8e09e80131f6b14dfb3d6a65c49dbb92dbebe2aa..714022e477dc8443ebc55edbc4b71d70e7c29ba5:/doc/devnotes.rst diff --git a/doc/devnotes.rst b/doc/devnotes.rst index 7721ecd..df89328 100644 --- a/doc/devnotes.rst +++ b/doc/devnotes.rst @@ -16,40 +16,46 @@ Most dependencies from :doc:`install-quick`, including ``qemu-img`` - `python-epydoc `_ - `python-sphinx `_ (tested with version 1.1.3) +- `python-mock `_ + (tested with version 1.0.1) - `graphviz `_ - the `en_US.UTF-8` locale must be enabled on the system - `pylint `_ and its associated dependencies - `pep8 `_ +- `PyYAML `_ -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 `_ 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 @@ -61,7 +67,7 @@ document, plus: 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) + above (tested with 1.8.43) - the `QuickCheck `_ library, version 2.x - the `HUnit `_ library (tested with @@ -69,11 +75,13 @@ document, plus: - the `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 `_, used for running shell-based unit-tests +- `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:: @@ -82,13 +90,14 @@ 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 @@ -107,6 +116,11 @@ 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 ------------------------- @@ -127,14 +141,29 @@ what the splices are converted to. This can be done via:: $ 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. @@ -152,25 +181,47 @@ 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). +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/ganeti.%mytest% + $ python ./test/py/ganeti.%mytest% For Haskell tests:: - $ make htest/test && ./htest/test -t %pattern% + $ 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, see the documentation (on the -`test-framework homepage +complex glob pattern. For more details, search for glob patterns in +the documentation of `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 ===============