3.1. Configuration
3.1.1. Overview
The global configuration file for cabal-install
is by default
$XDG_CONFIG_HOME/cabal/config
. If you do not have this file, cabal
will create
it for you on the first call to cabal update
(details see configuration file discovery).
Alternatively, you can explicitly ask cabal
to create it for you using
$ cabal user-config update
You can change the location of the global configuration file by specifying
either --config-file=FILE
on the command line or by setting the
CABAL_CONFIG
or CABAL_DIR
environment variable.
Most of the options in this configuration file are also available as command line arguments, and the corresponding documentation can be used to lookup their meaning. The created configuration file only specifies values for a handful of options. Most options are left at their default value, which it documents; for instance,
-- executable-stripping: True
means that the configuration file currently does not specify a value for
the executable-stripping
option (the line is commented out), and
that the default is True
; if you wanted to disable stripping of
executables by default, you would change this line to
executable-stripping: False
You can also use cabal user-config update
to migrate configuration
files created by older versions of cabal
.
3.1.2. Environment variables
Various environment variables affect cabal-install
.
CABAL_CONFIG
The variable to find global configuration file.
CABAL_DIR
If set, all
cabal-install
content files will be stored as subdirectories of this directory, including the configuration file ifCABAL_CONFIG
is unset. IfCABAL_DIR
is unset, Cabal will store data files according to the XDG Base Directory Specification (see directories).Note
For backwards compatibility, if the directory
~/.cabal
on Unix or%APPDATA%\cabal
on Windows exists, and$XDG_CONFIG_HOME/cabal/config
does not exist, andCABAL_DIR
is unset,cabal-install
will behave as ifCABAL_DIR
was set to point at this directory.
CABAL_BUILDDIR
The override for default
dist
build directory. Note, the nix-style builds build directory (dist-newstyle
) is not affected by this environment variable.
3.1.2.1. Configuration file discovery
The configuration file location is determined as follows:
If option
--config-file
is given, use it;otherwise, if
$CABAL_CONFIG
is set use it;otherwise, if
$CABAL_DIR
is set use$CABAL_DIR/config
;otherwise use
config
in$XDG_CONFIG_HOME/cabal
, which defaults to~/.config/cabal
on Unix.
If the configuration file does not exist, and it was not given
explicitly via --config-file
or $CABAL_CONFIG
, then
cabal-install
will generate the default one, with directories
based on $CABAL_DIR
(if set) or according to the XDG Base
Directory Specification, as listed below.
3.1.3. Directories
Unless the CABAL_DIR
environment variable is set or a ~/.cabal
directory exists, Cabal will by default store data in directories
according to the XDG Base Directory Specification. The following
directories are used unless otherwise specified in the configuration
file:
$XDG_CONFIG_HOME/cabal
for the main configuration file. Defaults to~/.config/cabal
on Unix, and%APPDATA%/cabal
on Windows. Overridden by theCABAL_CONFIG
environment variable if set.$XDG_CACHE_HOME/cabal
for downloaded packages and script executables. Defaults to~/.cache/cabal
on Unix, and%LOCALAPPDATA%/cabal
on Windows. You can delete this directory and expect that its contents will be reconstructed as needed.$XDG_STATE_HOME/cabal
for compiled libraries and other stateful artifacts, including the Cabal store. Defaults to~/.local/state/cabal
on Unix and%LOCALAPPDATA%/cabal
on Windows. Deleting this directory might cause installed programs to stop working.~/.local/bin
for executables installed withcabal install
.
You can run cabal path
to see a list of the directories that
cabal
will use with the active configuration.
3.1.4. Repository specification
An important part of the configuration is the specification of the
repository. When cabal
creates a default config file, it configures
the repository to be the central Hackage server:
repository hackage.haskell.org
url: http://hackage.haskell.org/
The name of the repository is given on the first line, and can be
anything; packages downloaded from this repository will be cached under
$XDG_CACHE_HOME/cabal/packages/hackage.haskell.org
(or whatever name you specify;
you can change the prefix by changing the value of
remote-repo-cache
). If you want, you can configure multiple
repositories, and cabal
will combine them and be able to download
packages from any of them.
3.1.4.1. Using secure repositories
When interacting with hackage.haskell.org
, Cabal always runs in secure mode
with standard root keys, so it is not necessary to specify secure
or
root-keys
. If no repositories are listed, Cabal will default to
hackage.haskell.org
.
For non-Hackage repositories that support the TUF security infrastructure you can enable secure access to the repository by specifying:
repository packages.example.org
url: http://packages.example.org/
secure: True
root-keys: <root-key-IDs>
key-threshold: <key-threshold>
The <root-key-IDs>
and <key-threshold>
values are used for
bootstrapping. As part of the TUF infrastructure the repository will
contain a file root.json
(for instance,
http://hackage.haskell.org/root.json) which the client needs to do
verification. However, how can cabal
verify the root.json
file
itself? This is known as bootstrapping: if you specify a list of root
key IDs and a corresponding threshold, cabal
will verify that the
downloaded root.json
file has been signed with at least
<key-threshold>
keys from your set of <root-key-IDs>
.
You can, but are not recommended to, omit these two fields. In that case
cabal
will download the root.json
field and use it without
verification. Although this bootstrapping step is then unsafe, all
subsequent access is secure (provided that the downloaded root.json
was not tampered with). Of course, adding root-keys
and
key-threshold
to your repository specification only shifts the
problem, because now you somehow need to make sure that the key IDs you
received were the right ones. How that is done is however outside the
scope of cabal
proper.
More information about the security infrastructure can be found at https://github.com/haskell/hackage-security.
3.1.4.2. Local no-index repositories
It’s possible to use a directory of .tar.gz package files as a local package repository.
repository my-local-repository
url: file+noindex:///absolute/path/to/directory
cabal
will construct the index automatically from the
package-name-version.tar.gz
files in the directory, and will use optional
corresponding package-name-version.cabal
files as new revisions.
For example, if /absolute/path/to/directory
looks like
/absolute/path/to/directory/
foo-0.1.0.0.tar.gz
bar-0.2.0.0.tar.gz
bar-0.2.0.0.cabal
then cabal
will create an index with two packages:
foo-0.1.0.0
using the source and.cabal
file insidefoo-0.1.0.0.tar.gz
bar-0.2.0.0
using the source insidebar-0.2.0.0.tar.gz
andbar-0.2.0.0.cabal
The index is cached inside the given directory. If the directory is not
writable, you can append #shared-cache
fragment to the URI,
then the cache will be stored inside the remote-repo-cache
directory.
The part of the path will be used to determine the cache key part.
Note
cabal-install
creates a .cache
file, and will aggressively use
its contents if it exists. Therefore if you change the contents of
the directory, remember to wipe the cache too.
Note
The URI scheme file:
is interpreted as a remote repository,
as described in the previous sections, thus requiring manual construction
of 01-index.tar
file.
It is possible to define preferred-versions
, containing additional version constraints
for deprecating or preferring certain package versions, in the given directory.
For example, if /absolute/path/to/directory
looks like
/absolute/path/to/directory/
foo-0.1.0.0.tar.gz
bar-0.2.0.0.tar.gz
preferred-versions
then package deprecations and preferences will be taken into account by the solver.
The contents of preferred-versions
is a list of package version constraints, e.g.
binary < 0.8.0.0 || > 0.8.0.0
text == 1.2.0.0
thus, looks similar to a package-name.cabal
’s build-depends
section.
Note
The preferred-versions
file can be used to restrict the package set from Hackage, by preferring
certain versions or marking a specific version as deprecated. To achieve this, add a
local no-index repository to your configuration file,
where the directory contains your custom
preferred-versions
. After running cabal update
, all cabal
operations will honour the
configuration.
3.1.4.3. Legacy repositories
Currently cabal
supports single kind of “legacy” repositories.
It is specified using
remote-repo: hackage.haskell.org:http://hackage.haskell.org/packages/archive
This is just syntactic sugar for
repository hackage.haskell.org
url: http://hackage.haskell.org/packages/archive
although, in (and only in) the specific case of Hackage, the URL
http://hackage.haskell.org/packages/archive
will be silently
translated to http://hackage.haskell.org/
.
3.1.4.4. Secure local repositories
If you want to use repositories on your local file system, it is recommended instead to use a secure local repository:
repository my-local-repo
url: file:/path/to/local/repo
secure: True
root-keys: <root-key-IDs>
key-threshold: <key-threshold>
The layout of these secure local repos matches the layout of remote repositories exactly; the hackage-repo-tool can be used to create and manage such repositories.