Distribution.Simple'>
Distribution.Make'>
License'>
Extension'>
BuildType'>
alex'>
autoconf'>
c2hs'>
cpphs'>
greencard'>
haddock'>
HsColour'>
happy'>
HackageDB'>
pkg-config'>
]>
Common Architecture for Building Applications and LibrariesUser's GuideThe Cabal aims to simplify the
distribution of Haskell
software. It does this by specifying a number of interfaces between
package authors, builders and users, as well as providing a library
implementing these interfaces.PackagesA package is the unit of distribution
for the Cabal. Its purpose, when installed, is to make available
either or both of:A library, exposing a number of Haskell modules. A library
may also contain hidden modules, which
are used internally but not available to clients.Hugs doesn't support module hiding.One or more Haskell programs.However having both a library and executables in a package
does not work very well; if the executables depend on the library,
they must explicitly list all the modules they directly or
indirectly import from that library.Internally, the package may consist of much more than a
bunch of Haskell modules: it may also have C source code and
header files, source code meant for preprocessing, documentation,
test cases, auxiliary tools etc.A package is identified by a globally-unique
package name, which consists of one or
more alphanumeric words separated by hyphens. To avoid ambiguity,
each of these words should contain at least one letter.
Chaos will result if two distinct packages with the
same name are installed on the same system, but there is not
yet a mechanism for allocating these names.
A particular version of the package is distinguished by a
version number, consisting of a sequence
of one or more integers separated by dots. These can be combined
to form a single text string called the package
ID, using a hyphen to separate the name from the
version, e.g. HUnit-1.1.Packages are not part of the Haskell language;
they simply populate the hierarchical space of module names.
In GHC 6.6 and later a program may contain multiple modules
with the same name if they come from separate packages; in all
other current Haskell systems packages may not overlap in the
modules they provide, including hidden modules.Creating a packageSuppose you have a directory hierarchy containing the source
files that make up your package. You will need to add two more
files to the root directory of the package:package.cabala text file containing a package description
(for details of the syntax of this file, see
), andSetup.hs or
Setup.lhsa single-module Haskell program to perform various
setup tasks (with the interface described in
). This module should import only
modules that will be present in all Haskell implementations,
including modules of the Cabal library. In most cases it
will be trivial, calling on the Cabal library to do most of
the work.Once you have these, you can create a source bundle of this
directory for distribution. Building of the package is discussed in
.A package containing a simple libraryThe HUnit package contains a file HUnit.cabal
containing:
Name: HUnit
Version: 1.1.1
Cabal-Version: >= 1.2
License: BSD3
License-File: LICENSE
Author: Dean Herington
Homepage: http://hunit.sourceforge.net/
Category: Testing
Synopsis: A unit testing framework for Haskell
Library
Build-Depends: base
Exposed-modules:
Test.HUnit.Base, Test.HUnit.Lang, Test.HUnit.Terminal,
Test.HUnit.Text, Test.HUnit
Extensions: CPP
and the following Setup.hs:
import Distribution.Simple
main = defaultMainA package containing executable programs
Name: TestPackage
Version: 0.0
Cabal-Version: >= 1.2
License: BSD3
Author: Angela Author
Synopsis: Small package with two programs
Build-Type: Simple
Executable program1
Build-Depends: HUnit
Main-Is: Main.hs
Hs-Source-Dirs: prog1
Executable program2
Main-Is: Main.hs
Build-Depends: HUnit
Hs-Source-Dirs: prog2
Other-Modules: Utils
with Setup.hs the same as above.A package containing a library and executable programs
Name: TestPackage
Version: 0.0
Cabal-Version: >= 1.2
License: BSD3
Author: Angela Author
Synopsis: Package with library and two programs
Build-Type: Simple
Library
Build-Depends: HUnit
Exposed-Modules: A, B, C
Executable program1
Main-Is: Main.hs
Hs-Source-Dirs: prog1
Other-Modules: A, B
Executable program2
Main-Is: Main.hs
Hs-Source-Dirs: prog2
Other-Modules: A, C, Utils
with Setup.hs the same as above.
Note that any library modules required (directly or indirectly)
by an executable must be listed again.The trivial setup script used in these examples uses
the simple build infrastructure
provided by the Cabal library (see &Simple;).
The simplicity lies in its interface rather that its implementation.
It automatically handles preprocessing with standard preprocessors,
and builds packages for all the Haskell implementations (except
nhc98, for now).The simple build infrastructure can also handle packages
where building is governed by system-dependent parameters,
if you specify a little more (see ).
A few packages require more elaborate solutions
(see ).Package descriptionsThe package description file should have a name ending in
.cabal. There must be exactly
one such file in the directory. The first part of the name is
usually the package name, and some of the tools that operate
on Cabal packages require this.In the package description file, lines beginning with
-- are treated as comments
and ignored.This file should contain of a number global property
descriptions and several sections.The global properties describe the package as a whole,
such as name, license, author, etc. (see ).Optionally, a number of configuration
flags can be declared. These can be used to
enable or disable certain features of a package. (see ).The (optional) library section specifies the library
properties (see ) and relevant build
information (see ).Following is an arbitrary number of executable sections
which describe an executable program and (see ) relevant build information (see ).Each section consists of a number of property descriptions
in the form of field/value pairs, with a syntax roughly like mail
message headers.Case is not significant in field names,
but is significant in field values.To continue a field value, indent the next line
relative to the field name.Field names may be indented, but all field values in
the same section must use the same indentation.Tabs are not allowed as
indentation characters due to a missing standard
interpretation of tab width.To get a blank line in a field value, use an indented
.The syntax of the value depends on the field. Field types
include:tokenfilenamedirectoryEither a sequence of one or more non-space non-comma
characters, or a quoted string in Haskell 98 lexical syntax.
Unless otherwise stated, relative filenames and directories
are interpreted from the package root directory.freeformURLaddressAn arbitrary, uninterpreted string.identifierA letter followed by zero or more alphanumerics
or underscores.Modules and preprocessorsHaskell module names listed in the
exposed-modules and
other-modules fields may
correspond to Haskell source files, i.e. with names
ending in .hs or
.lhs, or to inputs for
various Haskell preprocessors.
The simple build infrastructure understands the extensions
.gc (&Greencard;),
.chs (&C2hs;),
.hsc (hsc2hs),
.y and
.ly (&Happy;),
.x (&Alex;)
and
.cpphs (&Cpphs;).
When building, Cabal will automatically run the appropriate
preprocessor and compile the Haskell module it produces.Some fields take lists of values, which
are optionally separated by commas, except for the
build-depends field, where the commas are
mandatory.Some fields are marked as required. All others are optional,
and unless otherwise specified have empty default values.Package propertiesThese fields may occur in the first top-level properties
section and describe the package as a whole:name:package-name
(required)
The unique name of the package
(see ), without the version
number.version:numbers
(required)
The package version number, usually consisting of a
sequence of natural numbers separated by dots.cabal-version:>, <=, etc. & numbersThe version of Cabal required for this package.
Since, with Cabal version 1.2 the syntax of package
descriptions has changed, this is now a required field.
List the field early in your .cabal
file so that it will appear as a syntax error before any
others, since old versions of Cabal unfortunately do not
recognize this field.For compatibility, files written in the old syntax
are still recognized. Thus if you don't require
features introduced with or after Cabal version 1.2, you
may write your package description file using the old
syntax. Please consult the user's guide of that Cabal
version for a description of that syntax.build-type:identifierThe type of build used by this package.
Build types are the constructors of the &BuildType; type,
defaulting to Custom.
If this field is given a value other than
Custom, some tools such as
cabal-setup will be able to
build the package without using the setup script. So if you are
just using the default Setup.hs then set
the build type as Simple.license:identifier
(default: AllRightsReserved)
The type of license under which this package is
distributed. License names are the constants of the
&License; type.license-file:filenameThe name of a file containing the precise license
for this package. It will be installed with the package.
copyright:freeformThe content of a copyright notice, typically the
name of the holder of the copyright on the package and
the year(s) from which copyright is claimed.For example:
Copyright: (c) 2006-2007 Joe Bloggsauthor:freeformThe original author of the package.maintainer:addressThe current maintainer or maintainers of the package.
This is an e-mail address to which users should send bug
reports, feature requests and patches.stability:freeformThe stability level of the package, e.g.
alpha, experimental,
provisional,
stable.homepage:URLThe package homepage.package-url:URLThe location of a source bundle for the package.
The distribution should be a Cabal package.synopsis:freeformA very short description of the package, for use in
a table of packages. This is your headline, so keep
it short (one line) but as informative as possible.
Save space by not including the package name or saying
it's written in Haskell.description:freeformDescription of the package. This may be several
paragraphs, and should be aimed at a Haskell programmer
who has never heard of your package before.For library packages, this field is used as
prologue text by setup haddock
(see ), and thus may
contain the same markup as &Haddock; documentation
comments.category:freeformA classification category for future use by the
package catalogue Hackage. These
categories have not yet been specified, but the upper
levels of the module hierarchy make a good start.tested-with:compiler listA list of compilers and versions against which the
package has been tested (or at least built).data-files:filename listA list of files to be installed for run-time use by
the package. This is useful for packages that use a
large amount of static data, such as tables of values
or code templates. For details on how to find these
files at run-time, see
.extra-source-files:filename listA list of additional files to be included in source
distributions built with setup sdist
(see ).extra-tmp-files:filename listA list of additional files or directories to be
removed by setup clean
(see ).
These would typically be additional files created by
additional hooks, such as the scheme described in
.LibraryThe library section should contain the following
fields:exposed-modules:identifier list
(required if this package contains a library)
A list of modules added by this package.build-depends:package listA list of packages, possibly annotated with versions,
needed to build this one,
e.g. foo > 1.2, bar.
If no version constraint is specified, any version is
assumed to be acceptable.The library section may also contain build information fields
(see ).ExecutablesExecutable sections (if present) describe executable
programs contained in the package and must have an argument
after the section label, which defines the name of the
executable. This is a freeform argument but may not contain
spaces.The executable may be described using the following
fields, as well as build information fields (see ).main-is:filename
(required)
The name of the source file containing the
Main module, relative to one of the
directories listed in hs-source-dirs.build-depends:package listA list of packages, possibly annotated with versions,
needed to build this executable,
e.g. foo > 1.2, bar.
If no version constraint is specified, any version is
assumed to be acceptable.Build informationThe following fields may be optionally present in a
library or executable section, and give information for the
building of the corresponding library or executable. See also
and
for a way to supply system-dependent values for these
fields.buildable:Boolean
(default: True)
Is the component buildable?
Like some of the other fields below, this field is
more useful with the slightly more elaborate form of
the simple build infrastructure described in
.other-modules:identifier listA list of modules used by the component
but not exposed to users. For a library component, these
would be hidden modules of the library. For an executable,
these would be auxiliary modules to be linked with the
file named in the main-is field.hs-source-dirs:directory list
(default: .)
Root directories for the module hierarchy.For backwards compatibility, the old variant
hs-source-dir is also recognized.extensions:identifier listA list of Haskell extensions used by every module.
Extension names are the constructors of the &Extension; type.
These determine corresponding compiler options.
In particular, CPP specifies that
Haskell source files are to be preprocessed with a
C preprocessor.Extensions used only by one module may be specified
by placing a LANGUAGE pragma in the
source file affected, e.g.:{-# LANGUAGE CPP, MultiParamTypeClasses #-}GHC versions prior to 6.6 do not support the
LANGUAGE pragma.build-tools:program listA list of programs, possibly annotated with versions,
needed to build this package,
e.g. c2hs > 0.15, cpphs.
If no version constraint is specified, any version is
assumed to be acceptable.ghc-options:token listAdditional options for GHC. You can often achieve
the same effect using the extensions
field, which is preferred.Options required only by one module may be specified
by placing an OPTIONS_GHC pragma in the
source file affected.ghc-prof-options:token listAdditional options for GHC when the package is built
with profiling enabled.ghc-shared-options:token listAdditional options for GHC when the package is
built as shared library.hugs-options:token listAdditional options for Hugs. You can often achieve
the same effect using the extensions
field, which is preferred.Options required only by one module may be specified
by placing an OPTIONS_HUGS pragma in the
source file affected.nhc98-options:token listAdditional options for nhc98. You can often achieve
the same effect using the extensions
field, which is preferred.Options required only by one module may be specified
by placing an OPTIONS_NHC98 pragma in the
source file affected.Warning: Cabal does not currently support building
libraries or executables with nhc98 anyway.includes:filename listA list of header files to be included in any
compilations via C. This field applies to both header
files that are already installed on the system and to
those coming with the package to be isntalled. These files
typically contain function prototypes for foreign imports
used by the package.install-includes:filename listA list of header files from this package to be
installed into
$libdir/includes when the package
is installed. Files listed in
install-includes: should be found in
relative to the top of the source tree or relative to one of the
directories listed in include-dirs.install-includes is typically
used to name header files that contain prototypes for
foreign imports used in Haskell code in this package,
for which the C implementations are also provided with
the package. Note that to include them when compiling
the package itself, they need to be listed in the
includes: field as well.include-dirs:directory listA list of directories to search for header files,
when preprocessing with c2hs,
hsc2hs, ffihugs,
cpphs or the C preprocessor,
and also when compiling via C.c-sources:filename listA list of C source files to be compiled
and linked with the Haskell files.If you use this field, you should also name the
C files in CFILES pragmas in the
Haskell source files that use them, e.g.:
{-# CFILES dir/file1.c dir/file2.c #-}
These are ignored by the compilers, but needed by Hugs.extra-libraries:token listA list of extra libraries to link with.extra-lib-dirs:directory listA list of directories to search for libraries.cc-options:token listCommand-line arguments to be passed to the C compiler.
Since the arguments are compiler-dependent, this field
is more useful with the setup described in
.ld-options:token listCommand-line arguments to be passed to the linker.
Since the arguments are compiler-dependent, this field
is more useful with the setup described in
.pkgconfig-depends:package listA list of &PkgConfig; packages, needed to build this
package. They can be annotated with versions,
e.g. gtk+-2.0 >= 2.10, cairo >= 1.0.
If no version constraint is specified, any version is
assumed to be acceptable. Cabal uses
pkg-config to find if the packages are
available on the system and to find the extra compilation and
linker options needed to use the packages.
If you need to bind to a C library that supports
pkg-config (use
pkg-config --list-all to find out if it is
supported) then it is much preferable to use this field rather
than hard code options into the other fields.
frameworks:token listOn Darwin/MacOS X, a list of frameworks to link to.
See Apple's developer documentation for more details
on frameworks. This entry is ignored on all other
platforms.ConfigurationsLibrary and executable sections may include conditional
blocks, which test for various system parameters and
configuration flags. The flags mechanism is rather generic,
but most of the time a flag represents certain feature, that
can be switched on or off by the package user.Here is an example package description file using
configurations:A package containing a library and executable programsName: Test1
Version: 0.0.1
Cabal-Version: >= 1.2
License: BSD3
Author: Jane Doe
Synopsis: Test package to test configurations
Category: Example
Flag Debug
Description: Enable debug support
Default: False
Flag WebFrontend
Description: Include API for web frontend.
-- Cabal checks if the configuration is possible, first
-- with this flag set to True and if not it tries with False
Library
Build-Depends: base
Exposed-Modules: Testing.Test1
Extensions: CPP
if flag(debug)
GHC-Options: -DDEBUG
if !os(win32)
CC-Options: "-DDEBUG"
else
CC-Options: "-DNDEBUG"
if flag(webfrontend)
Build-Depends: cgi > 0.42
Other-Modules: Testing.WebStuff
Executable test1
Main-is: T1.hs
Other-Modules: Testing.Test1
Build-Depends: base
if flag(debug)
CC-Options: "-DDEBUG"
GHC-Options: -DDEBUG
LayoutFlags, conditionals, library and executable sections use layout to
indicate structure. This is very similar to the Haskell layout rule.
Entries in a section have to all be indented to the same level which must
be more than the section header. Tabs are not allowed to be used for
indentation.As an alternative to using layout you can also use explicit braces
{}. In this case the indentation of entries in a
section does not matter, though different fields within a block must be
on different lines. Here is a bit of the above example again, using
braces:Using explicit braces rather than indentation for layoutName: Test1
Version: 0.0.1
Cabal-Version: >= 1.2
License: BSD3
Author: Jane Doe
Synopsis: Test package to test configurations
Category: Example
Flag Debug {
Description: Enable debug support
Default: False
}
Library {
Build-Depends: base
Exposed-Modules: Testing.Test1
Extensions: CPP
if flag(debug) {
GHC-Options: -DDEBUG
if !os(win32) {
CC-Options: "-DDEBUG"
} else {
CC-Options: "-DNDEBUG"
}
}
}
Configuration FlagsA flag section takes the flag name as an argument and
may contain the following fields.description:freeformThe description of this flag.default:Boolean
(default: True)
The default value of this flag.Note that this value may be overridden in several
ways (see ). The
rationale for having flags default to True is that users
usually want new features as soon as they are available.
Flags representing features that are not (yet)
recommended for most users (such as experimental
features or debugging support) should therefore
explicitly override the default to False.Conditional BlocksConditional blocks may appear anywhere inside a
library or executable section. They have to follow rather
strict formatting rules.Conditional blocks must always be of the shape
if conditionproperty-descriptions-or-conditionals*or
if conditionproperty-descriptions-or-conditionals*elseproperty-descriptions-or-conditionals*Note that the if and the condition have to
be all on the same line.ConditionsConditions can be formed using boolean tests and the
boolean operators || (disjunction /
logical "or"), && (conjunction /
logical "and"), or ! (negation / logical
"not"). The unary ! takes highest
precedence, || takes lowest. Precedence
levels may be overridden through the use of parentheses.
For example, os(darwin) && !arch(i386) || os(freebsd)
is equivalent to (os(darwin) && !(arch(i386))) || os(freebsd).
The following tests are currently supported.os(name)Tests if the current operating system is
name. The argument is tested
against System.Info.os on
the target system. There is unfortunately some disagreement
between Haskell implementations about the standard values of
System.Info.os. Cabal canonicalises it so
that in particular os(windows) works on all
implementations. If the canonicalised os names match, this test
evaluates to true, otherwise false. The match is
case-insensitive. arch(name)Tests if the current architecture is
name. The argument is matched
against System.Info.arch on the target system.
If the arch names match, this test evaluates to true,
otherwise false. The match is case-insensitive. impl(compiler)Tests for the configured Haskell implementation. An optional
version constraint may be specified (for example
impl(ghc >= 6.6.1)). If the
configured implementation is of the right type and matches the
version constraint, then this evaluates to true,
otherwise false. The match is case-insensitive.flag(name)Evaluates to the current assignment of the flag of
the given name. Flag names are case insensitive.
Testing for flags that have not been introduced with a
flag section is an error.trueConstant value true.falseConstant value false.Resolution of Conditions and FlagsIf a package descriptions specifies configuration flags
the package user can control these in several ways (see
). If the user does not fix the
value of a flag, Cabal will try to find a flag assignment in the
following way.For each flag specified, it will assign its default
value, evaluate all conditions with this flag assignment,
and check if all dependencies can be satisfied. If this
check succeeded, the package will be configured with those
flag assignments.If dependencies were missing, the last flag (as by
the order in which the flags were introduced in the
package description) is tried with its alternative value
and so on. This continues until either an assignment is
found where all dependencies can be satisfied, or all
possible flag assignments have been tried.To put it another way, Cabal does a complete backtracking
search to find a satisfiable packge configuration. It is only the
dependencies specified in the build-depends field
in conditional blocks that determine if a particular flag assignment
is satisfiable (build-tools are not considered).
The order of the declaration and the default value of the flags
determines the search order. Flags overriden on the command line fix
the assignment of that flag, so no backtracking will be tried for
that flag.If no suitable flag assignment could be found, the
configuration phase will fail and a list of missing
dependencies will be printed. Note that this resolution
process is exponential in the worst case (i.e., in the case
where dependencies cannot be satisfied). There are some
optimizations applied internally, but the overall complexity
remains unchanged.Meaning of field values when using conditionalsDuring the configuration phase, a flag assignment is
chosen, all conditionals are evaluated, and the package description
is combined into a flat package descriptions. If the same field
both inside a conditional and outside then they are combined using
the following rules.Boolean fields are combined using conjunction
(logical "and").List fields are combined by appending the inner
items to the outer items, for example
Extensions: CPP
if impl(ghc) || impl(hugs)
Extensions: MultiParamTypeClasses
when compiled using Hugs or GHC will be combined to
Extensions: CPP, MultiParamTypeClassesSimilarly, if two conditional sections appear at the
same nesting level, properties specified in the latter
will come after properties specified in the former.All other fields must not be specified in ambiguous ways. For example
Main-is: Main.hs
if flag(useothermain)
Main-is: OtherMain.hs
will lead to an error. Instead use
if flag(useothermain)
Main-is: OtherMain.hs
else
Main-is: Main.hs
Accessing data files from package codeThe placement on the target system of files listed in the
data-files field varies between systems, and in
some cases one can even move packages around after installation
(see ). To enable packages
to find these files in a portable way, Cabal generates a module
called Paths_pkgname
(with any hyphens in pkgname replaced
by underscores) during building, so that it may be imported by
modules of the package. This module defines a function
getDataFileName :: FilePath -> IO FilePath
If the argument is a filename listed in the
data-files field, the result is the name
of the corresponding file on the system on which the program
is running.System-dependent parametersFor some packages, especially those interfacing with C
libraries, implementation details and the build procedure depend
on the build environment. A variant of the simple build
infrastructure (the build-typeConfigure) handles many such situations using
a slightly longer Setup.hs:
import Distribution.Simple
main = defaultMainWithHooks defaultUserHooksThis program differs from defaultMain
in two ways:If the package root directory contains a file called
configure, the configure step will
run that. This configure program may
be a script produced by the &Autoconf;
system, or may be hand-written. This program typically
discovers information about the system and records it for
later steps, e.g. by generating system-dependent header files
for inclusion in C source files and preprocessed Haskell
source files. (Clearly this won't work for Windows without
MSYS or Cygwin: other ideas are needed.)If the package root directory contains a file called
package.buildinfo
after the configuration step, subsequent steps will read it
to obtain additional settings for build information fields
(see ), to be merged with the
ones given in the .cabal file.
In particular, this file may be generated by the
configure script mentioned above,
allowing these settings to vary depending on the build
environment.The build information file should have the following
structure:buildinfo
executable: namebuildinfo
executable: namebuildinfo
...where each buildinfo consists
of settings of fields listed in .
The first one (if present) relates to the library, while each
of the others relate to the named executable. (The names
must match the package description, but you don't have to
have entries for all of them.)Neither of these files is required. If they are absent, this
setup script is equivalent to defaultMain.Using autoconf(This example is for people familiar with the &Autoconf;
tools.)In the X11 package, the file configure.ac
contains:
AC_INIT([Haskell X11 package], [1.1], [libraries@haskell.org], [X11])
# Safety check: Ensure that we are in the correct source directory.
AC_CONFIG_SRCDIR([X11.cabal])
# Header file to place defines in
AC_CONFIG_HEADERS([include/HsX11Config.h])
# Check for X11 include paths and libraries
AC_PATH_XTRA
AC_TRY_CPP([#include <X11/Xlib.h>],,[no_x=yes])
# Build the package if we found X11 stuff
if test "$no_x" = yes
then BUILD_PACKAGE_BOOL=False
else BUILD_PACKAGE_BOOL=True
fi
AC_SUBST([BUILD_PACKAGE_BOOL])
AC_CONFIG_FILES([X11.buildinfo])
AC_OUTPUTThen the setup script will run the
configure script, which checks for the
presence of the X11 libraries and substitutes for variables
in the file X11.buildinfo.in:
buildable: @BUILD_PACKAGE_BOOL@
cc-options: @X_CFLAGS@
ld-options: @X_LIBS@This generates a file X11.buildinfo
supplying the parameters needed by later stages:
buildable: True
cc-options: -I/usr/X11R6/include
ld-options: -L/usr/X11R6/libThe configure script also generates
a header file include/HsX11Config.h
containing C preprocessor defines recording the results of
various tests. This file may be included by C source files
and preprocessed Haskell source files in the package.Packages using these features will also need to list
additional files such as configure,
templates for .buildinfo files, files named
only in .buildinfo files, header files and
so on in the extra-source-files field,
to ensure that they are included in source distributions.
They should also list files and directories generated by
configure in the
extra-tmp-files field to ensure that they
are removed by setup clean.More complex packagesFor packages that don't fit the simple schemes described above,
you have a few options:You can customize the simple build infrastructure
using hooks. These allow you to
perform additional actions before and after each command is
run, and also to specify additional preprocessors. See
UserHooks in &Simple; for the details,
but note that this interface is experimental, and likely to
change in future releases.You could delegate all the work to make,
though this is unlikely to be very portable.
Cabal supports this with the build-typeMake and a trivial setup library &Make;,
which simply parses the command line arguments and invokes
make. Here Setup.hs
looks like
import Distribution.Make
main = defaultMainThe root directory of the package should contain
a configure script, and, after
that has run, a Makefile with a
default target that builds the package, plus targets
install, register,
unregister, clean,
dist and docs.
Some options to commands are passed through as follows:The ,
, ,
,
and options to the
configure command are passed on to
the configure script.
In addition the value of the
option is passed in a option and
all options specified with =
are passed on.the --destdir option to the
copy command becomes a setting of a
destdir variable on the invocation of
make copy. The supplied
Makefile should provide a
copy target, which will probably
look like this:
copy :
$(MAKE) install prefix=$(destdir)/$(prefix) \
bindir=$(destdir)/$(bindir) \
libdir=$(destdir)/$(libdir) \
datadir=$(destdir)/$(datadir) \
libexecdir=$(destdir)/$(libexecdir)You can write your own setup script conforming to the
interface of , possibly using
the Cabal library for part of the work. One option is to
copy the source of Distribution.Simple,
and alter it for your needs. Good luck.Building and installing a packageAfter you've unpacked a Cabal package, you can build it
by moving into the root directory of the package and using the
Setup.hs or Setup.lhs
script there:runhaskell Setup.hscommandoptionwhere runhaskell might be
runhugs, runghc or
runnhc. The command
argument selects a particular step in the build/install process.
You can also get a summary of the command syntax withrunhaskell Setup.hs Building and installing a system package
runhaskell Setup.hs configure --ghc
runhaskell Setup.hs build
runhaskell Setup.hs installThe first line readies the system to build the tool using GHC;
for example, it checks that GHC exists on the system. The second
line performs the actual building, while the last both copies
the build results to some permanent place and registers the
package with GHC.Building and installing a user package
runhaskell Setup.hs configure --ghc --user --prefix=$HOME
runhaskell Setup.hs build
runhaskell Setup.hs installThe package may use packages from the user's package database
as well as the global one (), is installed
under the user's home directory (),
and is registered in the user's package database
().Creating a binary packageWhen creating binary packages (e.g. for RedHat or
Debian) one needs to create a tarball that can be sent to
another system for unpacking in the root directory:
runhaskell Setup.hs configure --ghc --prefix=/usr
runhaskell Setup.hs build
runhaskell Setup.hs copy --destdir=/tmp/mypkg
(cd /tmp/mypkg; tar cf - .) | gzip -9 >mypkg.tar.gzIf the package contains a library, you need two additional
steps:
runhaskell Setup.hs register --gen-script
runhaskell Setup.hs unregister --gen-scriptThis creates shell scripts register.sh
and unregister.sh, which must also be sent
to the target system. After unpacking there, the package must be
registered by running the register.sh script.
The unregister.sh script would be used
in the uninstall procedure of the package. Similar steps may
be used for creating binary packages for Windows.The following options are understood by all commands:
, or
List the available options for the command.
=n or
nSet the verbosity level (0-3). The normal level is 1;
a missing n defaults to 2.The various commands and the additional options they support
are described below. In the simple build infrastructure, any
other options will be reported as errors.setup configurePrepare to build the package. Typically, this step checks
that the target platform is capable of building the package,
and discovers platform-specific features that are needed during
the build.The user may also adjust the behaviour of later stages using
the options listed in the following subsections. In the simple
build infrastructure, the values supplied via these options are
recorded in a private file read by later stages.If a user-supplied configure
script is run (see
or ), it is passed the
,
, ,
, and
options.
In addition the value of the
option is passed in a option and
all options specified with =
are passed on.Programs used for buildingThe following options govern the programs used to process
the source files of a package: or Specify which Haskell implementation to use to build
the package. At most one of these flags may be given.
If none is given, the implementation under which the setup
script was compiled or interpreted is used.=path
or pathSpecify the path to a particular compiler. If given,
this must match the implementation selected above.
The default is to search for the usual name of the
selected implementation.This flag also sets the default value of the
option to the package tool
for this compiler.
Check the output of setup configure -v
to ensure that it finds the right package tool (or use
explicitly).=pathSpecify the path to the package tool, e.g.
ghc-pkg.
The package tool must be compatible with the compiler
specified by .
If this option is omitted, the default value is determined
from the compiler selected.=pathSpecify the path to the program prog.
Any program known to Cabal can be used in place of
prog. It can either be a fully
path or the name of a program that can be found on the program
search path. For example:
or .=optionsSpecify additional options to the program prog.
Any program known to Cabal can be used in place of
prog. For example:
.The options is split into program options
based on spaces. Any options containing embeded spaced need to
be quoted, for example
--foo-options='--bar="C:\Program File\Bar"'. As an
alternative that takes only one option at a time but avoids the
need to quote, use
instead.
=optionSpecify a single additional option to the program
prog.For passing an option that contain embeded spaces, such as a file
name with embeded spaces, using this rather than
means you
do not need an additional level of quoting. Of course if
you are using a command shell you may still need to quote, for
example --foo-options="--bar=C:\Program File\Bar".
All of the options passed with either
or
are passed
in the order they were specified on the configure command line.
Installation pathsThe following options govern the location of installed files
from a package:=dirThe root of the installation, for example
/usr/local on a Unix system, or
C:\Program Files on a Windows system.
The other installation paths are usually subdirectories of
prefix, but they don't have
to be.In the simple build system, dir
may contain the following path variables:
$pkgid$pkg$version$compiler=dirExecutables that the user might invoke are installed here.In the simple build system, dir
may contain the following path variables:
$prefix$pkgid$pkg$version$compiler=dirObject-code libraries are installed here.In the simple build system, dir
may contain the following path variables:
$prefix$bindir$pkgid$pkg$version$compiler=dirExecutables that are not expected to be invoked
directly by the user are installed here.In the simple build system, dir
may contain the following path variables:
$prefix$bindir$libdir$libsubdir$pkgid$pkg$version$compiler=dirArchitecture-independent data files are installed
here.In the simple build system, dir
may contain the following path variables:
$prefix$bindir$libdir$libsubdir$pkgid$pkg$version$compilerIn addition the simple build system supports the following
installation path options:=dirA subdirectory of libdir
in which libraries are actually installed. For example,
in the simple build system on Unix, the default
libdir is
/usr/local/lib, and
libsubdir contains the package
identifier and compiler,
e.g. mypkg-0.2/ghc-6.4, so libraries
would be installed in
/usr/local/lib/mypkg-0.2/ghc-6.4.
dir may contain the following path
variables:
$pkgid$pkg$version$compiler=dirA subdirectory of datadir
in which data files are actually installed.
dir may contain the following path
variables:
$pkgid$pkg$version$compiler=dirDocumentation files are installed relative to this directory.
dir may contain the following path
variables:
$prefix$bindir$libdir$libsubdir$datadir$datasubdir$pkgid$pkg$version$compiler=dirHTML documentation files are installed relative to this directory.
dir may contain the following path
variables:
$prefix$bindir$libdir$libsubdir$datadir$datasubdir$docdir$pkgid$pkg$version$compilerPath variables in the simple build systemFor the simple build system, there are a number of variables
that can be used when specifying installation paths. The defaults
are also specified in terms of these variables. A number of the
variables are actually for other paths, like
$prefix. This allows paths to be specified
relative to each other rather than as absolute paths, which is
important for building relocatable packages (see
).$prefixThe path variable that stands for the root of the
installation.For an installation to be relocatable, all other
instllation paths must be relative to the
$prefix variable.$bindirThe path variable that expands to the path given by
the configure option (or the
default).$libdirAs above but for $libsubdirAs above but for $datadirAs above but for $datasubdirAs above but for $docdirAs above but for $pkgidThe name and version of the package, eg
mypkg-0.2$pkgThe name of the package, eg
mypkg$versionThe version of the package, eg
0.2$compilerThe compiler being used to build the package, eg
ghc-6.6.1Paths in the simple build systemFor the simple build system, the following defaults
apply:OptionWindows DefaultUnix Default--prefixC:\Program Files\Haskell/usr/local--bindir$prefix\bin$prefix/bin--libdir$prefix$prefix/lib--libsubdir (Hugs)hugs\packages\$pkghugs/packages/$pkg--libsubdir (others)$pkgid\$compiler$pkgid/$compiler--libexecdir$prefix\$pkgid$prefix/libexec--datadir (executable)$prefix$prefix/share--datadir (library)C:\Program Files\Haskell$prefix/share--datasubdir$pkgid$pkgid--docdir$prefix\doc\$pkgid$datadir/doc/$pkgid--htmldir$docdir\html$docdir/htmlPrefix-independenceOn Windows, and when using Hugs on any system, it is
possible to obtain the pathname of the running program.
This means that we can construct an installable executable
package that is independent of its absolute install location.
The executable can find its auxiliary files by finding its
own path and knowing the location of the other files relative
to bindir. Prefix-independence is
particularly useful: it means the user can choose the install
location (i.e. the value of prefix)
at install-time, rather than having to bake the path into
the binary when it is built.In order to achieve this, we require
that for an executable on Windows, all
of bindir,
libdir,
datadir and
libexecdir begin with
$prefix. If this is not the case
then the compiled executable will have baked in
all absolute paths.The application need do nothing special to achieve
prefix-independence. If it finds any files using
getDataFileName and the other functions
provided for the purpose (see ),
the files will be accessed relative to the location of the
current executable.A library cannot (currently) be prefix-independent,
because it will be linked into an executable whose
filesystem location bears no relation to the library
package.Controlling Flag AssignmentsFlag assignments (see ) can be
controlled with the following command line options.flagname or
-flagnameForce the specified flag to
true or false (if
preceded with a -). Later
specifications for the same flags will override earlier,
i.e., specifying -fdebug -f-debug is
equivalent to -f-debug=flagspecsSame as , but allows specifying
multiple flag assignments at once. The parameter is a
space-separated list of flag names (to force a flag to
true), optionally preceded by a
- (to force a flag to
false). For example,
--flags="debug -feature1 feature2" is
equivalent to -fdebug -f-feature1
-ffeature2.Miscellaneous optionsAllow dependencies to be satisfied by the user package
database, in addition to the global database.This also implies a default of
for any subsequent install command,
as packages registered in the global database should not
depend on packages registered in a user's database.(default) Dependencies must be satisfied by the global
package database. or (default) Build with optimization flags (if available).
This is appropriate for production use, taking more time
to build faster libraries and programs.Build without optimization. This is suited for
development: building will be quicker, but the resulting
library or programs will be slower. or
Request that an additional version of the library
with profiling features enabled be built and installed
(only for implementations that support profiling).(default) Do not generate an additional profiling
version of the library.Any executables generated should have profiling enabled
(only for implementations that support profiling). For this
to work, all libraries used by these executables must also
have been built with profiling support.(default) Do not enable profiling in generated
executables.(default) Build ordinary libraries (as opposed to profiling
libraries). This is independent of the
option. If you
enable both, you get both.(default) Do not build ordinary libraries. This is useful
in conjunction with
to build only profiling libraries, rather than profiling and
ordinary libraries.(default) Build libraries suitable for use with GHCi.Not all platforms support GHCi and indeed on some
platforms, trying to build GHCi libs fails. In such cases
this flag can be used as a workaround.Use the GHC feature when
building the library. This reduces the final size of the
executables that use the library by allowing them to link with
only the bits that they use rather than the entire library.
The downside is that building the library takes longer and uses
considerably more memory.(default) Do not use the GHC
feature. This makes building the library quicker but the final
executables that use the library will be larger.Build shared library. This implies a seperate
compiler run to generate position independent code as
required on most platforms.(default) Do not build shared library.=strAn extra option to an external
configure script,
if one is used (see ).
There can be several of these options.In the simple build infrastructure, an additional option
is recognized:=dirSpecify the directory into which the Hugs output will be
placed (default: dist/scratch).setup buildPerform any preprocessing or compilation needed to make this
package ready for installation.This command takes the following options:=options=optionThese are mostly the same as the options configure step (see
). Unlike the options
specified at the configure step, any program options specified at
the build step are not persistent but are used for that
invocation only. They options specified at the build step are in
addition not in replacement of any options specified at the
configure step.
setup makefileGenerate a Makefile that may be used
to compile the Haskell modules to object code.
This command is currently only supported when building libraries,
and only if the compiler is GHC.The makefile command replaces part of the work done by
setup build. The sequence of commands would
typeically be:
runhaskell Setup.hs makefile
make
runhaskell Setup.hs build
where setup makefile does the preprocessing,
make compiles the Haskell modules, and
setup build performs any final steps, such as
building the library archives.The Makefile does not use GHC's --make
flag to compile the modules, instead it compiles modules one at
a time, using dependency information generated by GHC's
-M flag. There are two reasons you might
therefore want to use setup makefile:
You want to build in parallel using make -j.
Currently, setup build on its own does not support
building in parallel.You want to build an individual module, pass extra
flags to a compilation, or do other non-standard things that
setup build does not support.This command takes the following options:=filename or
filenameSpecify the output file (default Makefile).setup haddockBuild the documentation for the package using &Haddock;. By
default, only the documentation for the exposed modules is generated
(see ).This command takes the following options:Generate a file
dist/doc/html/pkgid.txt,
which can be converted by
Hoogle
into a database for searching. This is
equivalent to running &Haddock; with the flag.
=urlSpecify a template for the location of HTML documentation
for pre-requisite packages. The substitutions listed in
are applied to the template
to obtain a location for each package, which will be used
by hyperlinks in the generated documentation. For example,
the following command generates links pointing at &HackageDB;
pages:setup haddock --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'Here the argument is quoted to prevent substitution
by the shell.If this option is omitted, the location for each package
is obtained using the package tool (e.g.
ghc-pkg).Also run &Haddock; for the modules of all the executable
programs. By default &Haddock; is run only on the exported
modules.=pathThe argument path denotes a CSS
file, which is passed to &Haddock; and used to set the style of
the generated documentation. This is only needed to override the
default style that &Haddock; uses.
Generate &Haddock; documentation integrated with &HsColour;.
First, &HsColour; is run to generate colourised code.
Then &Haddock; is run to generate HTML documentation. Each
entity shown in the documentation is linked to its definition in
the colourised code.=pathThe argument path denotes a CSS
file, which is passed to &HsColour; as in
runhaskell Setup.hs hscolour --css=pathsetup hscolourProduce colourised code in HTML format using &HsColour;.
Colourised code for exported modules is put in
dist/doc/html/pkgid/src.This command takes the following options:Also run &HsColour; on the sources of all executable
programs. Colourised code is put in
dist/doc/html/pkgid/executable/src.=pathCopy the CSS file from path to
dist/doc/html/pkgid/src/hscolour.css
for exported modules, or to
dist/doc/html/pkgid/executable/src/hscolour.css
for executable programs. The CSS file defines the actual colours
used to colourise code. Note that the
hscolour.css file is required for the code
to be actually colourised.setup installCopy the files into the install locations and (for library
packages) register the package with the compiler, i.e. make the
modules it contains available to programs.The install locations are determined by options to
setup configure
(see ).This command takes the following options:Register this package in the system-wide database.
(This is the default, unless the
option was supplied to the configure
command.)Register this package in the user's local package database.
(This is the default if the
option was supplied to the configure
command.)setup copyCopy the files without registering them. This command
is mainly of use to those creating binary packages.This command takes the following option:=pathSpecify the directory under which to place
installed files. If this is not given, then the root
directory is assumed.setup registerRegister this package with the compiler, i.e. make the
modules it contains available to programs. This only makes sense
for library packages. Note that the install
command incorporates this action. The main use of this
separate command is in the post-installation step for a binary
package.This command takes the following options:Register this package in the system-wide database.
(This is the default.)Register this package in the user's local package
database.Instead of registering the package, generate a script
containing commands to perform the registration. On Unix,
this file is called register.sh, on
Windows, register.bat. This script
might be included in a binary bundle, to be run after the
bundle is unpacked on the target system.=[path]Instead of registering the package, generate a package
registration file. This only applies to compilers that support
package registration files which at the moment is only GHC.
The file should be used with the compiler's mechanism for
registering packages.This option is mainly intended for packaging systems. If
possible use the option instead
since it is more portable across Haskell implementations.The path is optional and can be
used to specify a particular output file to generate. Otherwise,
by default the file is the package name and version with a
.conf extension.Registers the package for use directly from the
build tree, without needing to install it. This can be
useful for testing: there's no need to install the package
after modifying it, just recompile and test.This flag does not create a build-tree-local package
database. It still registers the package in one of the
user or global databases.However, there are some caveats. It only works with
GHC (currently). It only works if your package doesn't
depend on having any supplemental files installed - plain
Haskell libraries should be fine.setup unregisterDeregister this package with the compiler.This command takes the following options:Deregister this package in the system-wide database.
(This is the default.)Deregister this package in the user's local package
database.Instead of deregistering the package, generate a script
containing commands to perform the deregistration. On Unix,
this file is called unregister.sh, on
Windows, unregister.bat. This script
might be included in a binary bundle, to be run on the
target system.setup cleanRemove any local files created during the
configure, build,
haddock, register or
unregister steps, and also any files and
directories listed in the extra-tmp-files
field.This command takes the following options: or Keeps the configuration information so it is not necessary
to run the configure step again before building.setup testRun the test suite specified by the
runTests field of
Distribution.Simple.UserHooks. See &Simple;
for information about creating hooks and using
defaultMainWithHooks.setup sdistCreate a system- and compiler-independent source distribution
in a file
package-version.tar.gz
in the dist subdirectory, for distribution
to package builders. When unpacked, the commands listed in this
section will be available.The files placed in this distribution are the package
description file, the setup script, the sources of the modules
named in the package description file, and files named in the
license-file, main-is,
c-sources, data-files and
extra-source-files fields.This command takes the following option:Append today's date
(in YYYYMMDD form) to the version
number for the generated source package. The original
package is unaffected.Known bugs and deficienciesAll these should be fixed in future versions:The scheme described in
will not work on Windows without MSYS or Cygwin.Cabal has some limitations both running under Hugs
and building packages for it:Cabal requires the latest release (Mar 2005).It doesn't work with Windows.There is no hugs-pkg tool.Though the library runs under Nhc98, it cannot build
packages for Nhc98.Please report any other flaws to
libraries@haskell.org.