Fix pylint breakage due to unused var in gnt_cluster

[ganeti-local] / doc / devnotes.rst

diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index 898d03a..014f2cd 100644 (file)
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -1,35 +1,136 @@
 Developer notes
 ===============
 
 Developer notes
 ===============
 

+.. highlight:: shell-example
+

 Build dependencies
 ------------------
 
 Build dependencies
 ------------------
 

-Most dependencies from :doc:`install-quick`, plus:
+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/>`_
 
 - `GNU make <http://www.gnu.org/software/make/>`_
 - `GNU tar <http://www.gnu.org/software/tar/>`_
 - `Gzip <http://www.gnu.org/software/gzip/>`_

-- `Docbook tools <http://sources.redhat.com/docbook-tools/>`_
-  (docbook2html and docbook2man)
+- `pandoc <http://johnmacfarlane.net/pandoc/>`_
+- `python-epydoc <http://epydoc.sourceforge.net/>`_

 - `python-sphinx <http://sphinx.pocoo.org/>`_
 - `python-sphinx <http://sphinx.pocoo.org/>`_

-  (tested with version 0.6.1)
+  (tested with version 1.1.3)

 - `graphviz <http://www.graphviz.org/>`_
 - the `en_US.UTF-8` locale must be enabled on the system
 - `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.
 
 
 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
 ---------------------------
 
 
 Configuring for development
 ---------------------------
 

-.. highlight:: sh
-

 Run the following command (only use ``PYTHON=...`` if you need to use a
 different python version)::
 
 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
+-------------------------
+
+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.

 
 
 Packaging notes
 
 
 Packaging notes

@@ -48,7 +149,7 @@ before use.
 
 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
 
 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. Is is recommended to use ``daemon-util`` also from the system's
+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.
 
 init scripts. That way the code starting and stopping daemons is shared
 and future changes have to be made in only one place.