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