Document some useful Haskell tips

This improves devnotes.rst with some tricks for Haskell development,
and additionally it does two Makefile improvements:

- properly document lib/_vcsversion.py as a requirement for
  Constants.hs (but do not require rebuild when updated)
- move HEXTRA at the end of the GHC invocation, so any command line
  options will indeed override the built-in ones (especially -osuf)

Signed-off-by: Iustin Pop <iustin@google.com>
Reviewed-by: Michael Hanselmann <hansmi@google.com>

diff --git a/Makefile.am b/Makefile.am
index 9cc5b80..412e803 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -499,9 +499,10 @@ $(HS_ALL_PROGS): %: %.hs $(HS_LIB_SRCS) $(HS_BUILT_SRCS) Makefile
          exit 1; \
        fi
        BINARY=$(@:htools/%=%); $(GHC) --make \
-         $(HFLAGS) $(HEXTRA) \
+         $(HFLAGS) \
          $(HTOOLS_NOCURL) $(HTOOLS_PARALLEL3) \
-         -osuf $$BINARY.o -hisuf $$BINARY.hi $@
+         -osuf $$BINARY.o -hisuf $$BINARY.hi \
+         $(HEXTRA) $@
 
 # for the htools/test binary, we need to enable profiling/coverage
 htools/test: HEXTRA=-fhpc -Wwarn -fno-warn-missing-signatures \
@@ -920,7 +921,8 @@ htools/Ganeti/HTools/Version.hs: htools/Ganeti/HTools/Version.hs.in vcs-version
        sed -e "s/%ver%/$$VCSVER/" < $< > $@
 
 htools/Ganeti/Constants.hs: htools/Ganeti/Constants.hs.in \
-       lib/constants.py lib/_autoconf.py $(CONVERT_CONSTANTS)
+       lib/constants.py lib/_autoconf.py $(CONVERT_CONSTANTS) \
+       | lib/_vcsversion.py
        set -e; \
        { cat $< ; PYTHONPATH=. $(CONVERT_CONSTANTS); } > $@
 

diff --git a/doc/devnotes.rst b/doc/devnotes.rst
index f9646fb..9c11eb9 100644 (file)
--- a/doc/devnotes.rst
+++ b/doc/devnotes.rst
@@ -59,6 +59,37 @@ different python version)::
   ./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 it gets many false positives, and
+thus the normal output is not “clean”. The above command will generate
+both output on the terminal and also a 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::
+
+  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
 ===============