diff --git a/doc/Cabal.xml b/doc/Cabal.xml
deleted file mode 100644
index 50ff23fae53ea1c3a7305dd6a7e1ffdb4c69c4c3..0000000000000000000000000000000000000000
--- a/doc/Cabal.xml
+++ /dev/null
@@ -1,3715 +0,0 @@
-<?xml version="1.0" encoding="US-ASCII"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [
- <!ENTITY Simple '<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>'>
- <!ENTITY Make '<ulink url="../libraries/Cabal/Distribution-Make.html">Distribution.Make</ulink>'>
- <!ENTITY License '<ulink url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink>'>
- <!ENTITY Extension '<ulink url="../libraries/Cabal/Language-Haskell-Extension.html#t:Extension"><literal>Extension</literal></ulink>'>
- <!ENTITY BuildType '<ulink url="../libraries/Cabal/Distribution-PackageDescription.html#t:BuildType"><literal>BuildType</literal></ulink>'>
- <!ENTITY Alex '<ulink url="http://www.haskell.org/alex/"><command>alex</command></ulink>'>
- <!ENTITY Autoconf '<ulink url="http://www.gnu.org/software/autoconf/"><command>autoconf</command></ulink>'>
- <!ENTITY C2hs '<ulink url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/"><command>c2hs</command></ulink>'>
- <!ENTITY Cpphs '<ulink url="http://www.haskell.org/cpphs/"><command>cpphs</command></ulink>'>
- <!ENTITY Greencard '<ulink url="http://www.haskell.org/greencard/"><command>greencard</command></ulink>'>
- <!ENTITY Haddock '<ulink url="http://www.haskell.org/haddock/"><command>haddock</command></ulink>'>
- <!ENTITY HsColour '<ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour/"><command>HsColour</command></ulink>'>
- <!ENTITY Happy '<ulink url="http://www.haskell.org/happy/"><command>happy</command></ulink>'>
- <!ENTITY HackageDB '<ulink url="http://hackage.haskell.org/">HackageDB</ulink>'>
- <!ENTITY PkgConfig '<ulink url="http://pkg-config.freedesktop.org/">pkg-config</ulink>'>
- ]>
-
-<article>
- <title>Common Architecture for Building Applications and Libraries</title>
- <subtitle>User's Guide</subtitle>
-
- <abstract>
- <para><firstterm>Cabal</firstterm> aims to simplify the
- distribution of <ulink url="http://www.haskell.org/">Haskell</ulink>
- 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.</para>
- </abstract>
-
- <sect1 id="intro">
- <title>Introduction</title>
- <para>
- Developers write Cabal packages. These can be for libraries or
- executables. This involves writing the code obviously and also creating a
- <literal>.cabal</literal> file. The .cabal file contains some information
- about the package. Some of this information is needed to actually build
- the package and some is just useful for identifying the package when it
- comes to distribution.
- </para>
- <programlisting>
-name: Foo
-version: 1.0
-
-library
- build-depends: base
- exposed-modules: Foo
- </programlisting>
- <para>
- Users install Cabal packages so they can use them. It is not expected
- that users will have to modify any of the information in the
- <literal>.cabal</literal> file. Cabal does provide a number of ways for
- a user to customise how and where a package is installed. They can decide
- where a package will be installed, which Haskell implementation to use
- and whether to build optimised code or build with the ability to profile
- code.
- </para>
- <programlisting>
-tar -xzf Foo-1.0.tar.gz
-cd Foo-1.0
-runhaskell Setup configure --with-compiler=ghc-6.4.2 --user
-runhaskell Setup build
-runhaskell Setup install
- </programlisting>
- <para>
- One of the purposes of Cabal is to make it easier to build a package with
- different Haskell implementations. So it provides abstractions of
- features present in different Haskell implementations and wherever
- possible it is best to take advantage of these to increase portability.
- Where necessary however it is possible to use specific features of
- specific implementations. For example one of the pieces of information a
- package author can put in the package's <literal>.cabal</literal> file is
- what language extensions the code uses. This is far preferable to
- specifying flags for a specific compiler as it allows Cabal to pick the
- right flags for the Haskell implementation that the user picks. It also
- allows Cabal to figure out if the language extension is even supported by
- the Haskell implementation that the user picks. Where compiler-specific
- options are needed however, there is an "escape hatch" available. The
- developer can specify implementation-specific options and more generally
- there is a configuration mechanism to customise many aspects of how a
- package is built depending on the Haskell implementation, the Operating
- system, computer architecture and user-specified configuration flags.
- </para>
- <programlisting>
-name: Foo
-version: 1.0
-
-library
- build-depends: base
- exposed-modules: Foo
- extensions: ForeignFunctionInterface
- ghc-options: -Wall
- nhc98-options: -K4m
- if os(windows)
- build-depends: Win32
- </programlisting>
- </sect1>
-
- <sect1 id="packages">
- <title>Packages</title>
-
- <para>A <firstterm>package</firstterm> is the unit of distribution
- for the Cabal. Its purpose, when installed, is to make available
- either or both of:</para>
- <itemizedlist>
- <listitem>
- <para>A library, exposing a number of Haskell modules. A library
- may also contain <firstterm>hidden</firstterm> modules, which
- are used internally but not available to clients.<footnote>
- <para>Hugs doesn't support module hiding.</para>
- </footnote>
- </para>
- </listitem>
-
- <listitem>
- <para>One or more Haskell programs.</para>
- </listitem>
- </itemizedlist>
- <para>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.</para>
-
- <para>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.</para>
-
- <para>A package is identified by a globally-unique
- <firstterm>package name</firstterm>, 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
- <firstterm>version number</firstterm>, consisting of a sequence
- of one or more integers separated by dots. These can be combined
- to form a single text string called the <firstterm>package
- ID</firstterm>, using a hyphen to separate the name from the
- version, e.g. <quote><literal>HUnit-1.1</literal></quote>.</para>
-
- <note>
- <para>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.</para>
- </note>
- </sect1>
-
- <sect1 id="authors">
- <title>Creating a package</title>
-
- <para>Suppose 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:</para>
- <variablelist>
- <varlistentry>
- <term>
- <filename><replaceable>package</replaceable>.cabal</filename>
- </term>
- <listitem>
- <para>a Unicode UTF-8 text file containing a package description
- (for details of the syntax of this file, see
- <xref linkend="pkg-descr"/>)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <filename>Setup.hs</filename> or
- <filename>Setup.lhs</filename>
- </term>
- <listitem>
- <para>a single-module Haskell program to perform various
- setup tasks (with the interface described in
- <xref linkend="builders"/>). 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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Once you have these, you can create a source bundle of this
- directory for distribution. Building of the package is discussed in
- <xref linkend="builders"/>.</para>
-
- <example id="simple-library-example">
- <title>A package containing a simple library</title>
- <para>The HUnit package contains a file <filename>HUnit.cabal</filename>
- containing:</para>
- <programlisting>
-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
-</programlisting>
- <para>and the following <filename>Setup.hs</filename>:</para>
- <programlisting>
-import Distribution.Simple
-main = defaultMain</programlisting>
- </example>
-
- <example id="simple-executable-example">
- <title>A package containing executable programs</title>
- <programlisting>
-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
-</programlisting>
- <para>with <filename>Setup.hs</filename> the same as above.</para>
- </example>
-
- <example id="simple-library-executable-example">
- <title>A package containing a library and executable programs</title>
- <programlisting>
-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
-</programlisting>
- <para>with <filename>Setup.hs</filename> the same as above.
- Note that any library modules required (directly or indirectly)
- by an executable must be listed again.</para>
- </example>
-
- <para>The trivial setup script used in these examples uses
- the <firstterm>simple build infrastructure</firstterm>
- 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).</para>
-
- <para>The simple build infrastructure can also handle packages
- where building is governed by system-dependent parameters,
- if you specify a little more (see <xref linkend="system-dependent"/>).
- A few packages require more elaborate solutions
- (see <xref linkend="complex-packages"/>).</para>
-
- <sect2 id="pkg-descr">
- <title>Package descriptions</title>
-
- <para>The package description file must have a name ending in
- <quote><literal>.cabal</literal></quote>. It must be a Unicode text
- file encoded using valid UTF-8. 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.</para>
-
- <para>In the package description file, lines whose first
- non-whitespace characters
- are <quote><literal>--</literal></quote> are treated as comments
- and ignored.</para>
-
- <para>This file should contain of a number global property
- descriptions and several sections.</para>
-
- <itemizedlist>
- <listitem>
- <para>The global properties describe the package as a whole,
- such as name, license, author, etc. (see <xref
- linkend="general-fields"/>).</para>
- </listitem>
- <listitem>
- <para>Optionally, a number of <firstterm>configuration
- flags</firstterm> can be declared. These can be used to
- enable or disable certain features of a package. (see <xref
- linkend="configurations"/>).</para>
- </listitem>
- <listitem>
- <para>The (optional) library section specifies the library
- properties (see <xref linkend="library"/>) and relevant build
- information (see <xref linkend="buildinfo"/>).</para>
- </listitem>
- <listitem>
- <para>Following is an arbitrary number of executable sections
- which describe an executable program and (see <xref
- linkend="executable"/>) relevant build information (see <xref
- linkend="buildinfo"/>).</para>
- </listitem>
- </itemizedlist>
-
- <para>Each section consists of a number of property descriptions
- in the form of field/value pairs, with a syntax roughly like mail
- message headers.</para>
- <itemizedlist>
- <listitem>
- <para>Case is not significant in field names,
- but is significant in field values.</para>
- </listitem>
- <listitem>
- <para>To continue a field value, indent the next line
- relative to the field name.</para>
- </listitem>
- <listitem>
- <para>Field names may be indented, but all field values in
- the same section must use the same indentation.</para>
- </listitem>
- <listitem>
- <para>Tabs are <emphasis>not</emphasis> allowed as
- indentation characters due to a missing standard
- interpretation of tab width.</para>
- </listitem>
- <listitem>
- <para>To get a blank line in a field value, use an indented
- <quote><literal>.</literal></quote></para>
- </listitem>
- </itemizedlist>
- <para>The syntax of the value depends on the field. Field types
- include:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <replaceable>token</replaceable>
- </term>
- <term>
- <replaceable>filename</replaceable>
- </term>
- <term>
- <replaceable>directory</replaceable>
- </term>
- <listitem>
- <para>Either 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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <replaceable>freeform</replaceable>
- </term>
- <term>
- <replaceable>URL</replaceable>
- </term>
- <term>
- <replaceable>address</replaceable>
- </term>
- <listitem>
- <para>An arbitrary, uninterpreted string.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <replaceable>identifier</replaceable>
- </term>
- <listitem>
- <para>A letter followed by zero or more alphanumerics
- or underscores.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <replaceable>compiler</replaceable>
- </term>
- <listitem>
- <para>A compiler flavor (one
- of: <literal>GHC</literal>, <literal>NHC</literal>,
- <literal>YHC</literal>, <literal>Hugs</literal>,
- <literal>HBC</literal>, <literal>Helium</literal>,
- <literal>JHC</literal>, or <literal>LHC</literal>)
- followed by a version range. For example,
- <literal>GHC ==6.10.3</literal>,
- or <literal>LHC >=0.6 && <0.8</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <note>
- <title>Modules and preprocessors</title>
- <para>Haskell module names listed in the
- <literal>exposed-modules</literal> and
- <literal>other-modules</literal> fields may
- correspond to Haskell source files, i.e. with names
- ending in <quote><literal>.hs</literal></quote> or
- <quote><literal>.lhs</literal></quote>, or to inputs for
- various Haskell preprocessors.
- The simple build infrastructure understands the extensions
- <quote><literal>.gc</literal></quote> (&Greencard;),
- <quote><literal>.chs</literal></quote> (&C2hs;),
- <quote><literal>.hsc</literal></quote> (<command>hsc2hs</command>),
- <quote><literal>.y</literal></quote> and
- <quote><literal>.ly</literal></quote> (&Happy;),
- <quote><literal>.x</literal></quote> (&Alex;)
- and
- <quote><literal>.cpphs</literal></quote> (&Cpphs;).
- When building, Cabal will automatically run the appropriate
- preprocessor and compile the Haskell module it produces.</para>
- </note>
-
- <para>Some fields take lists of values, which
- are optionally separated by commas, except for the
- <literal>build-depends</literal> field, where the commas are
- mandatory.</para>
-
- <para>Some fields are marked as required. All others are optional,
- and unless otherwise specified have empty default values.</para>
-
- <sect3 id="general-fields">
- <title>Package properties</title>
-
- <para>These fields may occur in the first top-level properties
- section and describe the package as a whole:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <literal>name:</literal> <replaceable>package-name</replaceable>
- (required)
- </term>
- <listitem>
- <para>The unique name of the package
- (see <xref linkend="packages"/>), without the version
- number.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>version:</literal> <replaceable>numbers</replaceable>
- (required)
- </term>
- <listitem>
- <para>The package version number, usually consisting of a
- sequence of natural numbers separated by dots.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>cabal-version:</literal> <replaceable>>, <=, etc. & numbers</replaceable>
- </term>
- <listitem>
- <para>The 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 <literal>.cabal</literal>
- file so that it will appear as a syntax error before any
- others, since old versions of Cabal unfortunately do not
- recognize this field.</para>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>build-type:</literal> <replaceable>identifier</replaceable>
- </term>
- <listitem>
- <para>The type of build used by this package.
- Build types are the constructors of the &BuildType; type,
- defaulting to <literal>Custom</literal>.
- If this field is given a value other than
- <literal>Custom</literal>, some tools such as
- <literal>cabal-install</literal> will be able to
- build the package without using the setup script. So if you are
- just using the default <literal>Setup.hs</literal> then set
- the build type as <literal>Simple</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>license:</literal> <replaceable>identifier</replaceable>
- (default: <literal>AllRightsReserved</literal>)
- </term>
- <listitem>
- <para>The type of license under which this package is
- distributed. License names are the constants of the
- &License; type.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>license-file:</literal>
- <replaceable>filename</replaceable>
- </term>
- <listitem>
- <para>The name of a file containing the precise license
- for this package. It will be installed with the package.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>copyright:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>The 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.</para>
- <para>For example:
- <literal>Copyright: (c) 2006-2007 Joe Bloggs</literal>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>author:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>The original author of the package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>maintainer:</literal>
- <replaceable>address</replaceable>
- </term>
- <listitem>
- <para>The current maintainer or maintainers of the package.
- This is an e-mail address to which users should send bug
- reports, feature requests and patches.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>stability:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>The stability level of the package, e.g.
- <literal>alpha</literal>, <literal>experimental</literal>,
- <literal>provisional</literal>,
- <literal>stable</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>homepage:</literal> <replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>The package homepage.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>bug-reports:</literal> <replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>
- The URL where users should direct bug reports. This would
- normally be either:
- <itemizedlist>
- <listitem>
- <para>
- A <literal>mailto:</literal> URL, eg for a person or a
- mailing list.
- </para>
- </listitem>
- <listitem>
- <para>
- An <literal>http:</literal> (or <literal>https:</literal>)
- URL for an online bug tracking system.
- </para>
- </listitem>
- </itemizedlist>
- For example Cabal itself uses a web-based bug tracking system
- <programlisting>bug-reports: http://hackage.haskell.org/trac/hackage/</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>package-url:</literal> <replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>The location of a source bundle for the package.
- The distribution should be a Cabal package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>synopsis:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>A 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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>description:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>Description of the package. This may be several
- paragraphs, and should be aimed at a Haskell programmer
- who has never heard of your package before.</para>
-
- <para>For library packages, this field is used as
- prologue text by <command>setup haddock</command>
- (see <xref linkend="setup-haddock"/>), and thus may
- contain the same markup as &Haddock; documentation
- comments.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>category:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>A classification category for future use by the
- package catalogue <firstterm>Hackage</firstterm>. These
- categories have not yet been specified, but the upper
- levels of the module hierarchy make a good start.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>tested-with:</literal>
- <replaceable>compiler list</replaceable>
- </term>
- <listitem>
- <para>A list of compilers and versions against which the
- package has been tested (or at least built).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>data-files:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A 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
- <xref linkend="paths-module"/>.</para>
- <para>
- A limited form of <literal>*</literal> wildcards in file names,
- for example <literal>data-files: images/*.png</literal> matches
- all the <literal>.png</literal> files in the
- <literal>images</literal> directory.
- </para>
- <para>
- The limitation is that <literal>*</literal> wildcards are only
- allowed in place of the file name, not in the directory name or
- file extension. In particular, wildcards do not include
- directories contents recursively. Furthermore, if a wildcard is
- used it must be used with an extension, so <literal>data-files:
- data/*</literal> is not allowed. When matching a wildcard plus
- extension, a file's full extension must match exactly, so
- <literal>*.gz</literal> matches <literal>foo.gz</literal> but
- not <literal>foo.tar.gz</literal>. A wildcard that does not
- match any files is an error.
- </para>
- <para>
- The reason for providing only a very limited form of wildcard
- is to concisely express the common case of a large number of
- related files of the same file type without making it too easy
- to accidentally include unwanted files.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>data-dir:</literal>
- <replaceable>directory</replaceable>
- </term>
- <listitem>
- <para>The directory where Cabal looks for data files to install,
- relative to the source directory. By default, Cabal will look
- in the source directory itself.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>extra-source-files:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A list of additional files to be included in source
- distributions built with <command>setup sdist</command>
- (see <xref linkend="setup-sdist"/>).</para>
- <para>As with <literal>data-files</literal> it can use a limited
- form of <literal>*</literal> wildcards in file names.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>extra-tmp-files:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A list of additional files or directories to be
- removed by <command>setup clean</command>
- (see <xref linkend="setup-clean"/>).
- These would typically be additional files created by
- additional hooks, such as the scheme described in
- <xref linkend="system-dependent"/>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="library">
- <title>Library</title>
-
- <para>The library section should contain the following
- fields:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <literal>exposed-modules:</literal>
- <replaceable>identifier list</replaceable>
- (required if this package contains a library)
- </term>
- <listitem>
- <para>A list of modules added by this package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>exposed:</literal> <replaceable>boolean</replaceable>
- (default: <literal>True</literal>)
- </term>
- <listitem>
- <para>
- Some Haskell compilers (notably GHC) support the notion of
- packages being <quote>exposed</quote> or <quote>hidden</quote>
- which means the modules they provide can be easily imported
- without always having to specify which package they come from.
- However this only works effectively if the modules provided by
- all exposed packages do not overlap (otherwise a module import
- would be ambiguous).
- </para>
- <para>
- Almost all new libraries use hierarchical module names that do
- not clash, so it is very uncommon to have to use this field.
- However it may be necessary to set <literal>exposed:
- False</literal> for some old libraries that use a flat module
- namespace or where it is known that the exposed modules would
- clash with other common modules.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>The library section may also contain build information fields
- (see <xref linkend="buildinfo"/>).</para>
- </sect3>
-
- <sect3 id="executable">
- <title>Executables</title>
-
- <para>Executable 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.</para>
-
- <para>The executable may be described using the following
- fields, as well as build information fields (see <xref
- linkend="buildinfo"/>).</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <literal>main-is:</literal> <replaceable>filename</replaceable>
- (required)
- </term>
- <listitem>
- <para>The name of the <filename>.hs</filename> or
- <filename>.lhs</filename> file containing the
- <literal>Main</literal> module. Note that it is the
- <filename>.hs</filename> filename that must be listed, even if
- that file is generated using a preprocessor. The source
- file must be relative to one of the directories listed in
- <literal>hs-source-dirs</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="buildinfo">
- <title>Build information</title>
-
- <para>The 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
- <xref linkend="system-dependent"/> and <xref linkend="configurations"/>
- for a way to supply system-dependent values for these
- fields.</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <literal>build-depends:</literal>
- <replaceable>package list</replaceable>
- </term>
- <listitem>
- <para>A list of packages needed to build this one. Each package
- can be annotated with a version constraint.
- </para>
- <para>
- Version constraints use the operators <literal>==, >=, >,
- <, <=</literal> and a version number. Multiple
- constraints can be combined using <literal>&&</literal>
- or <literal>||</literal>. If no version constraint is
- specified, any version is assumed to be acceptable.
- For example:
- </para>
- <programlisting>
-library
- build-depends:
- base >= 2,
- foo >= 1.2 && < 1.3,
- bar
-</programlisting>
- <para>
- Dependencies like <literal>foo >= 1.2 && < 1.3</literal> turn
- out to be very common because it is recommended practise for
- package versions to correspond to API versions. There is a
- special syntax to support this use:
- </para>
- <programlisting>build-depends: foo ==1.2.*</programlisting>
- <para>
- It is only syntactic sugar. It is exactly equivalent to
- <literal>foo >= 1.2 && < 1.3</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>other-modules:</literal>
- <replaceable>identifier list</replaceable>
- </term>
- <listitem>
- <para>A 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 <literal>main-is</literal> field.</para>
- <note>
- <para>Every module in the package <emphasis>must</emphasis> be
- listed in one of <literal>other-modules</literal>,
- <literal>exposed-modules</literal> or
- <literal>main-is</literal> fields.
- </para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>hs-source-dirs:</literal>
- <replaceable>directory list</replaceable>
- (default: <quote><literal>.</literal></quote>)
- </term>
- <listitem>
- <para>Root directories for the module hierarchy.</para>
-
- <para>For backwards compatibility, the old variant
- <literal>hs-source-dir</literal> is also recognized.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>extensions:</literal>
- <replaceable>identifier list</replaceable>
- </term>
- <listitem>
- <para>A list of Haskell extensions used by every module.
- Extension names are the constructors of the &Extension; type.
- These determine corresponding compiler options.
- In particular, <literal>CPP</literal> specifies that
- Haskell source files are to be preprocessed with a
- C preprocessor.</para>
-
- <para>Extensions used only by one module may be specified
- by placing a <literal>LANGUAGE</literal> pragma in the
- source file affected, e.g.:</para>
- <programlisting>{-# LANGUAGE CPP, MultiParamTypeClasses #-}</programlisting>
- <note>
- <para>GHC versions prior to 6.6 do not support the
- <literal>LANGUAGE</literal> pragma.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>build-tools:</literal>
- <replaceable>program list</replaceable>
- </term>
- <listitem>
- <para>A list of programs, possibly annotated with versions,
- needed to build this package,
- e.g. <literal>c2hs > 0.15, cpphs</literal>.
- If no version constraint is specified, any version is
- assumed to be acceptable.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>buildable:</literal> <replaceable>boolean</replaceable>
- (default: <literal>True</literal>)
- </term>
- <listitem>
- <para>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
- <xref linkend="system-dependent"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>ghc-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Additional options for GHC. You can often achieve
- the same effect using the <literal>extensions</literal>
- field, which is preferred.</para>
-
- <para>Options required only by one module may be specified
- by placing an <literal>OPTIONS_GHC</literal> pragma in the
- source file affected.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>ghc-prof-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Additional options for GHC when the package is built
- with profiling enabled.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>ghc-shared-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Additional options for GHC when the package is
- built as shared library.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>hugs-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Additional options for Hugs. You can often achieve
- the same effect using the <literal>extensions</literal>
- field, which is preferred.</para>
-
- <para>Options required only by one module may be specified
- by placing an <literal>OPTIONS_HUGS</literal> pragma in the
- source file affected.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>nhc98-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Additional options for nhc98. You can often achieve
- the same effect using the <literal>extensions</literal>
- field, which is preferred.</para>
-
- <para>Options required only by one module may be specified
- by placing an <literal>OPTIONS_NHC98</literal> pragma in the
- source file affected.</para>
-
- <para>Warning: Cabal does not currently support building
- libraries or executables with nhc98 anyway.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>includes:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A 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 installed. These files
- typically contain function prototypes for foreign imports
- used by the package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>install-includes:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A list of header files from this package to be
- installed into
- <literal>$libdir/includes</literal> when the package
- is installed. Files listed in
- <literal>install-includes:</literal> should be found in
- relative to the top of the source tree or relative to one of the
- directories listed in <literal>include-dirs</literal>.</para>
-
- <para><literal>install-includes</literal> 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
- <literal>includes:</literal> field as well.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>include-dirs:</literal>
- <replaceable>directory list</replaceable>
- </term>
- <listitem>
- <para>A list of directories to search for header files,
- when preprocessing with <command>c2hs</command>,
- <command>hsc2hs</command>, <command>ffihugs</command>,
- <command>cpphs</command> or the C preprocessor,
- and also when compiling via C.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>c-sources:</literal>
- <replaceable>filename list</replaceable>
- </term>
- <listitem>
- <para>A list of C source files to be compiled
- and linked with the Haskell files.</para>
-
- <para>If you use this field, you should also name the
- C files in <literal>CFILES</literal> pragmas in the
- Haskell source files that use them, e.g.:
- <screen>{-# CFILES dir/file1.c dir/file2.c #-}</screen>
- These are ignored by the compilers, but needed by Hugs.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>extra-libraries:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>A list of extra libraries to link with.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>extra-lib-dirs:</literal>
- <replaceable>directory list</replaceable>
- </term>
- <listitem>
- <para>A list of directories to search for libraries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>cc-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Command-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
- <xref linkend="system-dependent"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>ld-options:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>Command-line arguments to be passed to the linker.
- Since the arguments are compiler-dependent, this field
- is more useful with the setup described in
- <xref linkend="system-dependent"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>pkgconfig-depends:</literal>
- <replaceable>package list</replaceable>
- </term>
- <listitem>
- <para>A list of &PkgConfig; packages, needed to build this
- package. They can be annotated with versions,
- e.g. <literal>gtk+-2.0 >= 2.10, cairo >= 1.0</literal>.
- If no version constraint is specified, any version is
- assumed to be acceptable. Cabal uses
- <literal>pkg-config</literal> to find if the packages are
- available on the system and to find the extra compilation and
- linker options needed to use the packages.
- </para>
- <para> If you need to bind to a C library that supports
- <literal>pkg-config</literal> (use
- <literal>pkg-config --list-all</literal> 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>frameworks:</literal>
- <replaceable>token list</replaceable>
- </term>
- <listitem>
- <para>On 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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="configurations">
- <title>Configurations</title>
- <para>Library 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.</para>
- <para>Here is an example package description file using
- configurations:</para>
- <example id="package-with-configurations-example">
- <title>A package containing a library and executable programs</title>
-
- <programlisting>Name: 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(windows)
- 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
-</programlisting>
- </example>
- <sect4>
- <title>Layout</title>
- <para>Flags, 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.</para>
-
- <para>As an alternative to using layout you can also use explicit braces
- <literal>{}</literal>. 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:</para>
- <example id="configurations-with-braces-example">
- <title>Using explicit braces rather than indentation for layout</title>
-
- <programlisting>Name: 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(windows) {
- CC-Options: "-DDEBUG"
- } else {
- CC-Options: "-DNDEBUG"
- }
- }
-}
-</programlisting>
- </example>
- </sect4>
- <sect4>
- <title>Configuration Flags</title>
- <para>A flag section takes the flag name as an argument and
- may contain the following fields.</para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>description:</literal>
- <replaceable>freeform</replaceable>
- </term>
- <listitem>
- <para>The description of this flag.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>default:</literal>
- <replaceable>boolean</replaceable>
- (default: <literal>True</literal>)
- </term>
- <listitem>
- <para>The default value of this flag.</para>
- <para>Note that this value may be overridden in several
- ways (see <xref linkend="flag-control"/>). 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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>manual:</literal>
- <replaceable>boolean</replaceable>
- (default: <literal>False</literal>)
- </term>
- <listitem>
- <para>By default, Cabal will first try to satisfy
- dependencies with the default flag value and then,
- if that is not possible, with the negated value.
- However, if the flag is manual, then the default
- value (which can be overridden by commandline flags)
- will be used.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- <sect4 id="conditionals">
- <title>Conditional Blocks</title>
- <para>Conditional blocks may appear anywhere inside a
- library or executable section. They have to follow rather
- strict formatting rules.</para>
- <para>Conditional blocks must always be of the shape
- <literallayout>
- <literal>if </literal><replaceable>condition</replaceable>
- <replaceable>property-descriptions-or-conditionals*</replaceable>
- </literallayout>or
- <literallayout>
- <literal>if </literal><replaceable>condition</replaceable>
- <replaceable>property-descriptions-or-conditionals*</replaceable>
- <literal>else</literal>
- <replaceable>property-descriptions-or-conditionals*</replaceable>
- </literallayout></para>
-
- <para>Note that the <literal>if</literal> and the condition have to
- be all on the same line.</para>
-
- </sect4>
- <sect4 id="conditions">
- <title>Conditions</title>
- <para>Conditions can be formed using boolean tests and the
- boolean operators <literal>||</literal> (disjunction /
- logical "or"), <literal>&&</literal> (conjunction /
- logical "and"), or <literal>!</literal> (negation / logical
- "not"). The unary <literal>!</literal> takes highest
- precedence, <literal>||</literal> takes lowest. Precedence
- levels may be overridden through the use of parentheses.
- For example, <literal>os(darwin) && !arch(i386) || os(freebsd)</literal>
- is equivalent to <literal>(os(darwin) && !(arch(i386))) || os(freebsd)</literal>.
- </para>
- <para>The following tests are currently supported.</para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>os(</literal>
- <replaceable>name</replaceable>
- <literal>)</literal>
- </term>
- <listitem>
- <para>Tests if the current operating system is
- <replaceable>name</replaceable>. The argument is tested
- against <literal>System.Info.os</literal> on
- the target system. There is unfortunately some disagreement
- between Haskell implementations about the standard values of
- <literal>System.Info.os</literal>. Cabal canonicalises it so
- that in particular <literal>os(windows)</literal> works on all
- implementations. If the canonicalised os names match, this test
- evaluates to true, otherwise false. The match is
- case-insensitive. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>arch(</literal>
- <replaceable>name</replaceable>
- <literal>)</literal>
- </term>
- <listitem>
- <para>Tests if the current architecture is
- <replaceable>name</replaceable>. The argument is matched
- against <literal>System.Info.arch</literal> on the target system.
- If the arch names match, this test evaluates to true,
- otherwise false. The match is case-insensitive. </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>impl(</literal>
- <replaceable>compiler</replaceable>
- <literal>)</literal>
- </term>
- <listitem>
- <para>Tests for the configured Haskell implementation. An optional
- version constraint may be specified (for example
- <literal>impl(ghc >= 6.6.1)</literal>). 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.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <term>
- <literal>flag(</literal>
- <replaceable>name</replaceable>
- <literal>)</literal>
- </term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>true</literal>
- </term>
- <listitem>
- <para>Constant value true.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>false</literal>
- </term>
- <listitem>
- <para>Constant value false.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect4>
- <sect4 id="conditional-resolution">
- <title>Resolution of Conditions and Flags</title>
- <para>If a package descriptions specifies configuration flags
- the package user can control these in several ways (see
- <xref linkend="flag-control"/>). If the user does not fix the
- value of a flag, Cabal will try to find a flag assignment in the
- following way.</para>
- <itemizedlist>
- <listitem>
- <para>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.</para>
- </listitem>
- <listitem>
- <para>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.</para>
- </listitem>
- </itemizedlist>
-
- <para>To put it another way, Cabal does a complete backtracking
- search to find a satisfiable package configuration. It is only the
- dependencies specified in the <literal>build-depends</literal> field
- in conditional blocks that determine if a particular flag assignment
- is satisfiable (<literal>build-tools</literal> are not considered).
- The order of the declaration and the default value of the flags
- determines the search order. Flags overridden on the command line fix
- the assignment of that flag, so no backtracking will be tried for
- that flag.</para>
-
- <para>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.</para>
- </sect4>
- <sect4 id="prop-combine">
- <title>Meaning of field values when using conditionals</title>
- <para>During 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.</para>
- <itemizedlist>
- <listitem>
- <para>Boolean fields are combined using conjunction
- (logical "and").</para>
- </listitem>
- <listitem>
- <para>List fields are combined by appending the inner
- items to the outer items, for example
- <programlisting>Extensions: CPP
-if impl(ghc) || impl(hugs)
- Extensions: MultiParamTypeClasses
-</programlisting>
- when compiled using Hugs or GHC will be combined to
- <programlisting>Extensions: CPP, MultiParamTypeClasses</programlisting>
- </para>
- <para>Similarly, if two conditional sections appear at the
- same nesting level, properties specified in the latter
- will come after properties specified in the former.</para>
- </listitem>
- <listitem>
- <para>All other fields must not be specified in ambiguous ways. For example
- <programlisting>Main-is: Main.hs
-if flag(useothermain)
- Main-is: OtherMain.hs
-</programlisting>
- will lead to an error. Instead use
- <programlisting>if flag(useothermain)
- Main-is: OtherMain.hs
-else
- Main-is: Main.hs
-</programlisting></para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
-
- <sect3 id="source-repos">
- <title>Source Repositories</title>
- <para>
- It is often useful to be able to specify a source revision control
- repository for a package. Cabal lets you specifying this information
- in a relatively structured form which enables other tools to
- interpret and make effective use of the information. For example the
- information should be sufficient for an automatic tool to checkout
- the sources.
- </para>
- <para>
- Cabal supports specifying different information for various common
- source control systems. Obviously not all automated tools will
- support all source control systems.
- </para>
- <para>
- Cabal supports specifying repositories for different use cases. By
- declaring which case we mean automated tools can be more useful.
- There are currently two kinds defined:
- <itemizedlist>
- <listitem>
- <para>
- The <literal>head</literal> kind refers to the
- latest development branch of the package. This may be used for
- example to track activity of a project or as an indication to
- outside developers what sources to get for making new
- contributions.
- </para>
- </listitem>
- <listitem>
- <para>
- The <literal>this</literal> kind refers to the
- branch and tag of a repository that contains the sources for this
- version or release of a package. For most source control systems
- this involves specifying a tag, id or hash of some form and
- perhaps a branch. The purpose is to be able to reconstruct the
- sources corresponding to a particular package version. This might
- be used to indicate what sources to get if someone needs to fix a
- bug in an older branch that is no longer an active head branch.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- You can specify one kind or the other or both. As an example here are
- the repositories for the Cabal library. Note that the
- <literal>this</literal> kind of repo specifies a tag.
- <programlisting>
-source-repository head
- type: darcs
- location: http://darcs.haskell.org/cabal/
-
-source-repository this
- type: darcs
- location: http://darcs.haskell.org/cabal-branches/cabal-1.6/
- tag: 1.6.1
-</programlisting>
- </para>
- <para>
- The exact fields are as follows:
- </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>type:</literal>
- <replaceable>token</replaceable>
- </term>
- <listitem>
- <para>
- The name of the source control system used for this repository.
- The currently recognised types are:
- <itemizedlist>
- <listitem><para>darcs</para></listitem>
- <listitem><para>git</para></listitem>
- <listitem><para>svn</para></listitem>
- <listitem><para>cvs</para></listitem>
- <listitem><para>mercurial (or alias hg)</para></listitem>
- <listitem><para>bazaar (or alias bzr)</para></listitem>
- <listitem><para>arch</para></listitem>
- <listitem><para>monotone</para></listitem>
- </itemizedlist>
- </para>
- <para>
- This field is required.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>location:</literal>
- <replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>
- The location of the repository. The exact form of this field
- depends on the repository type. For example:
- <itemizedlist>
- <listitem>
- <para>for darcs: <literal>http://code.haskell.org/foo/</literal></para>
- </listitem>
- <listitem>
- <para>for git: <literal>git://github.com/foo/bar.git</literal></para>
- </listitem>
- <listitem>
- <para>for CVS: <literal>anoncvs@cvs.foo.org:/cvs</literal></para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- This field is required.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>module:</literal>
- <replaceable>token</replaceable>
- </term>
- <listitem>
- <para>
- CVS requires a named module, as each CVS server can host multiple
- named repositories.
- </para>
- <para>
- This field is required for the CVS repo type and should not be
- used otherwise.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>branch:</literal>
- <replaceable>token</replaceable>
- </term>
- <listitem>
- <para>
- Many source control systems support the notion of a branch,
- as a distinct concept from having repositories in separate
- locations. For example CVS, SVN and git use branches while for
- darcs uses different locations for different branches. If you
- need to specify a branch to identify a your repository
- then specify it in this field.
- </para>
- <para>
- This field is optional.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>tag:</literal>
- <replaceable>token</replaceable>
- </term>
- <listitem>
- <para>
- A tag identifies a particular state of a source repository. The
- tag can be used with a <literal>this</literal> repo kind to
- identify the state of a repo corresponding to a particular
- package version or release. The exact form of the tag depends on
- the repository type.
- </para>
- <para>
- This field is required for the <literal>this</literal> repo kind.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>subdir:</literal>
- <replaceable>directory</replaceable>
- </term>
- <listitem>
- <para>
- Some projects put the sources for multiple packages under a
- single source repository. This field lets you specify the
- relative path from the root of the repository to the top
- directory for the package, ie the directory containing the
- package's <literal>.cabal</literal> file.
- </para>
- <para>
- This field is optional. It default to empty which corresponds to
- the root directory of the repository.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="paths-module">
- <title>Accessing data files from package code</title>
- <para>The placement on the target system of files listed in the
- <literal>data-files</literal> field varies between systems, and in
- some cases one can even move packages around after installation
- (see <xref linkend="prefix-independence"/>). To enable packages
- to find these files in a portable way, Cabal generates a module
- called <literal>Paths_</literal><replaceable>pkgname</replaceable>
- (with any hyphens in <replaceable>pkgname</replaceable> replaced
- by underscores) during building, so that it may be imported by
- modules of the package. This module defines a function
- <programlisting>getDataFileName :: FilePath -> IO FilePath</programlisting>
- If the argument is a filename listed in the
- <literal>data-files</literal> field, the result is the name
- of the corresponding file on the system on which the program
- is running.</para>
- <note>
- <para>If you decide to import the
- <literal>Paths_</literal><replaceable>pkgname</replaceable> module then
- it <emphasis>must</emphasis> be listed in the
- <literal>other-modules</literal> field just like any other module in
- your package.
- </para>
- <para>The <literal>Paths_</literal><replaceable>pkgname</replaceable>
- module is not platform independent so it does not get included in the
- source tarballs generated by <command>sdist</command>.
- </para>
- </note>
- </sect2>
-
- <sect2 id="system-dependent">
- <title>System-dependent parameters</title>
-
- <para>For 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 <literal>build-type</literal>
- <literal>Configure</literal>) handles many such situations using
- a slightly longer <filename>Setup.hs</filename>:</para>
- <programlisting>
-import Distribution.Simple
-main = defaultMainWithHooks autoconfUserHooks</programlisting>
-
- <para>Most packages, however, would probably do better with
- configurations (see <xref linkend="configurations"/>).</para>
-
- <para>This program differs from <literal>defaultMain</literal>
- in two ways:</para>
- <orderedlist>
- <listitem>
- <para>The package root directory must contain a shell script called
- <filename>configure</filename>. The configure step will run the
- script. This <filename>configure</filename> script may
- be produced by &Autoconf; or may be hand-written. The
- <filename>configure</filename> script 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.)</para>
- </listitem>
-
- <listitem>
- <para>If the package root directory contains a file called
- <replaceable>package</replaceable><literal>.buildinfo</literal>
- after the configuration step, subsequent steps will read it
- to obtain additional settings for build information fields
- (see <xref linkend="buildinfo"/>), to be merged with the
- ones given in the <literal>.cabal</literal> file.
- In particular, this file may be generated by the
- <filename>configure</filename> script mentioned above,
- allowing these settings to vary depending on the build
- environment.</para>
-
- <para>The build information file should have the following
- structure:</para>
- <programlisting>
-<replaceable>buildinfo</replaceable>
-
-executable: <replaceable>name</replaceable>
-<replaceable>buildinfo</replaceable>
-
-executable: <replaceable>name</replaceable>
-<replaceable>buildinfo</replaceable>
-
-...</programlisting>
- <para>where each <replaceable>buildinfo</replaceable> consists
- of settings of fields listed in <xref linkend="buildinfo"/>.
- 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.)</para>
-
- </listitem>
- </orderedlist>
-
- <para>Neither of these files is required. If they are absent, this
- setup script is equivalent to <literal>defaultMain</literal>.</para>
-
- <example id="autoconf-example">
- <title>Using autoconf</title>
-
- <para>(This example is for people familiar with the &Autoconf;
- tools.)</para>
-
- <para>In the X11 package, the file <filename>configure.ac</filename>
- contains:</para>
- <programlisting>
-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_OUTPUT</programlisting>
-
- <para>Then the setup script will run the
- <literal>configure</literal> script, which checks for the
- presence of the X11 libraries and substitutes for variables
- in the file <filename>X11.buildinfo.in</filename>:</para>
- <programlisting>
-buildable: @BUILD_PACKAGE_BOOL@
-cc-options: @X_CFLAGS@
-ld-options: @X_LIBS@</programlisting>
-
- <para>This generates a file <filename>X11.buildinfo</filename>
- supplying the parameters needed by later stages:</para>
- <programlisting>
-buildable: True
-cc-options: -I/usr/X11R6/include
-ld-options: -L/usr/X11R6/lib</programlisting>
-
- <para>The <filename>configure</filename> script also generates
- a header file <filename>include/HsX11Config.h</filename>
- 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.</para>
- </example>
-
- <note>
- <para>Packages using these features will also need to list
- additional files such as <filename>configure</filename>,
- templates for <literal>.buildinfo</literal> files, files named
- only in <literal>.buildinfo</literal> files, header files and
- so on in the <literal>extra-source-files</literal> field,
- to ensure that they are included in source distributions.
- They should also list files and directories generated by
- <command>configure</command> in the
- <literal>extra-tmp-files</literal> field to ensure that they
- are removed by <command>setup clean</command>.</para>
- </note>
- </sect2>
-
- <sect2 id="cpp">
- <title>Conditional compilation</title>
-
- <para>Sometimes you want to write code that works with more than
- one version of a dependency. You can specify a range of
- versions for the depenency in
- the <literal>build-depends</literal>, but how do you then write
- the code that can use different versions of the API?</para>
-
- <para>Haskell lets you preprocess your code using the C
- preprocessor (either the real C preprocessor, or
- <literal>cpphs</literal>). To enable this,
- add <literal>extensions: CPP</literal> to your package
- description. When using CPP, Cabal provides some pre-defined
- macros to let you test the version of dependent packages; for
- example, suppose your package works with either version 3 or
- version 4 of the <literal>base</literal> package, you could
- select the available version in your Haskell modules like
- this:</para>
-<programlisting>
-#if MIN_VERSION_base(4,0,0)
-... code that works with base-4 ...
-#else
-... code that works with base-3 ...
-#endif
-</programlisting>
-<para>In general, Cabal supplies a
- macro <literal>MIN_VERSION_<replaceable>package</replaceable>(A,B,C)</literal>
- for each package depended on via <literal>build-depends</literal>.
- This macro is true if the actual version of the package in use is
- greater than or equal to <literal>A.B.C</literal> (using the
- conventional ordering on version numbers, which is lexicographic on
- the sequence, but numeric on each component, so for example 1.2.0 is
- greater than 1.0.3).</para>
-
- <para>Cabal places the definitions of these macros into an
- automatically-generated header file, which is included when
- preprocessing Haskell source code by passing options to the C
- preprocessor.</para>
- </sect2>
-
- <sect2 id="complex-packages">
- <title>More complex packages</title>
-
- <para>For packages that don't fit the simple schemes described above,
- you have a few options:</para>
-
- <itemizedlist>
- <listitem>
- <para>You can customize the simple build infrastructure
- using <firstterm>hooks</firstterm>. These allow you to
- perform additional actions before and after each command is
- run, and also to specify additional preprocessors. See
- <literal>UserHooks</literal> in &Simple; for the details,
- but note that this interface is experimental, and likely to
- change in future releases.</para>
- </listitem>
-
- <listitem>
- <para>You could delegate all the work to <command>make</command>,
- though this is unlikely to be very portable.
- Cabal supports this with the <literal>build-type</literal>
- <literal>Make</literal> and a trivial setup library &Make;,
- which simply parses the command line arguments and invokes
- <command>make</command>. Here <filename>Setup.hs</filename>
- looks like</para>
- <programlisting>
-import Distribution.Make
-main = defaultMain</programlisting>
-
- <para>The root directory of the package should contain
- a <filename>configure</filename> script, and, after
- that has run, a <filename>Makefile</filename> with a
- default target that builds the package, plus targets
- <literal>install</literal>, <literal>register</literal>,
- <literal>unregister</literal>, <literal>clean</literal>,
- <literal>dist</literal> and <literal>docs</literal>.
- Some options to commands are passed through as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <option>--with-hc-pkg</option>,
- <option>--prefix</option>, <option>--bindir</option>,
- <option>--libdir</option>, <option>--datadir</option>
- and <option>--libexecdir</option> options to the
- <literal>configure</literal> command are passed on to
- the <filename>configure</filename> script.
- In addition the value of the <option>--with-compiler</option>
- option is passed in a <option>--with-hc</option> option and
- all options specified with <option>--configure-option</option>=
- are passed on.</para>
- </listitem>
-
- <listitem>
- <para>the <literal>--destdir</literal> option to the
- <literal>copy</literal> command becomes a setting of a
- <literal>destdir</literal> variable on the invocation of
- <literal>make copy</literal>. The supplied
- <literal>Makefile</literal> should provide a
- <literal>copy</literal> target, which will probably
- look like this:
-<programlisting>
-copy :
- $(MAKE) install prefix=$(destdir)/$(prefix) \
- bindir=$(destdir)/$(bindir) \
- libdir=$(destdir)/$(libdir) \
- datadir=$(destdir)/$(datadir) \
- libexecdir=$(destdir)/$(libexecdir)</programlisting>
-</para>
-
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>You can write your own setup script conforming to the
- interface of <xref linkend="builders"/>, possibly using
- the Cabal library for part of the work. One option is to
- copy the source of <literal>Distribution.Simple</literal>,
- and alter it for your needs. Good luck.</para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1 id="builders">
- <title>Building and installing a package</title>
- <para>After you've unpacked a Cabal package, you can build it
- by moving into the root directory of the package and using the
- <filename>Setup.hs</filename> or <filename>Setup.lhs</filename>
- script there:</para>
- <cmdsynopsis>
- <command>runhaskell Setup.hs</command>
- <arg><replaceable>command</replaceable></arg>
- <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
- </cmdsynopsis>
- <para>where <replaceable>runhaskell</replaceable> might be
- <command>runhugs</command>, <command>runghc</command> or
- <command>runnhc</command>. The <replaceable>command</replaceable>
- argument selects a particular step in the build/install process.
- You can also get a summary of the command syntax with</para>
- <cmdsynopsis>
- <command>runhaskell Setup.hs <option>--help</option></command>
- </cmdsynopsis>
-
- <example id="system-install-example">
- <title>Building and installing a system package</title>
- <screen>
-runhaskell Setup.hs configure --ghc
-runhaskell Setup.hs build
-runhaskell Setup.hs install</screen>
- <para>The 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.</para>
- </example>
-
- <example id="user-install-example">
- <title>Building and installing a user package</title>
- <screen>
-runhaskell Setup.hs configure --user
-runhaskell Setup.hs build
-runhaskell Setup.hs install</screen>
- <para>The package is installed under the user's home directory
- and is registered in the user's package database
- (<option>--user</option>).</para>
- </example>
-
- <example id="binary-package-example">
- <title>Creating a binary package</title>
- <para>When 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:</para>
- <screen>
-runhaskell Setup.hs configure --prefix=/usr
-runhaskell Setup.hs build
-runhaskell Setup.hs copy --destdir=/tmp/mypkg
-tar -czf mypkg.tar.gz /tmp/mypkg/</screen>
-
- <para>If the package contains a library, you need two additional
- steps:</para>
- <screen>
-runhaskell Setup.hs register --gen-script
-runhaskell Setup.hs unregister --gen-script</screen>
- <para>This creates shell scripts <filename>register.sh</filename>
- and <filename>unregister.sh</filename>, which must also be sent
- to the target system. After unpacking there, the package must be
- registered by running the <filename>register.sh</filename> script.
- The <filename>unregister.sh</filename> script would be used
- in the uninstall procedure of the package. Similar steps may
- be used for creating binary packages for Windows.</para>
- </example>
-
- <para>The following options are understood by all commands:</para>
- <variablelist>
- <varlistentry>
- <term>
- <option>--help</option>, <option>-h</option> or
- <option>-?</option>
- </term>
- <listitem>
- <para>List the available options for the command.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>--verbose</option>=<replaceable>n</replaceable> or
- <option>-v</option><replaceable>n</replaceable>
- </term>
- <listitem>
- <para>Set the verbosity level (0-3). The normal level is 1;
- a missing <replaceable>n</replaceable> defaults to 2.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>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.</para>
-
- <sect2 id="setup-configure">
- <title>setup configure</title>
- <para>Prepare 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.</para>
-
- <para>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.</para>
-
- <para>If a user-supplied <filename>configure</filename>
- script is run (see <xref linkend="system-dependent"/>
- or <xref linkend="complex-packages"/>), it is passed the
- <option>--with-hc-pkg</option>,
- <option>--prefix</option>, <option>--bindir</option>,
- <option>--libdir</option>, <option>--datadir</option> and
- <option>--libexecdir</option> options.
- In addition the value of the <option>--with-compiler</option>
- option is passed in a <option>--with-hc</option> option and
- all options specified with <option>--configure-option</option>=
- are passed on.</para>
-
- <sect3 id="setup-configure-programs">
- <title>Programs used for building</title>
-
- <para>The following options govern the programs used to process
- the source files of a package:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--ghc</option> or <option>-g</option></term>
- <term><option>--nhc</option></term>
- <term><option>--jhc</option></term>
- <term><option>--hugs</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-compiler</option>=<replaceable>path</replaceable>
- or <option>-w</option><replaceable>path</replaceable></term>
- <listitem>
- <para>Specify 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.</para>
- <para>This flag also sets the default value of the
- <option>--with-hc-pkg</option> option to the package tool
- for this compiler.
- Check the output of <literal>setup configure -v</literal>
- to ensure that it finds the right package tool (or use
- <option>--with-hc-pkg</option> explicitly).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-hc-pkg</option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>Specify the path to the package tool, e.g.
- <command>ghc-pkg</command>.
- The package tool must be compatible with the compiler
- specified by <option>--with-compiler</option>.
- If this option is omitted, the default value is determined
- from the compiler selected.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-<replaceable>prog</replaceable></option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>Specify the path to the program <replaceable>prog</replaceable>.
- Any program known to Cabal can be used in place of
- <replaceable>prog</replaceable>. It can either be a fully
- path or the name of a program that can be found on the program
- search path. For example: <option>--with-ghc=ghc-6.6.1</option>
- or <option>--with-cpphs=/usr/local/bin/cpphs</option>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--<replaceable>prog</replaceable>-options</option>=<replaceable>options</replaceable></term>
- <listitem>
- <para>Specify additional options to the program <replaceable>prog</replaceable>.
- Any program known to Cabal can be used in place of
- <replaceable>prog</replaceable>. For example:
- <option>--alex-options="--template=mytemplatedir/"</option>.</para>
- <para>The <replaceable>options</replaceable> is split into program options
- based on spaces. Any options containing embeded spaced need to
- be quoted, for example
- <literal>--foo-options='--bar="C:\Program File\Bar"'</literal>. As an
- alternative that takes only one option at a time but avoids the
- need to quote, use
- <option>--<replaceable>prog</replaceable>-option</option> instead.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--<replaceable>prog</replaceable>-option</option>=<replaceable>option</replaceable></term>
- <listitem>
- <para>Specify a single additional option to the program
- <replaceable>prog</replaceable>.</para>
- <para>For passing an option that contain embeded spaces, such as a file
- name with embeded spaces, using this rather than
- <option>--<replaceable>prog</replaceable>-options</option> 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 <literal>--foo-options="--bar=C:\Program File\Bar"</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>All of the options passed with either
- <option>--<replaceable>prog</replaceable>-options</option> or
- <option>--<replaceable>prog</replaceable>-option</option> are passed
- in the order they were specified on the configure command line.
- </para>
-
- </sect3>
-
- <sect3 id="setup-configure-paths">
- <title>Installation paths</title>
-
- <para>The following options govern the location of installed files
- from a package:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--prefix</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>The root of the installation. For example for a global
- install you might use
- <filename>/usr/local</filename> on a Unix system, or
- <filename>C:\Program Files</filename> on a Windows system.
- The other installation paths are usually subdirectories of
- <replaceable>prefix</replaceable>, but they don't have
- to be.</para>
- <para>In the simple build system, <replaceable>dir</replaceable>
- may contain the following path variables:
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--bindir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Executables that the user might invoke are installed here.</para>
- <para>In the simple build system, <replaceable>dir</replaceable>
- may contain the following path variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--libdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Object-code libraries are installed here.</para>
- <para>In the simple build system, <replaceable>dir</replaceable>
- may contain the following path variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$bindir</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--libexecdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Executables that are not expected to be invoked
- directly by the user are installed here.</para>
- <para>In the simple build system, <replaceable>dir</replaceable>
- may contain the following path variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$bindir</replaceable>,
- <replaceable>$libdir</replaceable>,
- <replaceable>$libsubdir</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--datadir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Architecture-independent data files are installed
- here.</para>
- <para>In the simple build system, <replaceable>dir</replaceable>
- may contain the following path variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$bindir</replaceable>,
- <replaceable>$libdir</replaceable>,
- <replaceable>$libsubdir</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>In addition the simple build system supports the following
- installation path options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--libsubdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>A subdirectory of <replaceable>libdir</replaceable>
- in which libraries are actually installed. For example,
- in the simple build system on Unix, the default
- <replaceable>libdir</replaceable> is
- <filename>/usr/local/lib</filename>, and
- <replaceable>libsubdir</replaceable> contains the package
- identifier and compiler,
- e.g. <literal>mypkg-0.2/ghc-6.4</literal>, so libraries
- would be installed in
- <filename>/usr/local/lib/mypkg-0.2/ghc-6.4</filename>.
- </para>
- <para><replaceable>dir</replaceable> may contain the following path
- variables:
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--datasubdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>A subdirectory of <replaceable>datadir</replaceable>
- in which data files are actually installed.
- </para>
- <para><replaceable>dir</replaceable> may contain the following path
- variables:
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--docdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Documentation files are installed relative to this directory.
- </para>
- <para><replaceable>dir</replaceable> may contain the following path
- variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$bindir</replaceable>,
- <replaceable>$libdir</replaceable>,
- <replaceable>$libsubdir</replaceable>,
- <replaceable>$datadir</replaceable>,
- <replaceable>$datasubdir</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--htmldir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>HTML documentation files are installed relative to this directory.
- </para>
- <para><replaceable>dir</replaceable> may contain the following path
- variables:
- <replaceable>$prefix</replaceable>,
- <replaceable>$bindir</replaceable>,
- <replaceable>$libdir</replaceable>,
- <replaceable>$libsubdir</replaceable>,
- <replaceable>$datadir</replaceable>,
- <replaceable>$datasubdir</replaceable>,
- <replaceable>$docdir</replaceable>,
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--program-prefix</option>=<replaceable>prefix</replaceable></term>
- <listitem>
- <para>Prepend <replaceable>prefix</replaceable> to installed program names.
- </para>
- <para><replaceable>prefix</replaceable> may contain the following path
- variables:
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--program-suffix</option>=<replaceable>suffix</replaceable></term>
- <listitem>
- <para>Append <replaceable>suffix</replaceable> to installed program names. The
- most obvious use for this is to append the program's version number to make it
- possible to install several versions of a program at once:
- <literal>--program-suffix='$version'</literal>.
- </para>
- <para><replaceable>suffix</replaceable> may contain the following path
- variables:
- <replaceable>$pkgid</replaceable>,
- <replaceable>$pkg</replaceable>,
- <replaceable>$version</replaceable>,
- <replaceable>$compiler</replaceable>,
- <replaceable>$os</replaceable>,
- <replaceable>$arch</replaceable>
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <sect4 id="simple-path-vars">
- <title>Path variables in the simple build system</title>
-
- <para>For 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
- <literal>$prefix</literal>. This allows paths to be specified
- relative to each other rather than as absolute paths, which is
- important for building relocatable packages (see
- <xref linkend="prefix-independence"/>).</para>
-
- <variablelist>
- <varlistentry>
- <term><replaceable>$prefix</replaceable></term>
- <listitem>
- <para>The path variable that stands for the root of the
- installation.</para>
- <para>For an installation to be relocatable, all other
- instllation paths must be relative to the
- <replaceable>$prefix</replaceable> variable.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$bindir</replaceable></term>
- <listitem>
- <para>The path variable that expands to the path given by
- the <option>--bindir</option> configure option (or the
- default).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$libdir</replaceable></term>
- <listitem>
- <para>As above but for <option>--libdir</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$libsubdir</replaceable></term>
- <listitem>
- <para>As above but for <option>--libsubdir</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$datadir</replaceable></term>
- <listitem>
- <para>As above but for <option>--datadir</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$datasubdir</replaceable></term>
- <listitem>
- <para>As above but for <option>--datasubdir</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$docdir</replaceable></term>
- <listitem>
- <para>As above but for <option>--docdir</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$pkgid</replaceable></term>
- <listitem>
- <para>The name and version of the package, eg
- <literal>mypkg-0.2</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$pkg</replaceable></term>
- <listitem>
- <para>The name of the package, eg
- <literal>mypkg</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$version</replaceable></term>
- <listitem>
- <para>The version of the package, eg
- <literal>0.2</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$compiler</replaceable></term>
- <listitem>
- <para>The compiler being used to build the package, eg
- <literal>ghc-6.6.1</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$os</replaceable></term>
- <listitem>
- <para>The operating system of the computer being used to build
- the package, eg <literal>linux</literal>,
- <literal>windows</literal>, <literal>osx</literal>,
- <literal>freebsd</literal> or <literal>solaris</literal></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>$arch</replaceable></term>
- <listitem>
- <para>The architecture of the computer being used to build the
- package, eg <literal>i386</literal>, <literal>x86_64</literal>,
- <literal>ppc</literal> or <literal>sparc</literal></para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect4>
-
- <sect4 id="simple-paths">
- <title>Paths in the simple build system</title>
-
- <para>For the simple build system, the following defaults
- apply:</para>
-
- <informaltable>
- <tgroup cols="3">
- <colspec align="left"/>
- <colspec align="left"/>
- <colspec align="left"/>
-
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Windows Default</entry>
- <entry>Unix Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>--prefix</literal> (global installs with the
- <literal>--global</literal> flag) </entry>
- <entry><filename>C:\Program Files\Haskell</filename></entry>
- <entry><filename>/usr/local</filename></entry>
- </row>
- <row>
- <entry><literal>--prefix</literal> (per-user installs with
- the <literal>--user</literal> flag)</entry>
- <entry><filename>C:\Documents And Settings\<replaceable>user</replaceable>\Application Data\cabal</filename></entry>
- <entry><filename><replaceable>$HOME</replaceable>/.cabal</filename></entry>
- </row>
-
- <row>
- <entry><literal>--bindir</literal></entry>
- <entry><literal>$prefix\bin</literal></entry>
- <entry><literal>$prefix/bin</literal></entry>
- </row>
-
- <row>
- <entry><literal>--libdir</literal></entry>
- <entry><literal>$prefix</literal></entry>
- <entry><literal>$prefix/lib</literal></entry>
- </row>
-
- <row>
- <entry><literal>--libsubdir</literal> (Hugs)</entry>
- <entry><literal>hugs\packages\$pkg</literal></entry>
- <entry><literal>hugs/packages/$pkg</literal></entry>
- </row>
-
- <row>
- <entry><literal>--libsubdir</literal> (others)</entry>
- <entry><literal>$pkgid\$compiler</literal></entry>
- <entry><literal>$pkgid/$compiler</literal></entry>
- </row>
-
- <row>
- <entry><literal>--libexecdir</literal></entry>
- <entry><literal>$prefix\$pkgid</literal></entry>
- <entry><literal>$prefix/libexec</literal></entry>
- </row>
-
- <row>
- <entry><literal>--datadir</literal> (executable)</entry>
- <entry><literal>$prefix</literal></entry>
- <entry><literal>$prefix/share</literal></entry>
- </row>
-
- <row>
- <entry><literal>--datadir</literal> (library)</entry>
- <entry><filename>C:\Program Files\Haskell</filename></entry>
- <entry><literal>$prefix/share</literal></entry>
- </row>
-
- <row>
- <entry><literal>--datasubdir</literal></entry>
- <entry><literal>$pkgid</literal></entry>
- <entry><literal>$pkgid</literal></entry>
- </row>
-
- <row>
- <entry><literal>--docdir</literal></entry>
- <entry><literal>$prefix\doc\$pkgid</literal></entry>
- <entry><literal>$datadir/doc/$pkgid</literal></entry>
- </row>
-
- <row>
- <entry><literal>--htmldir</literal></entry>
- <entry><literal>$docdir\html</literal></entry>
- <entry><literal>$docdir/html</literal></entry>
- </row>
-
- <row>
- <entry><literal>--program-prefix</literal></entry>
- <entry>(empty)</entry>
- <entry>(empty)</entry>
- </row>
-
- <row>
- <entry><literal>--program-suffix</literal></entry>
- <entry>(empty)</entry>
- <entry>(empty)</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect4>
-
- <sect4 id="prefix-independence">
- <title>Prefix-independence</title>
-
- <para>On 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 <replaceable>bindir</replaceable>. Prefix-independence is
- particularly useful: it means the user can choose the install
- location (i.e. the value of <replaceable>prefix</replaceable>)
- at install-time, rather than having to bake the path into
- the binary when it is built.</para>
-
- <para>In order to achieve this, we require
- that for an executable on Windows, all
- of <replaceable>bindir</replaceable>,
- <replaceable>libdir</replaceable>,
- <replaceable>datadir</replaceable> and
- <replaceable>libexecdir</replaceable> begin with
- <literal>$prefix</literal>. If this is not the case
- then the compiled executable will have baked in
- all absolute paths.</para>
-
- <para>The application need do nothing special to achieve
- prefix-independence. If it finds any files using
- <literal>getDataFileName</literal> and the other functions
- provided for the purpose (see <xref linkend="paths-module"/>),
- the files will be accessed relative to the location of the
- current executable.</para>
-
- <para>A library cannot (currently) be prefix-independent,
- because it will be linked into an executable whose
- file system location bears no relation to the library
- package.</para>
- </sect4>
- </sect3>
-
- <sect3 id="flag-control">
- <title>Controlling Flag Assignments</title>
- <para>Flag assignments (see <xref linkend="conditional-resolution"/>) can be
- controlled with the following command line options.</para>
- <variablelist>
- <varlistentry>
- <term><option>-f</option><replaceable>flagname</replaceable> or
- <option>-f</option><literal>-</literal><replaceable>flagname</replaceable></term>
- <listitem>
- <para>Force the specified flag to
- <literal>true</literal> or <literal>false</literal> (if
- preceded with a <literal>-</literal>). Later
- specifications for the same flags will override earlier,
- i.e., specifying <literal>-fdebug -f-debug</literal> is
- equivalent to <literal>-f-debug</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--flags</option>=<replaceable>flagspecs</replaceable></term>
- <listitem>
- <para>Same as <option>-f</option>, but allows specifying
- multiple flag assignments at once. The parameter is a
- space-separated list of flag names (to force a flag to
- <literal>true</literal>), optionally preceded by a
- <literal>-</literal> (to force a flag to
- <literal>false</literal>). For example,
- <literal>--flags="debug -feature1 feature2"</literal> is
- equivalent to <literal>-fdebug -f-feature1
- -ffeature2</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
-
- <sect3 id="setup-configure-misc">
- <title>Miscellaneous options</title>
-
- <variablelist>
- <varlistentry>
- <term><option>--user</option></term>
- <listitem>
- <para>Does a per-user installation. This changes the default
- installation prefix (see <xref linkend="simple-paths"/>).
- It also allow dependencies to be satisfied by the user's
- package database, in addition to the global database.</para>
-
- <para>This also implies a default of <option>--user</option>
- for any subsequent <literal>install</literal> command,
- as packages registered in the global database should not
- depend on packages registered in a user's database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--global</option></term>
- <listitem>
- <para>(default) Does a global installation. In this case
- package dependencies must be satisfied by the global
- package database. All packages in the user's package database
- will be ignored. Typically the final instllation step will
- require administrative privileges.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--package-db</option>=<replaceable>db</replaceable></term>
- <listitem>
- <para>Allows package dependencies to be satisfied from this
- additional package database <replaceable>db</replaceable> in
- addition to the global package database. All packages in the
- user's package database will be ignored. The interpretation
- of <replaceable>db</replaceable> is implementation-specific.
- Typically it will be a file or directory. Not all
- implementations support arbitrary package databases.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-optimization</option>[=<replaceable>n</replaceable>] or <option>-O</option>[<replaceable>n</replaceable>]</term>
- <listitem>
- <para>(default) Build with optimization flags (if available).
- This is appropriate for production use, taking more time
- to build faster libraries and programs.</para>
- <para>
- The optional <replaceable>n</replaceable> value is the
- optimisation level. Some compilers support multiple
- optimisation levels. The range is 0 to 2. Level 0 is
- equivalent to <option>--disable-optimization</option>,
- level 1 is the default if no <replaceable>n</replaceable>
- parameter is given. Level 2 is higher optimisation if the
- compiler supports it. Level 2 is likely to lead to longer
- compile times and bigger generated code.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-optimization</option></term>
- <listitem>
- <para>Build without optimization. This is suited for
- development: building will be quicker, but the resulting
- library or programs will be slower.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-library-profiling</option> or
- <option>-p</option></term>
- <listitem>
- <para>Request that an additional version of the library
- with profiling features enabled be built and installed
- (only for implementations that support profiling).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-library-profiling</option></term>
- <listitem>
- <para>(default) Do not generate an additional profiling
- version of the library.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-executable-profiling</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-executable-profiling</option></term>
- <listitem>
- <para>(default) Do not enable profiling in generated
- executables.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-library-vanilla</option></term>
- <listitem>
- <para>(default) Build ordinary libraries (as opposed to profiling
- libraries). This is independent of the
- <option>--enable-library-profiling</option> option. If you
- enable both, you get both.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-library-vanilla</option></term>
- <listitem>
- <para>Do not build ordinary libraries. This is useful
- in conjunction with <option>--enable-library-profiling</option>
- to build only profiling libraries, rather than profiling and
- ordinary libraries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-library-for-ghci</option></term>
- <listitem>
- <para>(default) Build libraries suitable for use with GHCi.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-library-for-ghci</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-split-objs</option></term>
- <listitem>
- <para>Use the GHC <option>-split-objs</option> 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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-split-objs</option></term>
- <listitem>
- <para>(default) Do not use the GHC <option>-split-objs</option>
- feature. This makes building the library quicker but the final
- executables that use the library will be larger.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-executable-stripping</option></term>
- <listitem>
- <para>
- (default) When installing binary executable programs, run the
- <literal>strip</literal> program on the binary. This can
- considerably reduce the size of the executable binary file. It
- does this by removing debugging information and symbols. While
- such extra information is useful for debugging C programs with
- traditional debuggers it is rarely helpful for debugging
- binaries produced by Haskell compilers.
- </para>
- <para>
- Not all Haskell implementations generate native binaries. For
- such implementations this option has no effect.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--disable-executable-stripping</option></term>
- <listitem>
- <para>
- Do not strip binary executables during installation. You
- might want to use this option if you need to debug a program
- using gdb, for example if you want to debug the C parts of a
- program containing both Haskell and C code. Another reason is
- if your are building a package for a system which has a policy
- of managing the stripping itself (such as some linux
- distributions).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-shared</option></term>
- <listitem>
- <para>Build shared library. This implies a seperate
- compiler run to generate position independent code as
- required on most platforms.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><option>--disable-shared</option></term>
- <listitem>
- <para>(default) Do not build shared library.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><option>--configure-option</option>=<replaceable>str</replaceable></term>
- <listitem>
- <para>An extra option to an external
- <filename>configure</filename> script,
- if one is used (see <xref linkend="system-dependent"/>).
- There can be several of these options.</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><option>--extra-include-dirs</option>[=<replaceable>dir</replaceable>]</term>
- <listitem>
- <para>
- An extra directory to search for C header files. You can use
- this flag multiple times to get a list of directories.
- </para>
- <para>
- You might need to use this flag if you have standard system
- header files in a non-standard location that is not mentioned
- in the package's <filename>.cabal</filename> file. Using this
- option has the same affect as appending the directory
- <replaceable>dir</replaceable> to the
- <literal>include-dirs</literal> field in each library and
- executable in the package's <filename>.cabal</filename> file.
- The advantage of course is that you do not have to modify the
- package at all. These extra directories will be used while
- building the package and for libraries it is also saved in the
- package registration information and used when compiling
- modules that use the library.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><option>--extra-lib-dirs</option>[=<replaceable>dir</replaceable>]</term>
- <listitem>
- <para>
- An extra directory to search for system libraries files. You
- can use this flag multiple times to get a list of directories.
- </para>
- <para>
- You might need to use this flag if you have standard system
- libraries in a non-standard location that is not mentioned
- in the package's <filename>.cabal</filename> file. Using this
- option has the same affect as appending the directory
- <replaceable>dir</replaceable> to the
- <literal>extra-lib-dirs</literal> field in each library and
- executable in the package's <filename>.cabal</filename> file.
- The advantage of course is that you do not have to modify the
- package at all. These extra directories will be used while
- building the package and for libraries it is also saved in the
- package registration information and used when compiling
- modules that use the library.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>In the simple build infrastructure, an additional option
- is recognized:</para>
- <variablelist>
- <varlistentry>
- <term><option>--scratchdir</option>=<replaceable>dir</replaceable></term>
- <listitem>
- <para>Specify the directory into which the Hugs output will be
- placed (default: <filename>dist/scratch</filename>).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
- </sect2>
-
- <sect2 id="setup-build">
- <title>setup build</title>
- <para>Perform any preprocessing or compilation needed to make this
- package ready for installation.</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--<replaceable>prog</replaceable>-options</option>=<replaceable>options</replaceable></term>
- <term><option>--<replaceable>prog</replaceable>-option</option>=<replaceable>option</replaceable></term>
- <listitem>
- <para>These are mostly the same as the options configure step (see
- <xref linkend="setup-configure-programs"/>). 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.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect2>
-
- <sect2 id="setup-makefile">
- <title>setup makefile</title>
- <para>Generate a <filename>Makefile</filename> 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.</para>
-
- <para>The makefile command replaces part of the work done by
- <literal>setup build</literal>. The sequence of commands would
- typically be:
-<programlisting>
-runhaskell Setup.hs makefile
-make
-runhaskell Setup.hs build
-</programlisting>
- where <literal>setup makefile</literal> does the preprocessing,
- <literal>make</literal> compiles the Haskell modules, and
- <literal>setup build</literal> performs any final steps, such as
- building the library archives.</para>
-
- <para>The Makefile does not use GHC's <literal>--make</literal>
- flag to compile the modules, instead it compiles modules one at
- a time, using dependency information generated by GHC's
- <literal>-M</literal> flag. There are two reasons you might
- therefore want to use <literal>setup makefile</literal>:
-
- <itemizedlist>
- <listitem>
- <para>You want to build in parallel using <literal>make -j</literal>.
- Currently, <literal>setup build</literal> on its own does not support
- building in parallel.</para>
- </listitem>
- <listitem>
- <para>You want to build an individual module, pass extra
- flags to a compilation, or do other non-standard things that
- <literal>setup build</literal> does not support.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--file</option>=<replaceable>filename</replaceable> or
- <option>-f</option> <replaceable>filename</replaceable></term>
- <listitem>
- <para>Specify the output file (default <filename>Makefile</filename>).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect2>
-
- <sect2 id="setup-haddock">
- <title>setup haddock</title>
- <para>Build the documentation for the package using &Haddock;. By
- default, only the documentation for the exposed modules is generated
- (see <xref linkend="setup-haddock-executables"/>).</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--hoogle</option></term>
- <listitem>
- <para>Generate a file
- <filename>dist/doc/html/<replaceable>pkgid</replaceable>.txt</filename>,
- which can be converted by
- <ulink url="http://www.haskell.org/hoogle/">Hoogle</ulink>
- into a database for searching. This is
- equivalent to running &Haddock; with the <option>--hoogle</option> flag.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--html-location</option>=<replaceable>url</replaceable></term>
- <listitem>
- <para>Specify a template for the location of HTML documentation
- for prerequisite packages. The substitutions listed in
- <xref linkend="simple-paths"/> 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:</para>
- <screen>setup haddock --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'</screen>
- <para>Here the argument is quoted to prevent substitution
- by the shell.</para>
- <para>If this option is omitted, the location for each package
- is obtained using the package tool (e.g.
- <command>ghc-pkg</command>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="setup-haddock-executables">
- <term><option>--executables</option></term>
- <listitem>
- <para>Also run &Haddock; for the modules of all the executable
- programs. By default &Haddock; is run only on the exported
- modules.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="setup-haddock-internal">
- <term><option>--internal</option></term>
- <listitem>
- <para>Run &Haddock; for the all modules, including unexposed ones, and
- make &Haddock; generate documentation for unexported symbols
- as well.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="setup-haddock-css">
- <term><option>--css</option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>The argument <replaceable>path</replaceable> 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--hyperlink-source</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--hscolour-css</option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>The argument <replaceable>path</replaceable> denotes a CSS
- file, which is passed to &HsColour; as in</para>
- <screen>
-runhaskell Setup.hs hscolour --css=<replaceable>path</replaceable></screen>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
- <sect2 id="setup-hscolour">
- <title>setup hscolour</title>
- <para>Produce colourised code in HTML format using &HsColour;.
- Colourised code for exported modules is put in
- <filename>dist/doc/html/<replaceable>pkgid</replaceable>/src</filename>.</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--executables</option></term>
- <listitem>
- <para>Also run &HsColour; on the sources of all executable
- programs. Colourised code is put in
- <filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--css</option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>Copy the CSS file from <replaceable>path</replaceable> to
- <filename>dist/doc/html/<replaceable>pkgid</replaceable>/src/hscolour.css</filename>
- for exported modules, or to
- <filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src/hscolour.css</filename>
- for executable programs. The CSS file defines the actual colours
- used to colourise code. Note that the
- <filename>hscolour.css</filename> file is required for the code
- to be actually colourised.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-install">
- <title>setup install</title>
- <para>Copy 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.</para>
-
- <para>The install locations are determined by options to
- <command>setup configure</command>
- (see <xref linkend="setup-configure-paths"/>).</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--global</option></term>
- <listitem>
- <para>Register this package in the system-wide database.
- (This is the default, unless the <option>--user</option>
- option was supplied to the <literal>configure</literal>
- command.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--user</option></term>
- <listitem>
- <para>Register this package in the user's local package database.
- (This is the default if the <option>--user</option>
- option was supplied to the <literal>configure</literal>
- command.)</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-copy">
- <title>setup copy</title>
- <para>Copy the files without registering them. This command
- is mainly of use to those creating binary packages.</para>
-
- <para>This command takes the following option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--destdir</option>=<replaceable>path</replaceable></term>
- <listitem>
- <para>Specify the directory under which to place
- installed files. If this is not given, then the root
- directory is assumed.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-register">
- <title>setup register</title>
- <para>Register 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 <literal>install</literal>
- command incorporates this action. The main use of this
- separate command is in the post-installation step for a binary
- package.</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--global</option></term>
- <listitem>
- <para>Register this package in the system-wide database.
- (This is the default.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--user</option></term>
- <listitem>
- <para>Register this package in the user's local package
- database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--gen-script</option></term>
- <listitem>
- <para>Instead of registering the package, generate a script
- containing commands to perform the registration. On Unix,
- this file is called <filename>register.sh</filename>, on
- Windows, <filename>register.bat</filename>. This script
- might be included in a binary bundle, to be run after the
- bundle is unpacked on the target system.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--gen-pkg-config</option>=[<replaceable>path</replaceable>]</term>
- <listitem>
- <para>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.</para>
- <para>This option is mainly intended for packaging systems. If
- possible use the <option>--gen-script</option> option instead
- since it is more portable across Haskell implementations.</para>
- <para>The <replaceable>path</replaceable> 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
- <literal>.conf</literal> extension.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--inplace</option></term>
- <listitem>
- <para>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.</para>
-
- <para>This flag does not create a build-tree-local package
- database. It still registers the package in one of the
- user or global databases.</para>
-
- <para>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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-unregister">
- <title>setup unregister</title>
- <para>Deregister this package with the compiler.</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--global</option></term>
- <listitem>
- <para>Deregister this package in the system-wide database.
- (This is the default.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--user</option></term>
- <listitem>
- <para>Deregister this package in the user's local package
- database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--gen-script</option></term>
- <listitem>
- <para>Instead of deregistering the package, generate a script
- containing commands to perform the deregistration. On Unix,
- this file is called <filename>unregister.sh</filename>, on
- Windows, <filename>unregister.bat</filename>. This script
- might be included in a binary bundle, to be run on the
- target system.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-clean">
- <title>setup clean</title>
- <para>Remove any local files created during the
- <literal>configure</literal>, <literal>build</literal>,
- <literal>haddock</literal>, <literal>register</literal> or
- <literal>unregister</literal> steps, and also any files and
- directories listed in the <literal>extra-tmp-files</literal>
- field.</para>
-
- <para>This command takes the following options:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--save-configure</option> or <option>-s</option></term>
- <listitem>
- <para>Keeps the configuration information so it is not necessary
- to run the configure step again before building.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="setup-test">
- <title>setup test</title>
-
- <para>Run the test suite specified by the
- <literal>runTests</literal> field of
- <literal>Distribution.Simple.UserHooks</literal>. See &Simple;
- for information about creating hooks and using
- <literal>defaultMainWithHooks</literal>.</para>
-
- </sect2>
-
- <sect2 id="setup-sdist">
- <title>setup sdist</title>
- <para>Create a system- and compiler-independent source distribution
- in a file
- <filename><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</filename>
- in the <filename>dist</filename> subdirectory, for distribution
- to package builders. When unpacked, the commands listed in this
- section will be available.</para>
-
- <para>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
- <literal>license-file</literal>, <literal>main-is</literal>,
- <literal>c-sources</literal>, <literal>data-files</literal> and
- <literal>extra-source-files</literal> fields.</para>
-
- <para>This command takes the following option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--snapshot</option></term>
- <listitem>
- <para>Append today's date
- (in <replaceable>YYYYMMDD</replaceable> form) to the version
- number for the generated source package. The original
- package is unaffected.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-
- <sect1 id="bugs">
- <title>Reporting bugs and deficiencies</title>
-
- <para>Please report any flaws or feature requests in the
- <ulink url="http://hackage.haskell.org/trac/hackage/">bug
- tracker</ulink>.
- </para>
-
- <para>For general discussion or queries email the libraries mailing list
- <email>libraries@haskell.org</email>. There is also a development mailing
- list <email>cabal-devel@haskell.org</email>.
- </para>
- </sect1>
-
- <sect1 id="stability">
- <title>Stability of Cabal interfaces</title>
-
- <para>The Cabal library and related infrastructure is still under active
- development. New features are being added and limitations and bugs are
- being fixed. This requires internal changes and often user visible
- changes as well. We therefor cannot promise complete future-proof
- stability, at least not without halting all development work.</para>
-
- <para>This section documents the aspects of the Cabal interface that we can
- promise to keep stable and which bits are subject to change.</para>
-
- <sect2>
- <title>Cabal file format</title>
- <para>
- This is backwards compatible and mostly forwards compatible.
- New fields can be added without breaking older versions of Cabal.
- Fields can be deprecated without breaking older packages.
- </para>
- </sect2>
-
- <sect2>
- <title>Command-line interface</title>
- <sect3>
- <title>Very Stable Command-line interfaces</title>
-
- <itemizedlist>
- <listitem>
- <para>
- ./setup configure
- <itemizedlist>
- <listitem><para>--prefix</para></listitem>
- <listitem><para>--user</para></listitem>
- <listitem><para>--ghc, --hugs</para></listitem>
- <listitem><para>--verbose</para></listitem>
- <listitem><para>--prefix</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>./setup build</para></listitem>
- <listitem><para>./setup install</para></listitem>
- <listitem><para>./setup register</para></listitem>
- <listitem><para>./setup copy</para></listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Stable Command-line interfaces</title>
- <para></para>
- </sect3>
-
- <sect3>
- <title>Unstable command-line</title>
- <para></para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Functions and Types</title>
- <para>
- The Cabal library follows the <ulink
- url="http://haskell.org/haskellwiki/Package_versioning_policy">Package
- Versioning Policy</ulink>. This means that within a stable major
- release, for example 1.2.x, there will be no incompatible API changes.
- But minor versions increments, for example 1.2.3, indicate compatible
- API additions.
- </para>
-
- <para>
- The Package Versioning Policy does not require any API guarantees
- between major releases, for example between 1.2.x and 1.4.x. In
- practise of course not everything changes between major releases. Some
- parts of the API are more prone to change than others. The rest of this
- section gives some informal advice on what level of API stability you
- can expect between major releases.
- </para>
-
- <sect3>
- <title>Very Stable API</title>
- <itemizedlist>
- <listitem><para><literal>defaultMain</literal></para></listitem>
- <listitem>
- <para>
- <literal>defaultMainWithHooks defaultUserHooks</literal>
- </para>
- <para>
- But regular <literal>defaultMainWithHooks</literal> isn't stable
- since <literal>UserHooks</literal> changes.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Semi-stable API</title>
- <para>
- <itemizedlist>
- <listitem>
- <para><literal>UserHooks</literal> The hooks API will change in the
- future</para>
- </listitem>
- <listitem>
- <para><literal>Distribution.<replaceable>*</replaceable></literal>
- is mostly declarative information about packages and is somewhat
- stable.</para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
-
- <sect3>
- <title>Unstable API</title>
- <para>
- Everything under
- <literal>Distribution.Simple.<replaceable>*</replaceable></literal>
- has no stability guarantee.
- </para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Hackage</title>
- <para>
- The index format is a partly stable interface. It consists of a tar.gz
- file that contains directories with <filename>.cabal</filename> files
- in. In future it may contain more kinds of files so do not assume every
- file is a <filename>.cabal</filename> file. Incompatible revisions to
- the format would involve bumping the name of the index file, i.e.,
- <filename>00-index.tar.gz</filename>,
- <filename>01-index.tar.gz</filename> etc.
- </para>
- </sect2>
-
- </sect1>
-
-</article>
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index c9ae039f6e750495455191b29ad38552ff92d721..0000000000000000000000000000000000000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,32 +0,0 @@
-TOP = ../../..
-
-ifeq "$(findstring boilerplate.mk, $(wildcard $(TOP)/mk/*))" ""
-# ----------------------------------------------------------------------------
-# Standalone Makefile:
-
-.PHONY: all
-
-all: Cabal.pdf
-
-Cabal.pdf: Cabal.xml
- docbook2pdf Cabal.xml
-
-clean:
- rm -fr *~ API users-guide Cabal.pdf Cabal.dvi semantic.cache
-
-else # boilerplate.mk exists
-# ----------------------------------------------------------------------------
-# GHC build tree Makefile:
-
-include $(TOP)/mk/boilerplate.mk
-
-DOC_SUBDIR=libraries/Cabal/doc
-XML_DOC = Cabal
-INSTALL_XML_DOC = $(XML_DOC)
-
-binary-dist:
- @:
-
-include $(TOP)/mk/target.mk
-
-endif
diff --git a/doc/ghc.mk b/doc/ghc.mk
deleted file mode 100644
index a0c5ac6773a1eb702961d3b1266f206988f28d87..0000000000000000000000000000000000000000
--- a/doc/ghc.mk
+++ /dev/null
@@ -1,5 +0,0 @@
-
-libraries/Cabal/doc_DOCBOOK_SOURCES := $(wildcard libraries/Cabal/doc/*.xml)
-
-$(eval $(call docbook,libraries/Cabal/doc,Cabal))
-