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