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 overridden, 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 available, preprocessor token "DEBIAN_NO_GHCI" is defined.

       Value of environment 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 automatically substituted into binary packages. This transformation performed in
       "substitute_description".

perl v5.24.1                                       2016-09-28              Debian::Debhel...system::haskell(3pm)