kvm: Use -display none rather than -nographic

[ganeti-local] / doc / devnotes.rst

diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index 718ca75..941e548 100644 (file)
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -29,14 +29,16 @@ Note that for pylint, at the current moment the following versions
 must be used::
 
     $ pylint --version
 must be used::
 
     $ pylint --version

-    pylint 0.21.1,
-    astng 0.20.1, common 0.50.3
+    pylint 0.25.1,
+    astng 0.23.1, common 0.58.0

 
 The same with pep8, other versions may give you errors::
 
      $ pep8 --version
      1.2
 
 
 The same with pep8, other versions may give you errors::
 
      $ pep8 --version
      1.2
 

+Both these versions are the ones shipped with Debian Wheezy.
+

 To generate unittest coverage reports (``make coverage``), `coverage
 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
 
 To generate unittest coverage reports (``make coverage``), `coverage
 <http://pypi.python.org/pypi/coverage>`_ needs to be installed.
 

@@ -46,9 +48,9 @@ Installation of all dependencies listed here::
      $ apt-get install pandoc python-epydoc graphviz
      $ cd / && sudo easy_install \
                sphinx \
      $ 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 \
+               logilab-astng==0.25.1 \
+               logilab-common==0.58.0 \
+               pylint==0.23.1 \

                pep8==1.2 \
                coverage
 
                pep8==1.2 \
                coverage
 

@@ -69,11 +71,13 @@ document, plus:
 - the `test-framework
   <http://batterseapower.github.com/test-framework/>`_ libraries,
   tested versions: ``test-framework``: 0.6, ``test-framework-hunit``:
 - 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
 - ``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::
 
 Under Debian Wheezy or later, these can be installed (on top of the
 required ones from the quick install document) via::

@@ -82,11 +86,14 @@ required ones from the quick install document) via::
         libghc-test-framework-dev \
         libghc-test-framework-quickcheck2-dev \
         libghc-test-framework-hunit-dev \
         libghc-test-framework-dev \
         libghc-test-framework-quickcheck2-dev \
         libghc-test-framework-hunit-dev \

+        libghc-temporary-dev \

         hscolour hlint
 
 Or alternatively via ``cabal``::
 
         hscolour hlint
 
 Or alternatively via ``cabal``::
 

-  $ cabal install quickcheck hscolour hlint shelltestrunner
+  $ cabal install QuickCheck HUnit \
+          test-framework test-framework-quickcheck2 test-framework-hunit \
+          temporary hscolour hlint shelltestrunner

 
 
 Configuring for development
 
 
 Configuring for development

@@ -98,6 +105,13 @@ different python version)::
   $ ./autogen.sh && \
     ./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
 
   $ ./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.
+

 Haskell development notes
 -------------------------
 
 Haskell development notes
 -------------------------
 

@@ -118,25 +132,71 @@ what the splices are converted to. This can be done via::
 
   $ make HEXTRA="-ddump-splices"
 
 
   $ 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
 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.
 
 
 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/py/ganeti.%mytest%
+
+For Haskell tests::
+
+  $ make test/hs/htest && ./test/hs/htest -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
 ===============
 
 
 Packaging notes
 ===============
 

-Ganeti is mostly developped and tested on `Debian
+Ganeti is mostly developed and tested on `Debian

 <http://www.debian.org/>`_-based distributions, while still keeping
 <http://www.debian.org/>`_-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
 
 The ``doc/examples/`` directory contains a number of potentially useful
 scripts and configuration files. Some of them might need adjustment