doc/config.rst

   1 Configuration
   2 =============
   3
   4 .. highlight:: cabal
   5
   6 Overview
   7 --------
   8
   9 The global configuration file for ``cabal-install`` is by default
  10 ``$XDG_CONFIG_HOME/cabal/config``. If you do not have this file, ``cabal`` will create
  11 it for you on the first call to ``cabal update``
  12 (details see `configuration file discovery`_).
  13 Alternatively, you can explicitly ask ``cabal`` to create it for you using
  14
  15 .. code-block:: console
  16
  17     $ cabal user-config update
  18
  19 You can change the location of the global configuration file by specifying
  20 either ``--config-file=FILE`` on the command line or by setting the
  21 ``CABAL_CONFIG`` or ``CABAL_DIR`` environment variable.
  22
  23 Most of the options in this configuration file are also available as
  24 command line arguments, and the corresponding documentation can be used
  25 to lookup their meaning. The created configuration file only specifies
  26 values for a handful of options. Most options are left at their default
  27 value, which it documents; for instance,
  28
  29 ::
  30
  31     -- executable-stripping: True
  32
  33 means that the configuration file currently does not specify a value for
  34 the ``executable-stripping`` option (the line is commented out), and
  35 that the default is ``True``; if you wanted to disable stripping of
  36 executables by default, you would change this line to
  37
  38 ::
  39
  40     executable-stripping: False
  41
  42 You can also use ``cabal user-config update`` to migrate configuration
  43 files created by older versions of ``cabal``.
  44
  45 Environment variables
  46 ---------------------
  47
  48 Various environment variables affect ``cabal-install``.
  49
  50 ``CABAL_CONFIG``
  51    The variable to find global configuration file.
  52
  53 ``CABAL_DIR``
  54
  55    If set, *all* ``cabal-install`` content files will be stored as
  56    subdirectories of this directory, including the configuration file
  57    if ``CABAL_CONFIG`` is unset.  If ``CABAL_DIR`` is unset, Cabal
  58    will store data files according to the XDG Base Directory
  59    Specification (see `directories`_).
  60
  61    .. note::
  62
  63        For backwards compatibility, if the directory ``~/.cabal`` on
  64        Unix or ``%APPDATA%\cabal`` on Windows exist and ``CABAL_DIR``
  65        is unset, ``cabal-install`` will behave as if ``CABAL_DIR`` was
  66        set to point at this directory.
  67
  68 ``CABAL_BUILDDIR``
  69
  70     The override for default ``dist`` build directory.
  71     Note, the nix-style builds build directory (``dist-newstyle``)
  72     is not affected by this environment variable.
  73
  74 .. _config-file-discovery:
  75
  76 Configuration file discovery
  77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78
  79 The configuration file location is determined as follows:
  80
  81 1. If option ``--config-file`` is given, use it;
  82 2. otherwise, if ``$CABAL_CONFIG`` is set use it;
  83 3. otherwise, if ``$CABAL_DIR`` is set use ``$CABAL_DIR/config``;
  84 4. otherwise use ``config`` in ``$XDG_CONFIG_HOME/cabal``, which
  85    defaults to ``~/.config/cabal`` on Unix.
  86
  87 If the configuration file does not exist, and it was not given
  88 explicitly via ``--config-file`` or ``$CABAL_CONFIG``, then
  89 ``cabal-install`` will generate the default one, with directories
  90 based on ``$CABAL_DIR`` (if set) or according to the XDG Base
  91 Directory Specification, as listed below.
  92
  93 .. _directories:
  94
  95 Directories
  96 -----------
  97
  98 Unless the ``CABAL_DIR`` environment variable is set or a ``~/.cabal``
  99 directory exists, Cabal will by default store data in directories
 100 according to the XDG Base Directory Specification.  The following
 101 directories are used unless otherwise specified in the configuration
 102 file:
 103
 104 * ``$XDG_CONFIG_HOME/cabal`` for the main configuration file.
 105   Defaults to ``~/.config/cabal`` on Unix, and ``%APPDATA%/cabal`` on
 106   Windows.  Overridden by the ``CABAL_CONFIG`` environment variable if
 107   set.
 108
 109 * ``$XDG_CACHE_HOME/cabal`` for downloaded packages and script
 110   executables.  Defaults to ``~/.cache/cabal`` on Unix, and
 111   ``%LOCALAPPDATA%/cabal`` on Windows.  You can delete this directory
 112   and expect that its contents will be reconstructed as needed.
 113
 114 * ``$XDG_STATE_HOME/cabal`` for compiled libraries and other stateful
 115   artifacts, including the Cabal store.  Defaults to
 116   ``~/.local/state/cabal`` on Unix and ``%LOCALAPPDATA%/cabal`` on
 117   Windows.  Deleting this directory might cause installed programs to
 118   stop working.
 119
 120 * ``~/.local/bin`` for executables installed with ``cabal install``.
 121
 122 Repository specification
 123 ------------------------
 124
 125 An important part of the configuration is the specification of the
 126 repository. When ``cabal`` creates a default config file, it configures
 127 the repository to be the central Hackage server:
 128
 129 ::
 130
 131     repository hackage.haskell.org
 132       url: http://hackage.haskell.org/
 133
 134 The name of the repository is given on the first line, and can be
 135 anything; packages downloaded from this repository will be cached under
 136 ``$XDG_CACHE_HOME/cabal/packages/hackage.haskell.org`` (or whatever name you specify;
 137 you can change the prefix by changing the value of
 138 :cfg-field:`remote-repo-cache`). If you want, you can configure multiple
 139 repositories, and ``cabal`` will combine them and be able to download
 140 packages from any of them.
 141
 142 Using secure repositories
 143 ^^^^^^^^^^^^^^^^^^^^^^^^^
 144
 145 When interacting with ``hackage.haskell.org``, Cabal always runs in secure mode
 146 with standard root keys, so it is not necessary to specify ``secure`` or
 147 ``root-keys``. If no repositories are listed, Cabal will default to
 148 ``hackage.haskell.org``.
 149
 150 For non-Hackage repositories that support the TUF security infrastructure you
 151 can enable secure access to the repository by specifying:
 152
 153 ::
 154
 155     repository packages.example.org
 156       url: http://packages.example.org/
 157       secure: True
 158       root-keys: <root-key-IDs>
 159       key-threshold: <key-threshold>
 160
 161 The ``<root-key-IDs>`` and ``<key-threshold>`` values are used for
 162 bootstrapping. As part of the TUF infrastructure the repository will
 163 contain a file ``root.json`` (for instance,
 164 http://hackage.haskell.org/root.json) which the client needs to do
 165 verification. However, how can ``cabal`` verify the ``root.json`` file
 166 *itself*? This is known as bootstrapping: if you specify a list of root
 167 key IDs and a corresponding threshold, ``cabal`` will verify that the
 168 downloaded ``root.json`` file has been signed with at least
 169 ``<key-threshold>`` keys from your set of ``<root-key-IDs>``.
 170
 171 You can, but are not recommended to, omit these two fields. In that case
 172 ``cabal`` will download the ``root.json`` field and use it without
 173 verification. Although this bootstrapping step is then unsafe, all
 174 subsequent access is secure (provided that the downloaded ``root.json``
 175 was not tampered with). Of course, adding ``root-keys`` and
 176 ``key-threshold`` to your repository specification only shifts the
 177 problem, because now you somehow need to make sure that the key IDs you
 178 received were the right ones. How that is done is however outside the
 179 scope of ``cabal`` proper.
 180
 181 More information about the security infrastructure can be found at
 182 https://github.com/haskell/hackage-security.
 183
 184 Local no-index repositories
 185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 186
 187 It's possible to use a directory of `.tar.gz` package files as a local package
 188 repository.
 189
 190 ::
 191
 192     repository my-local-repository
 193       url: file+noindex:///absolute/path/to/directory
 194
 195 ``cabal`` will construct the index automatically from the
 196 ``package-name-version.tar.gz`` files in the directory, and will use optional
 197 corresponding ``package-name-version.cabal`` files as new revisions.
 198
 199 For example, if ``/absolute/path/to/directory`` looks like
 200 ::
 201
 202     /absolute/path/to/directory/
 203         foo-0.1.0.0.tar.gz
 204         bar-0.2.0.0.tar.gz
 205         bar-0.2.0.0.cabal
 206
 207 then ``cabal`` will create an index with two packages:
 208
 209 - ``foo-0.1.0.0`` using the source and ``.cabal`` file inside
 210   ``foo-0.1.0.0.tar.gz``
 211 - ``bar-0.2.0.0`` using the source inside ``bar-0.2.0.0.tar.gz``
 212   and ``bar-0.2.0.0.cabal``
 213
 214 The index is cached inside the given directory. If the directory is not
 215 writable, you can append ``#shared-cache`` fragment to the URI,
 216 then the cache will be stored inside the :cfg-field:`remote-repo-cache` directory.
 217 The part of the path will be used to determine the cache key part.
 218
 219 .. note::
 220     ``cabal-install`` creates a ``.cache`` file, and will aggressively use
 221     its contents if it exists. Therefore if you change the contents of
 222     the directory, remember to wipe the cache too.
 223
 224 .. note::
 225     The URI scheme ``file:`` is interpreted as a remote repository,
 226     as described in the previous sections, thus requiring manual construction
 227     of ``01-index.tar`` file.
 228
 229 It is possible to define ``preferred-versions``, containing additional version constraints
 230 for deprecating or preferring certain package versions, in the given directory.
 231
 232 For example, if ``/absolute/path/to/directory`` looks like
 233 ::
 234
 235     /absolute/path/to/directory/
 236         foo-0.1.0.0.tar.gz
 237         bar-0.2.0.0.tar.gz
 238         preferred-versions
 239
 240 then package deprecations and preferences will be taken into account by the solver.
 241
 242 The contents of ``preferred-versions`` is a list of package version constraints, e.g.
 243 ::
 244
 245     binary < 0.8.0.0 || > 0.8.0.0
 246     text == 1.2.0.0
 247
 248 thus, looks similar to a ``package-name.cabal``'s ``build-depends`` section.
 249
 250 .. note::
 251     The ``preferred-versions`` file can be used to restrict the package set from Hackage, by preferring
 252     certain versions or marking a specific version as deprecated. To achieve this, add a
 253     local no-index repository to your :ref:`configuration file <config-file-discovery>`,
 254     where the directory contains your custom
 255     ``preferred-versions``. After running ``cabal update``, all ``cabal`` operations will honour the
 256     configuration.
 257
 258 Legacy repositories
 259 ^^^^^^^^^^^^^^^^^^^
 260
 261 Currently ``cabal`` supports single kind of “legacy” repositories.
 262 It is specified using
 263
 264 ::
 265
 266     remote-repo: hackage.haskell.org:http://hackage.haskell.org/packages/archive
 267
 268 This is just syntactic sugar for
 269
 270 ::
 271
 272     repository hackage.haskell.org
 273       url: http://hackage.haskell.org/packages/archive
 274
 275 although, in (and only in) the specific case of Hackage, the URL
 276 ``http://hackage.haskell.org/packages/archive`` will be silently
 277 translated to ``http://hackage.haskell.org/``.
 278
 279 Secure local repositories
 280 ^^^^^^^^^^^^^^^^^^^^^^^^^
 281
 282 If you want to use repositories on your local file system, it is
 283 recommended instead to use a *secure* local repository:
 284
 285 ::
 286
 287     repository my-local-repo
 288       url: file:/path/to/local/repo
 289       secure: True
 290       root-keys: <root-key-IDs>
 291       key-threshold: <key-threshold>
 292
 293 The layout of these secure local repos matches the layout of remote
 294 repositories exactly; the :hackage-pkg:`hackage-repo-tool`
 295 can be used to create and manage such repositories.