bionic (3) Debian::Debhelper::Buildsystem::haskell.3pm.gz

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".