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