NAME

       dh-haskell -- debhelper build system class for cabal-based haskell packages

DESCRIPTION

       The dh-haskell package provides a build system for debhelper which can be used in following way:

        %:
               dh $@ --build-system=haskell

       Usually it is all you need to know, and maybe you may want to adjust DEB_BUILD_OPTIONS noopt and nocheck.
       If you want to know precisely what and how is performed, read on implementation section.

IMPLEMENTATION

   HASKELL COMPILER
       The dh-haskell package supports two haskell compilers -- ghc and ghcjs, with only ghc is present in
       official Debian repositories. Each of them have following different properties, that should be well-known
       to anyone familiar with configure scripts.

       bin name of compiler (for example, ghc)

       haddoc
           absolute path to corresponding haddock binary (different compilers have different haddock binary)

       prefix
           Unless overrided, every installation path is under prefix path.

       libdir
           Interface files (for example Writer.hi) and shared library (for example libHSmtl-2.1.3.1-ghc7.8.4.so)
           are installed under libdir path.

       pkgdir
           Every  package  should provide configuration file, like mtl-2.1.3.1.conf which is used by tools, like
           ghc-pkg. It is installed under pkgdir path.

       Actual values for these paths for each compiler can be found in source  of  functions  compiler_compiler.
       You  are  not  meant  to change them, since for packages to be well-used together, during compilation and
       installation they all should be configured with same paths.

       What compiler to use is decided by inspecting  names  of  binary  packages,  which  have  names  is  form
       libcompiler-foo-(dev|doc|prof). Multiple compilers for same source package are NOT supported.

   PREPARATION
       As  mimimal  safety  belt  against cryptic errors, dh-haskell refuses to try build package if it fails to
       find cabal file. If it is found, it is compiled into binary under debian/, which is used  to  orchestrate
       build process.

   CONFIGURATION
       Obliviously,  installation  paths  of package depends on it's upstream name and version. Upstream name is
       detected by inspecting debian/copyright DEP5 file, falling back on source package name. Upstream  version
       is deduced from debian version in debian/changelog.

       Package  is  configured  with  profiling  enabled  only  if  there  is  binary  package  with  name  like
       libcompiler-pkgname-prof.

       If compiler is ghc, LDFLAGS, suggested by dpkg-buildpackage are forwarded to ghc, that  harden  generated
       binaries and fix corresponding lintian warning.

       If for some reason ghci is not availiable, preprocessor token "DEBIAN_NO_GHCI" is defined.

       Value  of enviroment variable "GHC_CONFIGURE_ARGS" is passed unmodified at configuration stage. It may be
       useful, if you need enable or disable flags due some  complicated  logic,  implemented  in  debian/rules.
       Please, don't abuse it.

       If  options noopt or nocheck are present in "DEB_BUILD_OPTIONS", then optimization or tests are disabled,
       correspondingly.

   BUILDING
       Building of library is  trivial  and  is  essence  equivalent  to  "cabal  build".   If  haddock  binary,
       corresponding  to  current  compiler  is  present  (FIXME:  When  it does not?), it is used to also build
       hyperlinked documentation.

   TESTING
       Unless tests were disabled at configuration stage, they are run.

   INSTALLATION
       First, compiled objects are copied into temporary directory, and then dispatached, to which package  what
       belong.  See  "do_dispatch" in source for exact filename patterns. If file does not match any pattern, it
       is installed into non-library binary package, if any, or in -dev otherwise.

       Separately pkg-config file is generated (ex. bool-extras-0.4.0.conf) and installed for dev binary package
       under compiler pkgdir. This file contains package build indentifier, used to generate  "haskell:Provides"
       substitute  variable.  It also contains dependencies, used to generate "haskell:Depends" for dev and prof
       packages, and "haskell:Recommends" for doc packages.

       Such cabal build identifiers looks like bool-extras-HASH or base-HASH, where HASH is  32  heximal  digits
       string.    For    purposed    of    debian    packaging,    we    convert    it    to    something   like
       "libghc-bool-extras-(dev|prof)-SHORT_HASH", where SHORT_HASH is first 5 digits of HASH.

       Since in most cases description of binary packages differs slightly, it is written once in source package
       X-Description field and automaticaly substituted into binary packages. This transformation  performed  in
       "substitute_description".

perl v5.22.1                                       2015-07-09              Debian::Debhel...system::haskell(3pm)