The Cabal file format

This document is a comprehensive reference manual for the Cabal file format.

Common formats

Version range

e ::= e "&&" e
    | e "||" e
    | "(" e ")"
    | "-any"
    | "-none"
    | "==" [0-9]+ ([0-9]+ )+ ".*"

Package description

Required fields for building

There are only four required fields for a Cabal package description to build with Cabal: :pkg-field:`name`, :pkg-field:`version`, :pkg-field:`cabal-version` and :pkg-field:`build-type`.

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

    The unique name of the package, without the version number.  The
    name of the package must coincide with the name of the Cabal file;
    e.g., a package named ``p`` must have a file ``p.cabal``.  A valid
    package name consists of one or more non-empty alphanumeric
    components (with at least one alphabetic character) separated by
    hyphens.  Numeric components are not permitted as they would be
    ambiguous with version numbers.  Package names are case sensitive,
    but it is discouraged to have multiple packages that would
    case-insensitively compare equal, since such packages interact
    poorly with case-insensitive file systems like NTFS.

    Some valid package names are reserved, because they would be
    ambiguous with special targets in the UI of package managers.
    Currently reserved package names are:

    - all
    - any
    - none
    - setup
    - lib
    - exe
    - test

    Additionally, package names starting with ``z-`` are reserved,
    as these are used to backwards-compatibly encode internal libraries
    of packages which are registered to the package database.

    Finally, names which are reserved file system names on Windows
    are prohibited.  These are: COM, PRN, AUX, NUL, COMn (where n is
    from 1 to 9) and LPTn (where n is from 1 to 9).

    Valid package names:

    - ``Cabal``
    - ``cabal-install``
    - ``gtk2``

    Invalid package names:

    - ``gtk-2-hs`` (numeric component is ambiguous)
    - ``foo--bar`` (double hyphen is not permitted)
    - ``-far-`` (leading/trailing hyphen is not permitted)
    - ``my_app`` (underscore is not permitted)

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

    The package version number, a sequence of natural numbers separated
    by dots.  Conventionally, these version numbers follow the package
    versioning policy (TODO: link), where the increments to the first
    two natural numbers indicate major, backwards-compatibility breaking
    changes, an increment to the third number indicates a feature
    release, and an increment to the fourth number indicates a
    patch/bugfix-only release.

    Version numbers are lexicographically ordered by version component;
    if one version number is a prefix of another, it always compares
    less than that number (i.e., 2.0 is less than 2.0.0; however,
    Hackage prohibits uploading multiple versions of a package which
    differ only in trailing zeros.)  Cabal
    doesn't mandate a normal form for version numbers, so a package
    can choose to pad a version number with any number of zeros, but
    standard practice is to pad out a version number to four places.

    One gotcha: for historical reasons, Cabal will parse version
    numbers with a trailing hyphen and then arbitrary string data,
    interpreting these as tags.  However, these tags are ignored
    by Cabal proper, and should not be used in version numbers.

    Valid version numbers:

    - 0.0.1.0
    - 2.0
    - 3

    Invalid version numbers:

    - 2.0-beta (but it will parse!)
    - 3.0~2

.. pkg-field:: cabal-version: >= x.y

    The version of the Cabal specification that this package description
    uses.  This serves two functions:

    1. It specifies what version of Cabal is necessary to support all
       of the features used in this package.  If you use a Cabal feature
       that was introduced in x.y, you must specify
       a :pkg-field:`cabal-version` of at least ``>= x.y``

    2. It specifies a compatibility-level version, locking a package
       to the semantics produced by Cabal in x.y, even if future
       versions of Cabal change the meaning of certain constructs.
       This means increasing :pkg-field:`cabal-version` can change
       the semantics of your package.

    For historical reasons this is always expressed using *>=* version
    range syntax.  Other forms version ranges are invalid.

    For more details about minimum required versions and semantic
    changes, see `cabal-version feature gating/behavior changes`_.

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

    The type of build system used to build a package.  The valid types
    are:

    * ``Simple``, the basic build system which does not allow for
      any programmatic customization.  Most packages can be built with
      just this.

    * ``Custom``, which permits an arbitrary ``Setup.hs`` script to
      implement any rules you want.  Conventionally, most custom
      ``Setup.hs`` scripts are implemented by using the ``Simple``
      build system in conjunction with programmable hooks which
      can be used to customize the build.

    * ``Configure``, a build system for packages which require running
      a ``configure`` script to detect system-dependent headers and
      libraries needed by a package.

    * ``Make``, a build system which defers to a top-level ``Makefile``
      in a directory.  (This build system is rarely used, since it
      generally takes quite a lot of work to write a make-based build system
      for Haskell code)

    In principle, the :pkg-field:`build-type` field is redundant
    with the contents of the ``Setup.hs`` file, which must be
    provided even for non-Custom builds (a non-Custom build simply
    indicates that a ``Setup.hs`` is some standard template.)  The
    motivation behind having a :pkg-field:`build-type` is to make
    it easier for tools to identify that a package is using a particular
    build system and handle it specially.  For example, ``cabal-install``
    will generally not bother invoking a ``Setup.hs`` script if it
    knows that the :pkg-field:`build-type` is ``Simple``; instead,
    it will directly call into its linked copy of the Cabal library
    to perform the build.

    For more information about each of these build systems, as
    well as template ``Setup.hs`` for non-Custom build types,
    see XXX.

Required fields for distribution

If you would like to upload your package to Hackage, there are a few more fields which must be specified (otherwise, Hackage will reject your package.) Failure to include these fields will cause cabal check to fail.

.. pkg-field:: synopsis: freeform

    A short, one-line description of the package.  This description
    would be suitable as a byline of a title or a description in a table
    of packages.  We recommend keeping this less than 80 characters.

    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:: license: identifier

    The type of the license under which this package is distributed.
    (XXX: Is this field normative, i.e., if you say BSD2, are you
    obligated to paste the exact BSD2 text in LICENSE?)
    Valid values for this field are:
    (XXX: Link these)

    * GPL
    * GPL-2
    * GPL-3
    * LGPL
    * LGPL-2
    * LGPL-3
    * AGPL
    * AGPL-3
    * BSD2
    * BSD3
    * MIT
    * ISC
    * MPL-2.0
    * Apache
    * Apache-2.0
    * PublicDomain
    * AllRightsReserved
    * OtherLicense

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

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

    The name of a file(s) containing the precise copyright and 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.

Recommended fields

.. 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:: 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:: author: freeform

    The original author of the package.

Other fields

.. pkg-field:: stability: freeform

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

    Although, in principle, this field can be used to
    designate the stability of a package, in practice, the stability
    of packages is rarely kept up to date (e.g., widely used,
    stable packages are still labeled "experimental.")

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

    A list of compilers and versions against which the package has been
    tested (or at least built).

Build information

Library

Executable

Test suite

Benchmark

Foreign library

Conditional language

GHC-Cabal version decoder

General speaking, Cabal makes a major version release when GHC does. Here is a converter table to help you determine which version of Cabal corresponds to which version of GHC.

GHC 8.2 = Cabal 2.0 (2017)
GHC 8.0 = Cabal 1.24 (2016)
GHC 7.10 = Cabal 1.22 (2015)
GHC 7.8 = Cabal 1.18
GHC 7.6 = Cabal 1.16
GHC 7.4 = Cabal 1.14
GHC 7.2 = Cabal 1.12
GHC 7.0 = Cabal 1.10

cabal-version feature gating/behavior changes

Behavior changes:

>= 1.2

Prior to this version, it was permissible to place information about the library/executable in the top-level of the Cabal file, without making a stanza. In 1.2, use of stanzas became mandatory. If :pkg-field:`cabal-version` is set to a version lower than 1.2, old-style, no-stanza parsing is available.

>= 1.8

Prior to this version, there was only one set of dependencies for the entire package; i.e., even if you declared a dependency in a test suite, it was visible to a library. In 1.8, this behavior changed, so that dependencies were accounted for each component separately (a test suite dependency would not be visible to the library, unless the library specified it as well.) If a package's :pkg-field:`cabal-version` is not set to this version or later, it is not considered eligible for per-component builds in cabal new-build.

>= 2.0

Prior to this version, it was permissible for the module Main to be listed in :pkg-field:`other-modules`, in violation of the fact that this field is only intended for non-Main modules. If :pkg-field:`cabal-version` is set to 2.0 or greater, every module listed in :pkg-field:`other-modules` will be passed to the compiler, along with the main module specified by :pkg-field:`main-is`

Cabal uses :pkg-field:`cabal-version` to gate certain features and/or modify the behavior of certain fields in Cabal files. Starting with 1.18, in this section we describe the exactly what features are gated in this way:

>= 1.18

C/C++/obj-C source file in :pkg-field:`main-is`
:pkg-field:`extra-doc-files`

>= 1.21

:pkg-field:`reexported-modules`

>= 1.23

Internal/convenience libraries (TODO: double check tihs)
:pkg-field:`extra-framework-dirs`
:pkg-field:`build-type` Custom packages must specify custom-setup stanza with :pkg-field:`setup-depends` field.

>= 1.25

:pkg-field:`scope`
:pkg-field:`mixins`
Use of :pkg-field:`autogen-modules` mandated for autogenerated modules like Paths_*.hs