cabal-package.rst

Package Description
===================

The Cabal package is the unit of distribution. When installed, its
purpose is to make available:

- One or more Haskell programs.

- At most one library, exposing a number of Haskell modules.

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. Fortunately, starting with Cabal 1.8.0.4, executables can
also declare the package that they are in as a dependency, and Cabal
will treat them as if they were in another package that depended on the
library.

Internally, the package may consist of much more than a bunch of Haskell
modules: it may also have C source code and header files, source code
meant for preprocessing, documentation, test cases, auxiliary tools etc.

A package is identified by a globally-unique *package name*, which
consists of one or more alphanumeric words separated by hyphens. To
avoid ambiguity, each of these words should contain at least one letter.
Chaos will result if two distinct packages with the same name are
installed on the same system. A particular version of the package is
distinguished by a *version number*, consisting of a sequence of one or
more integers separated by dots. These can be combined to form a single
text string called the *package ID*, using a hyphen to separate the name
from the version, e.g. "``HUnit-1.1``".

.. Note::

Packages are not part of the Haskell language; they simply
populate the hierarchical space of module names. In GHC 6.6 and later a
program may contain multiple modules with the same name if they come
from separate packages; in all other current Haskell systems packages
may not overlap in the modules they provide, including hidden modules.

Creating a package
------------------

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:

:file:`{package-name}.cabal`
a Unicode UTF-8 text file containing a package description. For
details of the syntax of this file, see the section on
`package descriptions`_.

:file:`Setup.hs`
a single-module Haskell program to perform various setup tasks (with
the interface described in the section on :ref:`installing-packages`).
This module should import only modules that will be present in all Haskell
implementations, including modules of the Cabal library. The content of
this file is determined by the :pkg-field:`build-type` setting in the
``.cabal`` file. In most cases it will be trivial, calling on the Cabal
library to do most of the work.

Once you have these, you can create a source bundle of this directory
for distribution. Building of the package is discussed in the section on
:ref:`installing-packages`.

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 ``.cabal`` 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.

::

name: Foo
version: 1.0

library
build-depends: base >= 4 && < 5
exposed-modules: Foo
extensions: ForeignFunctionInterface
ghc-options: -Wall
if os(windows)
build-depends: Win32 >= 2.1 && < 2.6

Example: A package containing a simple library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The HUnit package contains a file ``HUnit.cabal`` containing:

::

name: HUnit
version: 1.1.1
synopsis: A unit testing framework for Haskell
homepage: http://hunit.sourceforge.net/
category: Testing
author: Dean Herington
license: BSD3
license-file: LICENSE
cabal-version: 1.12
build-type: Simple

library
build-depends: base >= 2 && < 4
exposed-modules: Test.HUnit.Base, Test.HUnit.Lang,
Test.HUnit.Terminal, Test.HUnit.Text, Test.HUnit
default-extensions: CPP

and the following ``Setup.hs``:

.. code-block:: haskell

import Distribution.Simple
main = defaultMain

Example: A package containing executable programs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

name: TestPackage
version: 0.0
synopsis: Small package with two programs
author: Angela Author
license: BSD3
build-type: Simple
cabal-version: >= 1.8

executable program1
build-depends: HUnit >= 1.1.1 && < 1.2
main-is: main.hs
hs-source-dirs: prog1

executable program2
-- A different main.hs because of hs-source-dirs.
main-is: main.hs
build-depends: HUnit >= 1.1.1 && < 1.2
hs-source-dirs: prog2
other-modules: Utils

with ``Setup.hs`` the same as above.

Example: A package containing a library and executable programs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

name: TestPackage
version: 0.0
synopsis: Package with library and two programs
license: BSD3
author: Angela Author
build-type: Simple
cabal-version: >= 1.8

library
build-depends: HUnit >= 1.1.1 && < 1.2
hs-source-dirs: lib
exposed-modules: A, B, C

executable program1
main-is: main.hs
hs-source-dirs: prog1
other-modules: D, E

executable program2
-- A different main.hs because of hs-source-dirs.
main-is: main.hs
-- No bound on internal libraries.
build-depends: TestPackage
hs-source-dirs: prog2
other-modules: Utils

with ``Setup.hs`` the same as above. Note that any library modules
required (directly or indirectly) by an executable must be listed again.

The trivial setup script used in these examples uses the *simple build
infrastructure* provided by the Cabal library (see
`Distribution.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.

The simple build infrastructure can also handle packages where building
is governed by system-dependent parameters, if you specify a little more
(see the section on `system-dependent parameters`_).
A few packages require `more elaborate solutions `_.

.. _pkg-desc:

Package descriptions
--------------------

The package description file must have a name ending in "``.cabal``". 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; specifically, Hackage rejects packages which
don't follow this rule.

In the package description file, lines whose first non-whitespace
characters are "``--``" are treated as comments and ignored.

This file should contain a number global property descriptions and
several sections.

- The `package properties`_ describe the package
as a whole, such as name, license, author, etc.

- Optionally, a number of *configuration flags* can be declared. These
can be used to enable or disable certain features of a package. (see
the section on `configurations`_).

- The (optional) library section specifies the `library`_ properties and
relevant `build information`_.

- Following is an arbitrary number of executable sections which describe
an executable program and relevant `build information`_.

Each section consists of a number of property descriptions in the form
of field/value pairs, with a syntax roughly like mail message headers.

- Case is not significant in field names, but is significant in field
values.

- To continue a field value, indent the next line relative to the field
name.

- Field names may be indented, but all field values in the same section
must use the same indentation.

- Tabs are *not* allowed as indentation characters due to a missing
standard interpretation of tab width.

- Before Cabal 3.0, to get a blank line in a field value, use an indented "``.``"

The syntax of the value depends on the field. Field types include:

*token*, *filename*, *directory*
Either a sequence of one or more non-space non-comma characters, or
a quoted string in Haskell 98 lexical syntax. The latter can be used
for escaping whitespace, for example:
``ghc-options: -Wall "-with-rtsopts=-T -I1"``. Unless otherwise
stated, relative filenames and directories are interpreted from the
package root directory.
*freeform*, *URL*, *address*
An arbitrary, uninterpreted string.
*identifier*
A letter followed by zero or more alphanumerics or underscores.
*compiler*
A compiler flavor (one of: ``GHC``, ``UHC`` or ``LHC``)
followed by a version range. For example, ``GHC ==6.10.3``, or
``LHC >=0.6 && <0.8``.

Modules and preprocessors
^^^^^^^^^^^^^^^^^^^^^^^^^

Haskell module names listed in the :pkg-field:`library:exposed-modules` and
:pkg-field:`library:other-modules` fields may correspond to Haskell source
files, i.e. with names ending in "``.hs``" or "``.lhs``", or to inputs for
various Haskell preprocessors. The simple build infrastructure understands the
extensions:

- ``.gc`` (:hackage-pkg:`greencard`)
- ``.chs`` (:hackage-pkg:`c2hs`)
- ``.hsc`` (:hackage-pkg:`hsc2hs`)
- ``.y`` and ``.ly`` (happy_)
- ``.x`` (alex_)
- ``.cpphs`` (cpphs_)

When building, Cabal will automatically run the appropriate preprocessor
and compile the Haskell module it produces. For the ``c2hs`` and
``hsc2hs`` preprocessors, Cabal will also automatically add, compile and
link any C sources generated by the preprocessor (produced by
``hsc2hs``'s ``#def`` feature or ``c2hs``'s auto-generated wrapper
functions). Dependencies on pre-processors are specified via the
:pkg-field:`build-tools` or :pkg-field:`build-tool-depends` fields.

Some fields take lists of values, which are optionally separated by
commas, except for the :pkg-field:`build-depends` field, where the commas are
mandatory.

Some fields are marked as required. All others are optional, and unless
otherwise specified have empty default values.

Package properties
^^^^^^^^^^^^^^^^^^

These fields may occur in the first top-level properties section and
describe the package as a whole:

.. pkg-field:: name: package-name (required)

The unique name of the package, without the version number.

As pointed out in the section on `package descriptions`_, some
tools require the package-name specified for this field to match
the package description's file-name :file:`{package-name}.cabal`.

Package names are case-sensitive and must match the regular expression
(i.e. alphanumeric "words" separated by dashes; each alphanumeric
word must contain at least one letter):
``[[:digit:]]*[[:alpha:]][[:alnum:]]*(-[[:digit:]]*[[:alpha:]][[:alnum:]]*)*``.

Or, expressed in ABNF_:

.. code-block:: abnf

package-name = package-name-part *("-" package-name-part)
package-name-part = *DIGIT UALPHA *UALNUM

UALNUM = UALPHA / DIGIT
UALPHA = ... ; set of alphabetic Unicode code-points

.. note::

Hackage restricts package names to the ASCII subset.

.. pkg-field:: version: numbers (required)

The package version number, usually consisting of a sequence of
natural numbers separated by dots, i.e. as the regular
expression ``[0-9]+([.][0-9]+)*`` or expressed in ABNF_:

.. code-block:: abnf

package-version = 1*DIGIT *("." 1*DIGIT)

.. pkg-field:: cabal-version: x.y[.z]

The version of the Cabal specification that this package
description uses. The Cabal specification does slowly evolve (see
also :ref:`spec-history`), introducing new features and
occasionally changing the meaning of existing features.
Specifying which version of the specification you are using
enables programs which process the package description to know
what syntax to expect and what each part means.

The version number you specify will affect both compatibility and
behaviour. Most tools (including the Cabal library and the ``cabal``
program) understand a range of versions of the Cabal specification.
Older tools will of course only work with older versions of the
Cabal specification that was known at the time. Most of the time,
tools that are too old will recognise this fact and produce a
suitable error message. Likewise, ``cabal check`` will tell you
whether the version number is sufficiently high for the features
you use in the package description.

As for behaviour, new versions of the Cabal specification can change the
meaning of existing syntax. This means if you want to take advantage
of the new meaning or behaviour then you must specify the newer
Cabal version. Tools are expected to use the meaning and behaviour
appropriate to the version given in the package description.

In particular, the syntax of package descriptions changed
significantly with Cabal version 1.2 and the :pkg-field:`cabal-version`
field is now required. Files written in the old syntax are still
recognized, so if you require compatibility with very old Cabal
versions then you may write your package description file using the
old syntax. Please consult the user's guide of an older Cabal
version for a description of that syntax.

Starting with ``cabal-version: 2.2`` this field is only valid if
fully contained in the very first line of a package description
and ought to adhere to the ABNF_ grammar

.. code-block:: abnf

newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-spec-version *WS

newstyle-spec-version = NUM "." NUM [ "." NUM ]

NUM = DIGIT0 / DIGITP 1*DIGIT0
DIGIT0 = %x30-39
DIGITP = %x31-39
WS = %20

.. note::

For package descriptions using a format prior to
``cabal-version: 1.12`` the legacy syntax resembling a version
range syntax

.. code-block:: cabal

cabal-version: >= 1.10

needs to be used.

This legacy syntax is supported up until ``cabal-version: >=
2.0`` it is however strongly recommended to avoid using the
legacy syntax. See also :issue:`4899`.

.. pkg-field:: build-type: identifier

:default: ``Custom`` or ``Simple``

The type of build used by this package. Build types are the
constructors of the
`BuildType `__
type. This field is optional and when missing, its default value
is inferred according to the following rules:

- When :pkg-field:`cabal-version` is set to ``2.2`` or higher,
the default is ``Simple`` unless a :pkg-section:`custom-setup`
exists, in which case the inferred default is ``Custom``.

- For lower :pkg-field:`cabal-version` values, the default is
``Custom`` unconditionally.

If the build type is anything other than ``Custom``, then the
``Setup.hs`` file *must* be exactly the standardized content
discussed below. This is because in these cases, ``cabal`` will
ignore the ``Setup.hs`` file completely, whereas other methods of
package management, such as ``runhaskell Setup.hs [CMD]``, still
rely on the ``Setup.hs`` file.

For build type ``Simple``, the contents of ``Setup.hs`` must be:

.. code-block:: haskell

import Distribution.Simple
main = defaultMain

For build type ``Configure`` (see the section on `system-dependent
parameters`_ below), the contents of
``Setup.hs`` must be:

.. code-block:: haskell

import Distribution.Simple
main = defaultMainWithHooks autoconfUserHooks

For build type ``Make`` (see the section on `more complex packages`_ below),
the contents of ``Setup.hs`` must be:

.. code-block:: haskell

import Distribution.Make
main = defaultMain

For build type ``Custom``, the file ``Setup.hs`` can be customized,
and will be used both by ``cabal`` and other tools.

For most packages, the build type ``Simple`` is sufficient.

.. pkg-field:: license: SPDX expression

:default: ``NONE``

The type of license under which this package is distributed.

Starting with ``cabal-version: 2.2`` the ``license`` field takes a
(case-sensitive) SPDX expression such as

.. code-block:: cabal

license: Apache-2.0 AND (MIT OR GPL-2.0-or-later)

See `SPDX IDs: How to use `__ for more
examples of SPDX expressions.

The version of the
`list of SPDX license identifiers `__
is a function of the :pkg-field:`cabal-version` value as defined
in the following table:

+--------------------------+--------------------+
| Cabal specification | SPDX license list |
| version | version |
| | |
+==========================+====================+
| ``cabal-version: 2.2`` | ``3.0 2017-12-28`` |
+--------------------------+--------------------+
| ``cabal-version: 2.4`` | ``3.2 2018-07-10`` |
+--------------------------+--------------------+

**Pre-SPDX Legacy Identifiers**

The license identifier in the table below are defined for
``cabal-version: 2.0`` and previous versions of the Cabal
specification.

+--------------------------+-----------------+
| :pkg-field:`license` | Note |
| identifier | |
| | |
+==========================+=================+
| ``GPL`` | |
| ``GPL-2`` | |
| ``GPL-3`` | |
+--------------------------+-----------------+
| ``LGPL`` | |
| ``LGPL-2.1`` | |
| ``LGPL-3`` | |
+--------------------------+-----------------+
| ``AGPL`` | since 1.18 |
| ``AGPL-3`` | |
+--------------------------+-----------------+
| ``BSD2`` | since 1.20 |
+--------------------------+-----------------+
| ``BSD3`` | |
+--------------------------+-----------------+
| ``MIT`` | |
+--------------------------+-----------------+
| ``ISC`` | since 1.22 |
+--------------------------+-----------------+
| ``MPL-2.0`` | since 1.20 |
+--------------------------+-----------------+
| ``Apache`` | |
| ``Apache-2.0`` | |
+--------------------------+-----------------+
| ``PublicDomain`` | |
+--------------------------+-----------------+
| ``AllRightsReserved`` | |
+--------------------------+-----------------+
| ``OtherLicense`` | |
+--------------------------+-----------------+

.. pkg-field:: license-file: filename

See :pkg-field:`license-files`.

.. pkg-field:: license-files: filename list
:since: 1.20

The name of a file(s) containing the precise copyright license for
this package. The license file(s) will be installed with the
package.

If you have multiple license files then use the :pkg-field:`license-files`
field instead of (or in addition to) the :pkg-field:`license-file` field.

.. pkg-field:: copyright: freeform

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. For example::

copyright: (c) 2006-2007 Joe Bloggs

.. pkg-field:: author: freeform

The original author of the package.

Remember that ``.cabal`` files are Unicode, using the UTF-8
encoding.

.. pkg-field:: maintainer: address

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.

.. pkg-field:: stability: freeform

The stability level of the package, e.g. ``alpha``,
``experimental``, ``provisional``, ``stable``.

.. pkg-field:: homepage: URL

The package homepage.

.. pkg-field:: bug-reports: URL

The URL where users should direct bug reports. This would normally
be either:

- A ``mailto:`` URL, e.g. for a person or a mailing list.

- An ``http:`` (or ``https:``) URL for an online bug tracking
system.

For example Cabal itself uses a web-based bug tracking system

::

bug-reports: https://github.com/haskell/cabal/issues

.. pkg-field:: package-url: URL

The location of a source bundle for the package. The distribution
should be a Cabal package.

.. pkg-field:: synopsis: freeform

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.

.. pkg-field:: description: freeform

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.

For library packages, this field is used as prologue text by
:ref:`setup-haddock` and thus may contain the same markup as Haddock_
documentation comments.

.. pkg-field:: category: freeform

A classification category for future use by the package catalogue
Hackage_. These categories have not
yet been specified, but the upper levels of the module hierarchy
make a good start.

.. pkg-field:: tested-with: compiler list

A list of compilers and versions against which the package has been
tested (or at least built). The value of this field is not used by Cabal
and is rather intended as extra metadata for use by third party
tooling, such as e.g. CI tooling.

Here's a typical usage example:

::

tested-with: GHC == 9.0.1, GHC == 8.10.4, GHC == 8.8.4,
GHC == 8.6.5, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2,
GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2

The same can be spread over several lines, for instance:

::

tested-with: GHC == 9.0.1
, GHC == 8.10.4
, GHC == 8.8.4
, GHC == 8.6.5
, GHC == 8.4.4
, GHC == 8.2.2
, GHC == 8.0.2
, GHC == 7.10.3
, GHC == 7.8.4
, GHC == 7.6.3
, GHC == 7.4.2

The separating comma can also be dropped altogether:

::

tested-with:
GHC == 9.0.1
GHC == 8.10.4
GHC == 8.8.4
GHC == 8.6.5
GHC == 8.4.4
GHC == 8.2.2
GHC == 8.0.2
GHC == 7.10.3
GHC == 7.8.4
GHC == 7.6.3
GHC == 7.4.2

However, this alternative might
`disappear `__
in the future.

Starting with :pkg-field:`cabal-version` 3.0,
there are further conveniences.

1. A preceding ``,`` is allowed, so a bullet-list style
is possible (recommended):

::

tested-with:
, GHC == 9.0.1
, GHC == 8.10.4
, GHC == 8.8.4
, GHC == 8.6.5
, GHC == 8.4.4
, GHC == 8.2.2
, GHC == 8.0.2
, GHC == 7.10.3
, GHC == 7.8.4
, GHC == 7.6.3
, GHC == 7.4.2

2. A concise set notation syntax is available:

::

tested-with: GHC == { 9.0.1, 8.10.4, 8.8.4, 8.6.5, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 }

.. pkg-field:: data-files: filename list

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. Cabal provides a way to
`find these files at run-time <#accessing-data-files-from-package-code>`_.

A limited form of ``*`` wildcards in file names, for example
``data-files: images/*.png`` matches all the ``.png`` files in the
``images`` directory. ``data-files: audio/**/*.mp3`` matches all
the ``.mp3`` files in the ``audio`` directory, including
subdirectories.

The specific limitations of this wildcard syntax are

- ``*`` wildcards are only allowed in place of the file name, not
in the directory name or file extension. It must replace the
whole file name (e.g., ``*.html`` is allowed, but
``chapter-*.html`` is not). If a wildcard is used, it must be
used with an extension, so ``data-files: data/*`` is not
allowed.

- Prior to Cabal 2.4, when matching a wildcard plus extension, a
file's full extension must match exactly, so ``*.gz`` matches
``foo.gz`` but not ``foo.tar.gz``. This restriction has been
lifted when ``cabal-version: 2.4`` or greater so that ``*.gz``
does match ``foo.tar.gz``

- ``*`` wildcards will not match if the file name is empty (e.g.,
``*.html`` will not match ``foo/.html``).

- ``**`` wildcards can only appear as the final path component
before the file name (e.g., ``data/**/images/*.jpg`` is not
allowed). If a ``**`` wildcard is used, then the file name must
include a ``*`` wildcard (e.g., ``data/**/README.rst`` is not
allowed).

- A wildcard that does not match any files is an error.

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.

On efficiency: if you use ``**`` patterns, the directory tree will
be walked starting with the parent directory of the ``**``. If
that's the root of the project, this might include ``.git/``,
``dist-newstyle/``, or other large directories! To avoid this
behaviour, put the files that wildcards will match against in
their own folder.

``**`` wildcards are available starting in Cabal 2.4.

.. pkg-field:: data-dir: directory

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.

.. pkg-field:: extra-source-files: filename list

A list of additional files to be included in source distributions
built with :ref:`setup-sdist`. As with :pkg-field:`data-files` it can use
a limited form of ``*`` wildcards in file names.

.. pkg-field:: extra-doc-files: filename list
:since: 1.18

A list of additional files to be included in source distributions,
and also copied to the html directory when Haddock documentation is
generated. As with :pkg-field:`data-files` it can use a limited form of
``*`` wildcards in file names.

.. pkg-field:: extra-tmp-files: filename list

A list of additional files or directories to be removed by
:ref:`setup-clean`. These would typically be additional files created by
additional hooks, such as the scheme described in the section on
`system-dependent parameters`_.

Library
^^^^^^^

.. pkg-section:: library name
:synopsis: Library build information.

Build information for libraries.