.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Debian::Debhelper::Buildsystem::haskell 3pm"
.TH Debian::Debhelper::Buildsystem::haskell 3pm "2016-09-28" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh\-haskell \-\- debhelper build system class for cabal\-based haskell packages
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The dh-haskell package provides a build system for debhelper which can be used
in following way:
.PP
.Vb 2
\& %:
\&        dh $@ \-\-build\-system=haskell
.Ve
.PP
Usually it is all you need to know, and maybe you may want to adjust
\&\s-1DEB_BUILD_OPTIONS \s0\fInoopt\fR and \fInocheck\fR.  If you want to know precisely what
and how is performed, read on implementation section.
.SH "IMPLEMENTATION"
.IX Header "IMPLEMENTATION"
.SS "\s-1HASKELL COMPILER\s0"
.IX Subsection "HASKELL COMPILER"
The dh-haskell package supports two haskell compilers \*(-- \fBghc\fR and \fBghcjs\fR,
with only \fBghc\fR is present in official Debian repositories. Each of them have
following different properties, that should be well-known to anyone familiar
with \fIconfigure\fR scripts.
.IP "\fIbin\fR" 4
.IX Item "bin"
name of compiler (for example, \fBghc\fR)
.IP "\fIhaddoc\fR" 4
.IX Item "haddoc"
absolute path to corresponding haddock binary (different compilers have
different haddock binary)
.IP "\fIprefix\fR" 4
.IX Item "prefix"
Unless overridden, every installation path is under prefix path.
.IP "\fIlibdir\fR" 4
.IX Item "libdir"
Interface files (for example \fIWriter.hi\fR) and shared library (for example
\&\fIlibHSmtl\-2.1.3.1\-ghc7.8.4.so\fR) are installed under libdir path.
.IP "\fIpkgdir\fR" 4
.IX Item "pkgdir"
Every package should provide configuration file, like \fImtl\-2.1.3.1.conf\fR which
is used by tools, like \fBghc-pkg\fR. It is installed under pkgdir path.
.PP
Actual values for these paths for each \fIcompiler\fR can be found in source of
functions \fBcompiler\fR_\fIcompiler\fR. 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.
.PP
What compiler to use is decided by inspecting names of binary packages, which
have names is form lib\fIcompiler\fR\-foo\-(dev|doc|prof). Multiple compilers
for same source package are \s-1NOT\s0 supported.
.SS "\s-1PREPARATION\s0"
.IX Subsection "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 \fIdebian/\fR,
which is used to orchestrate build process.
.SS "\s-1CONFIGURATION\s0"
.IX Subsection "CONFIGURATION"
Obliviously, installation paths of package depends on it's upstream name
and version. Upstream name is detected by inspecting \fIdebian/copyright\fR
\&\s-1DEP5\s0 file, falling back on source package name. Upstream version
is deduced from debian version in \fIdebian/changelog\fR.
.PP
Package is configured with profiling enabled only if there is binary package with name like
lib\fIcompiler\fR\-\fIpkgname\fR\-prof.
.PP
If compiler is ghc, \s-1LDFLAGS,\s0 suggested by dpkg-buildpackage are forwarded to
ghc, that harden generated binaries and fix corresponding lintian warning.
.PP
If for some reason ghci is not available, preprocessor token \f(CW\*(C`DEBIAN_NO_GHCI\*(C'\fR is
defined.
.PP
Value of environment variable \f(CW\*(C`GHC_CONFIGURE_ARGS\*(C'\fR is passed unmodified at configuration
stage. It may be useful, if you need enable or disable flags due some complicated logic,
implemented in \fIdebian/rules\fR. \fBPlease\fR, don't abuse it.
.PP
If options \fInoopt\fR or \fInocheck\fR are present in \f(CW\*(C`DEB_BUILD_OPTIONS\*(C'\fR,
then optimization or tests are disabled, correspondingly.
.SS "\s-1BUILDING\s0"
.IX Subsection "BUILDING"
Building of library is trivial and is essence equivalent to \f(CW\*(C`cabal build\*(C'\fR.  If
haddock binary, corresponding to current compiler is present
(\fB\s-1FIXME:\s0 When it does not?\fR), it is used to also build hyperlinked documentation.
.SS "\s-1TESTING\s0"
.IX Subsection "TESTING"
Unless tests were disabled at configuration stage, they are run.
.SS "\s-1INSTALLATION\s0"
.IX Subsection "INSTALLATION"
First, compiled objects are copied into temporary directory, and then
dispatached, to which package what belong. See \f(CW\*(C`do_dispatch\*(C'\fR 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 \fI\-dev\fR otherwise.
.PP
Separately pkg-config file is generated (ex. \fIbool\-extras\-0.4.0.conf\fR) and
installed for dev binary package under compiler pkgdir. This file contains
package build indentifier, used to generate \f(CW\*(C`haskell:Provides\*(C'\fR substitute
variable. It also contains dependencies, used to generate \f(CW\*(C`haskell:Depends\*(C'\fR
for \fIdev\fR and \fIprof\fR packages, and \f(CW\*(C`haskell:Recommends\*(C'\fR for \fIdoc\fR packages.
.PP
Such cabal build identifiers looks like bool\-extras\-\fI\s-1HASH\s0\fR or base\-\fI\s-1HASH\s0\fR,
where \fI\s-1HASH\s0\fR is 32 heximal digits string. For purposed of debian packaging, we
convert it to something like \f(CW\*(C`libghc\-bool\-extras\-(dev|prof)\-\f(CISHORT_HASH\f(CW\*(C'\fR,
where \fI\s-1SHORT_HASH\s0\fR is first 5 digits of \fI\s-1HASH\s0\fR.
.PP
Since in most cases description of binary packages differs slightly,
it is written once in source package \fIX\-Description\fR field and
automatically substituted into binary packages. This transformation
performed in \f(CW\*(C`substitute_description\*(C'\fR.