cabal-project.rst

cabal.project Reference
=======================

``cabal.project`` files support a variety of options which configure the
details of your build. The general syntax of a ``cabal.project`` file is
similar to that of a Cabal file: there are a number of fields, some of
which live inside stanzas (groups of fields that apply to only part of a
project or can be referenced as a unit):

::

packages: */*.cabal
with-compiler: /opt/ghc/8.0.1/bin/ghc

package cryptohash
optimization: False

In general, the accepted field names coincide with the accepted command
line flags that ``cabal install`` and other commands take. For example,
``cabal v2-configure --enable-profiling`` will write out a project
file with ``profiling: True``.

The full configuration of a project is determined by combining the
following sources (later entries override earlier ones, except for appendable
options):

1. ``~/.cabal/config`` (the user-wide global configuration)

2. ``cabal.project`` (the project configuration)

3. ``cabal.project.freeze`` (the output of ``cabal v2-freeze``)

4. ``cabal.project.local`` (the output of ``cabal v2-configure``)

Specifying the local packages
-----------------------------

The following top-level options specify what the local packages of a
project are:

.. cfg-field:: packages: package location list (space or comma separated)
:synopsis: Project packages.

:default: ``./*.cabal``

Specifies the list of package locations which contain the local
packages to be built by this project. Package locations can take the
following forms:

1. They can specify a Cabal file, or a directory containing a Cabal
file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``.

2. They can specify glob-style wildcards, which must match one or
more (a) directories containing a (single) Cabal file, (b) Cabal
files (extension ``.cabal``), or (c) tarballs which contain Cabal
packages (extension ``.tar.gz``).
For example, to match all Cabal files in all
subdirectories, as well as the Cabal projects in the parent
directories ``foo`` and ``bar``, use
``packages: */*.cabal ../{foo,bar}/``

3. They can specify an ``http``, ``https`` or ``file``
URL, representing the path to a remote tarball to be downloaded
and built.

There is no command line variant of this field; see :issue:`3585`.
Note that the default value is only included if there is no
``cabal.project`` file. The field is appendable which means there would be
no way to drop the default value if it was included.

.. cfg-field:: optional-packages: package location list (space or comma-separated)
:synopsis: Optional project packages.

:default: empty

Like :cfg-field:`packages`, specifies a list of package locations
containing local packages to be built. Unlike :cfg-field:`packages`,
if we glob for a package, it is permissible for the glob to match against
zero packages. The intended use-case for :cfg-field:`optional-packages`
is to make it so that vendored packages can be automatically picked up if
they are placed in a subdirectory, but not error if there aren't any.

There is no command line variant of this field.

.. cfg-field:: extra-packages: package list with version bounds (comma separated)
:synopsis: Adds external packages as local

[STRIKEOUT:Specifies a list of external packages from Hackage which
should be considered local packages.] (Not implemented)

There is no command line variant of this field.

All local packages are *vendored*, in the sense that if other packages
(including external ones from Hackage) depend on a package with the name
of a local package, the local package is preferentially used.
For subdirectories to be considered local packages, the following setting
can be used::

packages: ./*.cabal
optional-packages: ./*/*.cabal

...then any package can be vendored simply by making a checkout in the
top-level project directory, as might be seen in this hypothetical
directory layout::

foo.cabal
foo-helper/ # local package
unix/ # vendored external package

All of these options support globs. ``cabal v2-build`` has its own glob
format:

- Anywhere in a path, as many times as you like, you can specify an
asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal``
files in all immediate subdirectories. Like in glob(7), asterisks do
not match hidden files unless there is an explicit period, e.g.,
``.*/foo.cabal`` will match ``.private/foo.cabal`` (but
``*/foo.cabal`` will not).

- You can use braces to specify specific directories; e.g.,
``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor``
and ``pkgs`` subdirectories.

Formally, the format is described by the following BNF:

.. todo::
convert globbing grammar to proper ABNF_ syntax

.. code-block:: abnf

FilePathGlob ::= FilePathRoot FilePathGlobRel
FilePathRoot ::= {- empty -} # relative to cabal.project
| "/" # Unix root
| [a-zA-Z] ":" [/\\] # Windows root
| "~" # home directory
FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory
| Glob "\\" FilePathGlobRel # Windows directory
| Glob # file
| {- empty -} # trailing slash
Glob ::= GlobPiece *
GlobPiece ::= "*" # wildcard
| [^*{},/\\] * # literal string
| "\\" [*{},] # escaped reserved character
| "{" Glob "," ... "," Glob "}" # union (match any of these)

Specifying Packages from Remote Version Control Locations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Starting with Cabal 2.4, there is now a stanza
``source-repository-package`` for specifying packages from an external
version control.

.. code-block:: cabal

packages: .

source-repository-package
type: git
location: https://github.com/hvr/HsYAML.git
tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1

source-repository-package
type: git
location: https://github.com/well-typed/cborg
tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
subdir: cborg

source-repository-package
type: git
location: https://github.com/haskell/network.git
tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
post-checkout-command: autoreconf -i

cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages.
This allows sharing of packages across different projects.

.. cfg-field:: type: VCS kind

.. cfg-field:: location: VCS location (usually URL)

.. cfg-field:: type: VCS tag

.. cfg-field:: subdir: subdirectory list

Use one or more subdirectories of the repository.

.. cfg-field:: post-checkout-command: command

Run command in the checked out repository, prior sdisting.

Global configuration options
----------------------------

The following top-level configuration options are not specific to any
package, and thus apply globally:

.. cfg-field:: verbose: nat
--verbose=n, -vn
:synopsis: Build verbosity level.

:default: 1

Control the verbosity of ``cabal`` commands, valid values are from 0
to 3.

The command line variant of this field is ``--verbose=2``; a short
form ``-v2`` is also supported.

.. cfg-field:: jobs: nat or $ncpus
--jobs=n, -jn, --jobs=$ncpus
:synopsis: Number of builds running in parallel.

:default: 1

Run *nat* jobs simultaneously when building. If ``$ncpus`` is
specified, run the number of jobs equal to the number of CPUs.
Package building is often quite parallel, so turning on parallelism
can speed up build times quite a bit!

The command line variant of this field is ``--jobs=2``; a short form
``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent
to ``--jobs=$ncpus``.

.. cfg-field:: keep-going: boolean
--keep-going
:synopsis: Try to continue building on failure.

:default: False

If true, after a build failure, continue to build other unaffected
packages.

The command line variant of this field is ``--keep-going``.

.. option:: --builddir=DIR

Specifies the name of the directory where build products for
build will be stored; defaults to ``dist-newstyle``. If a
relative name is specified, this directory is resolved relative
to the root of the project (i.e., where the ``cabal.project``
file lives.)

This option cannot be specified via a ``cabal.project`` file.

.. _cmdoption-project-file:
.. option:: --project-file=FILE

Specifies the name of the project file used to specify the
rest of the top-level configuration; defaults to ``cabal.project``.
This name not only specifies the name of the main project file,
but also the auxiliary project files ``cabal.project.freeze``
and ``cabal.project.local``; for example, if you specify
``--project-file=my.project``, then the other files that will
be probed are ``my.project.freeze`` and ``my.project.local``.

If the specified project file is a relative path, we will
look for the file relative to the current working directory,
and then for the parent directory, until the project file is
found or we have hit the top of the user's home directory.

This option cannot be specified via a ``cabal.project`` file.

.. option:: --store-dir=DIR

Specifies the name of the directory of the global package store.

Phase control
-------------

The following settings apply to commands that result in build actions
(``build``, ``run``, ``repl``, ``test``...), and control which phases of the
build are executed.

.. option:: --dry-run

Do not download, build, or install anything, only print what would happen.

.. option:: --only-configure

Instead of performing a full build just run the configure step.
Only accepted by the ``build`` command.

.. option:: --only-download

Do not build anything, only fetch the packages.

.. option:: --only-dependencies

Install only the dependencies necessary to build the given packages.
Not accepted by the ``repl`` command.

Solver configuration options
----------------------------

The following settings control the behavior of the dependency solver:

.. cfg-field:: constraints: constraints list (comma separated)
--constraint="pkg >= 2.0"
:synopsis: Extra dependencies constraints.

Add extra constraints to the version bounds, flag settings,
and other properties a solver can pick for a
package. For example:

::

constraints: bar == 2.1

A package can be specified multiple times in ``constraints``, in
which case the specified constraints are intersected. This is
useful, since the syntax does not allow you to specify multiple
constraints at once. For example, to specify both version bounds and
flag assignments, you would write:

::

constraints: bar == 2.1,
bar +foo -baz

Valid constraints take the same form as for the `constraint
command line option
`__.

.. cfg-field:: preferences: preference (comma separated)
--preference="pkg >= 2.0"
:synopsis: Preferred dependency versions.

Like :cfg-field:`constraints`, but the solver will attempt to satisfy
these preferences on a best-effort basis. The resulting install is locally
optimal with respect to preferences; specifically, no single package
could be replaced with a more preferred version that still satisfies
the hard constraints.

Operationally, preferences can cause the solver to attempt certain
version choices of a package before others, which can improve
dependency solver runtime.

One way to use :cfg-field:`preferences` is to take a known working set of
constraints (e.g., via ``cabal v2-freeze``) and record them as
preferences. In this case, the solver will first attempt to use this
configuration, and if this violates hard constraints, it will try to
find the minimal number of upgrades to satisfy the hard constraints
again.

The command line variant of this field is
``--preference="pkg >= 2.0"``; to specify multiple preferences, pass
the flag multiple times.

.. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
--allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
:synopsis: Lift dependencies upper bound constraints.

:default: ``none``

Allow the solver to pick more recent version of some packages than
would normally be permitted by the :pkg-field:`build-depends` bounds
of packages in the install plan. This option may be useful if the
dependency solver cannot otherwise find a valid install plan.

For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on
``dep-pkg``, write a scoped package name of the form:

::

allow-newer: pkg:dep-pkg

If the scope shall be limited to specific releases of ``pkg``, the
extended form as in

::

allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg

can be used to limit the relaxation of dependencies on
``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only.

The scoped syntax is recommended, as it is often only a single package
whose upper bound is misbehaving. In this case, the upper bounds of
other packages should still be respected; indeed, relaxing the bound
can break some packages which test the selected version of packages.

The syntax also allows to prefix the dependee package with a
modifier symbol to modify the scope/semantic of the relaxation
transformation in a additional ways. Currently only one modifier
symbol is defined, i.e. ``^`` (i.e. caret) which causes the
relaxation to be applied only to ``^>=`` operators and leave all other
version operators untouched.

However, in some situations (e.g., when attempting to build packages
on a new version of GHC), it is useful to disregard *all*
upper-bounds, with respect to a package or all packages. This can be
done by specifying just a package name, or using the keyword ``all``
to specify all packages:

::

-- Disregard upper bounds involving the dependencies on
-- packages bar, baz. For quux only, relax
-- 'quux ^>= ...'-style constraints only.
allow-newer: bar, baz, ^quux

-- Disregard all upper bounds when dependency solving
allow-newer: all

-- Disregard all `^>=`-style upper bounds when dependency solving
allow-newer: ^all

For consistency, there is also the explicit wildcard scope syntax
``*`` (or its alphabetic synonym ``all``). Consequently, the
examples above are equivalent to the explicitly scoped variants:

::

allow-newer: all:bar, *:baz, *:^quux

allow-newer: *:*
allow-newer: all:all

allow-newer: *:^*
allow-newer: all:^all

In order to ignore all bounds specified by a package ``pkg-1.2.3``
you can combine scoping with a right-hand-side wildcard like so

::

-- Disregard any upper bounds specified by pkg-1.2.3
allow-newer: pkg-1.2.3:*

-- Disregard only `^>=`-style upper bounds in pkg-1.2.3
allow-newer: pkg-1.2.3:^*

:cfg-field:`allow-newer` is often used in conjunction with a constraint
(in the :cfg-field:`constraints` field) forcing the usage of a specific,
newer version of a package.

The command line variant of this field is e.g. ``--allow-newer=bar``. A
bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.

.. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
--allow-older, --allow-older=[none,all,[scope:][^]pkg]
:synopsis: Lift dependency lower bound constraints.
:since: 2.0

:default: ``none``

Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
upper bounds.

The command line variant of this field is ``--allow-older=all``. A
bare ``--allow-older`` is equivalent to ``--allow-older=all``.

.. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp.
:synopsis: Use source package index state as it existed at a previous time.
:since: 2.0

:default: ``HEAD``

This allows to change the source package index state the solver uses
to compute install-plans. This is particularly useful in
combination with freeze-files in order to also freeze the state the
package index was in at the time the install-plan was frozen.

::

-- UNIX timestamp format example
index-state: @1474739268

-- ISO8601 UTC timestamp format example
-- This format is used by 'cabal v2-configure'
-- for storing `--index-state` values.
index-state: 2016-09-24T17:47:48Z

-- Specify different index-states per package repository
-- Supported since 3.4
index-state:
, hackage.haskell.org 2020-05-06T22:33:27Z
, head.hackage 2020-04-29T04:11:05Z

.. cfg-field:: active-repositories: reponame1, reponame2

:synopsis: Specify active package repositories
:since: 3.4

:default: ``:rest``

Specifies which of the package repositories defined in the configuration
should be active. It's also useful for specifying the order and the way
active repositories are merged.

When searching for a certain version of a certain package name, the list of
active repositories is searched last-to-first.

For example, suppose hackage.haskell.org has versions 1.0 and 2.0 of
package X, and my-repository has version 2.0 of a similarly named package.
Then, with the following configuration:

::

-- Force my-repository to be the first repository considered
active-repositories:
, hackage.haskell.org
, my-repository

version 2.0 of X will come from my-repository, and version 1.0 will come
from hackage.haskell.org.

If we want to make a repository the sole provider of certain packages, we
can put it last in the active repositories list, and add the :override
modifier.

For example, if we modify the previous example like this:

::

active-repositories:
, hackage.haskell.org
, my-repository:override

then version 1.0 of package X won't be found in any case, because X is
present in my-repository only in version 2.0, and the :override forbids
searching for other versions of X further up the list.

:override has no effect for package names that aren't present in the
overriding repository.

The special repository reference :rest stands for "all the other repositories"
and can be useful to avoid lenghty lists of repository names:

::

-- Force my-repository to be the first repository considered
active-repositories: :rest, my-repository

The special repository reference "none" disables all repositories, effectively
putting cabal in "offline" mode:

::

active-repositories: none

.. cfg-field:: reject-unconstrained-dependencies: all, none
--reject-unconstrained-dependencies=[all|none]
:synopsis: Restrict the solver to packages that have constraints on them.

:default: none
:since: 2.6

By default, the dependency solver can include any package that it's
aware of in a build plan. If you wish to restrict the build plan to
a closed set of packages (e.g., from a freeze file), use this flag.

When set to `all`, all non-local packages that aren't goals must be
explicitly constrained. When set to `none`, the solver will
consider all packages.

Package configuration options
-----------------------------

Package options affect the building of specific packages. There are three
ways a package option can be specified:

- They can be specified at the top-level, in which case they apply only
to **local package**, or

- They can be specified inside a ``package`` stanza, in which case they
apply to the build of the package, whether or not it is local or
external.

- They can be specified inside an ``package *`` stanza, in which case they
apply to all packages, local ones from the project and also external
dependencies.

For example, the following options specify that :cfg-field:`optimization`
should be turned off for all local packages, and that ``bytestring`` (possibly
an external dependency) should be built with ``-fno-state-hack``::

optimization: False

package bytestring
ghc-options: -fno-state-hack

``ghc-options`` is not specifically described in this documentation,
but is one of many fields for configuring programs. They take the form
``progname-options`` and ``progname-location``, and
can only be set inside package stanzas. (TODO: They are not supported
at top-level, see :issue:`3579`.)

At the moment, there is no way to specify an option to apply to all
external packages or all inplace packages. Additionally, it is only
possible to specify these options on the command line for all local
packages (there is no per-package command line interface.)

Some flags were added by more recent versions of the Cabal library. This
means that they are NOT supported by packages which use Custom setup
scripts that require a version of the Cabal library older than when the
feature was added.

.. cfg-field:: flags: list of +flagname or -flagname (space separated)
--flags="+foo -bar", -ffoo, -f-bar
:synopsis: Enable or disable package flags.

Force all flags specified as ``+flagname`` to be true, and all flags
specified as ``-flagname`` to be false. For example, to enable the
flag ``foo`` and disable ``bar``, set:

::

flags: +foo -bar

Exactly one of + or - is required before each flag.

Flags are *per-package*, so it doesn't make much sense to specify
flags at the top-level, unless you happen to know that *all* of your
local packages support the same named flags. If a flag is not
supported by a package, it is ignored.

See also the solver configuration field :cfg-field:`constraints`.

The command line variant of this flag is ``--flags``. There is also
a shortened form ``-ffoo -f-bar``.

A common mistake is to say ``cabal v2-build -fhans``, where
``hans`` is a flag for a transitive dependency that is not in the
local package; in this case, the flag will be silently ignored. If
``haskell-tor`` is the package you want this flag to apply to, try
``--constraint="haskell-tor +hans"`` instead.

.. cfg-field:: with-compiler: executable
--with-compiler=executable
:synopsis: Path to compiler executable.

Specify the path to a particular compiler to be used. If not an
absolute path, it will be resolved according to the ``PATH``
environment. The type of the compiler (GHC, GHCJS, etc) must be
consistent with the setting of the :cfg-field:`compiler` field.

The most common use of this option is to specify a different version
of your compiler to be used; e.g., if you have ``ghc-7.8`` in your
path, you can specify ``with-compiler: ghc-7.8`` to use it.

This flag also sets the default value of :cfg-field:`with-hc-pkg`, using
the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name
is suffixed with a version number), or is the executable named
``ghc-pkg`` in the same directory as the ``ghc`` directory. If this
heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly.

For inplace packages, ``cabal v2-build`` maintains a separate build
directory for each version of GHC, so you can maintain multiple
build trees for different versions of GHC without clobbering each
other.

It's not possible to set :cfg-field:`with-compiler` on a
per-package basis.

The command line variant of this flag is
``--with-compiler=ghc-7.8``; there is also a short version
``-w ghc-7.8``.

.. cfg-field:: with-hc-pkg: executable
--with-hc-pkg=executable
:synopsis: Specifies package tool.

Specify the path to the package tool, e.g., ``ghc-pkg``. This
package tool must be compatible with the compiler specified by
:cfg-field:`with-compiler` (generally speaking, it should be precisely
the tool that was distributed with the compiler). If this option is
omitted, the default value is determined from :cfg-field:`with-compiler`.

The command line variant of this flag is
``--with-hc-pkg=ghc-pkg-7.8``.

.. cfg-field:: optimization: nat
--enable-optimization
--disable-optimization
:synopsis: Build with optimization.

:default: ``1``

Build with optimization. This is appropriate for production use,
taking more time to build faster libraries and programs.

The optional *nat* value is the optimisation level. Some compilers
support multiple optimisation levels. The range is 0 to 2. Level 0
disables optimization, level 1 is the default. Level 2 is higher
optimisation if the compiler supports it. Level 2 is likely to lead
to longer compile times and bigger generated code. If you are not
planning to run code, turning off optimization will lead to better
build times and less code to be rebuilt when a module changes.

When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.