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 You can run ``cabal path`` to see a list of the directories that
 124 ``cabal`` will use with the active configuration.
 125
 126 Repository specification
 127 ------------------------
 128
 129 An important part of the configuration is the specification of the
 130 repository. When ``cabal`` creates a default config file, it configures
 131 the repository to be the central Hackage server:
 132
 133 ::
 134
 135     repository hackage.haskell.org
 136       url: http://hackage.haskell.org/
 137
 138 The name of the repository is given on the first line, and can be
 139 anything; packages downloaded from this repository will be cached under
 140 ``$XDG_CACHE_HOME/cabal/packages/hackage.haskell.org`` (or whatever name you specify;
 141 you can change the prefix by changing the value of
 142 :cfg-field:`remote-repo-cache`). If you want, you can configure multiple
 143 repositories, and ``cabal`` will combine them and be able to download
 144 packages from any of them.
 145
 146 Using secure repositories
 147 ^^^^^^^^^^^^^^^^^^^^^^^^^
 148
 149 When interacting with ``hackage.haskell.org``, Cabal always runs in secure mode
 150 with standard root keys, so it is not necessary to specify ``secure`` or
 151 ``root-keys``. If no repositories are listed, Cabal will default to
 152 ``hackage.haskell.org``.
 153
 154 For non-Hackage repositories that support the TUF security infrastructure you
 155 can enable secure access to the repository by specifying:
 156
 157 ::
 158
 159     repository packages.example.org
 160       url: http://packages.example.org/
 161       secure: True
 162       root-keys: <root-key-IDs>
 163       key-threshold: <key-threshold>
 164
 165 The ``<root-key-IDs>`` and ``<key-threshold>`` values are used for
 166 bootstrapping. As part of the TUF infrastructure the repository will
 167 contain a file ``root.json`` (for instance,
 168 http://hackage.haskell.org/root.json) which the client needs to do
 169 verification. However, how can ``cabal`` verify the ``root.json`` file
 170 *itself*? This is known as bootstrapping: if you specify a list of root
 171 key IDs and a corresponding threshold, ``cabal`` will verify that the
 172 downloaded ``root.json`` file has been signed with at least
 173 ``<key-threshold>`` keys from your set of ``<root-key-IDs>``.
 174
 175 You can, but are not recommended to, omit these two fields. In that case
 176 ``cabal`` will download the ``root.json`` field and use it without
 177 verification. Although this bootstrapping step is then unsafe, all
 178 subsequent access is secure (provided that the downloaded ``root.json``
 179 was not tampered with). Of course, adding ``root-keys`` and
 180 ``key-threshold`` to your repository specification only shifts the
 181 problem, because now you somehow need to make sure that the key IDs you
 182 received were the right ones. How that is done is however outside the
 183 scope of ``cabal`` proper.
 184
 185 More information about the security infrastructure can be found at
 186 https://github.com/haskell/hackage-security.
 187
 188 Local no-index repositories
 189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 190
 191 It's possible to use a directory of `.tar.gz` package files as a local package
 192 repository.
 193
 194 ::
 195
 196     repository my-local-repository
 197       url: file+noindex:///absolute/path/to/directory
 198
 199 ``cabal`` will construct the index automatically from the
 200 ``package-name-version.tar.gz`` files in the directory, and will use optional
 201 corresponding ``package-name-version.cabal`` files as new revisions.
 202
 203 For example, if ``/absolute/path/to/directory`` looks like
 204 ::
 205
 206     /absolute/path/to/directory/
 207         foo-0.1.0.0.tar.gz
 208         bar-0.2.0.0.tar.gz
 209         bar-0.2.0.0.cabal
 210
 211 then ``cabal`` will create an index with two packages:
 212
 213 - ``foo-0.1.0.0`` using the source and ``.cabal`` file inside
 214   ``foo-0.1.0.0.tar.gz``
 215 - ``bar-0.2.0.0`` using the source inside ``bar-0.2.0.0.tar.gz``
 216   and ``bar-0.2.0.0.cabal``
 217
 218 The index is cached inside the given directory. If the directory is not
 219 writable, you can append ``#shared-cache`` fragment to the URI,
 220 then the cache will be stored inside the :cfg-field:`remote-repo-cache` directory.
 221 The part of the path will be used to determine the cache key part.
 222
 223 .. note::
 224     ``cabal-install`` creates a ``.cache`` file, and will aggressively use
 225     its contents if it exists. Therefore if you change the contents of
 226     the directory, remember to wipe the cache too.
 227
 228 .. note::
 229     The URI scheme ``file:`` is interpreted as a remote repository,
 230     as described in the previous sections, thus requiring manual construction
 231     of ``01-index.tar`` file.
 232
 233 It is possible to define ``preferred-versions``, containing additional version constraints
 234 for deprecating or preferring certain package versions, in the given directory.
 235
 236 For example, if ``/absolute/path/to/directory`` looks like
 237 ::
 238
 239     /absolute/path/to/directory/
 240         foo-0.1.0.0.tar.gz
 241         bar-0.2.0.0.tar.gz
 242         preferred-versions
 243
 244 then package deprecations and preferences will be taken into account by the solver.
 245
 246 The contents of ``preferred-versions`` is a list of package version constraints, e.g.
 247 ::
 248
 249     binary < 0.8.0.0 || > 0.8.0.0
 250     text == 1.2.0.0
 251
 252 thus, looks similar to a ``package-name.cabal``'s ``build-depends`` section.
 253
 254 .. note::
 255     The ``preferred-versions`` file can be used to restrict the package set from Hackage, by preferring
 256     certain versions or marking a specific version as deprecated. To achieve this, add a
 257     local no-index repository to your :ref:`configuration file <config-file-discovery>`,
 258     where the directory contains your custom
 259     ``preferred-versions``. After running ``cabal update``, all ``cabal`` operations will honour the
 260     configuration.
 261
 262 Legacy repositories
 263 ^^^^^^^^^^^^^^^^^^^
 264
 265 Currently ``cabal`` supports single kind of “legacy” repositories.
 266 It is specified using
 267
 268 ::
 269
 270     remote-repo: hackage.haskell.org:http://hackage.haskell.org/packages/archive
 271
 272 This is just syntactic sugar for
 273
 274 ::
 275
 276     repository hackage.haskell.org
 277       url: http://hackage.haskell.org/packages/archive
 278
 279 although, in (and only in) the specific case of Hackage, the URL
 280 ``http://hackage.haskell.org/packages/archive`` will be silently
 281 translated to ``http://hackage.haskell.org/``.
 282
 283 Secure local repositories
 284 ^^^^^^^^^^^^^^^^^^^^^^^^^
 285
 286 If you want to use repositories on your local file system, it is
 287 recommended instead to use a *secure* local repository:
 288
 289 ::
 290
 291     repository my-local-repo
 292       url: file:/path/to/local/repo
 293       secure: True
 294       root-keys: <root-key-IDs>
 295       key-threshold: <key-threshold>
 296
 297 The layout of these secure local repos matches the layout of remote
 298 repositories exactly; the :hackage-pkg:`hackage-repo-tool`
 299 can be used to create and manage such repositories.
 300
 301 .. _program_options:
 302
 303 Program options
 304 ---------------
 305
 306 Programs that ``cabal`` knows about can be provided with options that will be
 307 passed in whenever the program is invoked by ``cabal``. The configuration file
 308 can contain a stanza of ``program-default-options`` with ``<prog>-options``
 309 fields to specify these.
 310
 311 ::
 312
 313   program-default-options
 314     ghc-options: ...
 315     happy-options: ...
 316
 317 The list of known programs is:
 318
 319 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 320 | Program               | Notes                                                                                                                              |
 321 +=======================+====================================================================================================================================+
 322 | ``alex``              | `<https://haskell-alex.readthedocs.io/en/latest/>`_                                                                                |
 323 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 324 | ``ar``                | Usually provided by GHC's ``"ar command"`` entry in ``ghc --info``. Note this might refer to ``llvm-ar`` instead of GNU's ``ar``.  |
 325 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 326 | ``c2hs``              | `<https://hackage.haskell.org/package/c2hs>`_                                                                                      |
 327 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 328 | ``doctest``           | `<https://hackage.haskell.org/package/doctest>`_                                                                                   |
 329 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 330 | ``gcc``               | Usually provided by GHC's ``"C compiler command"`` entry in ``ghc --info``. Note this might refer to ``clang`` instead of ``gcc``. |
 331 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 332 | ``ghc``               |                                                                                                                                    |
 333 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 334 | ``ghc-pkg``           |                                                                                                                                    |
 335 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 336 | ``ghcjs``             |                                                                                                                                    |
 337 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 338 | ``ghcjs-pkg``         |                                                                                                                                    |
 339 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 340 | ``greencard``         | Greencard hasn't been updated since 2014, it doesn't build with newer GHCs `<https://hackage.haskell.org/package/greencard>`_      |
 341 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 342 | ``haddock``           | `<https://haskell-haddock.readthedocs.io/latest/>`_                                                                                |
 343 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 344 | ``happy``             | `<https://haskell-happy.readthedocs.io/en/latest/>`_                                                                               |
 345 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 346 | ``haskell-suite``     | Haskell suite was abandoned a long time ago.                                                                                       |
 347 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 348 | ``haskell-suite-pkg`` | Haskell suite was abandoned a long time ago.                                                                                       |
 349 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 350 | ``hmake``             | Seems like hmake disappeared a long time ago `<https://www.haskell.org/cabal/proposal-1.1/x756.html>`_                             |
 351 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 352 | ``hpc``               | `<https://hackage.haskell.org/package/hpc>`_                                                                                       |
 353 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 354 | ``hsc2hs``            | `<https://hackage.haskell.org/package/hsc2hs>`_                                                                                    |
 355 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 356 | ``hscolour``          | `<https://hackage.haskell.org/package/hscolour>`_                                                                                  |
 357 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 358 | ``jhc``               | `<http://repetae.net/computer/jhc/>`_                                                                                              |
 359 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 360 | ``ld``                | Usually provided by GHC's ``"ld command"`` entry in ``ghc --info``.                                                                |
 361 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 362 | ``pkg-config``        |                                                                                                                                    |
 363 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 364 | ``runghc``            |                                                                                                                                    |
 365 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 366 | ``strip``             |                                                                                                                                    |
 367 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 368 | ``tar``               |                                                                                                                                    |
 369 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 370 | ``uhc``               | `<https://github.com/UU-ComputerScience/uhc>`_                                                                                     |
 371 +-----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 372
 373 .. warning::
 374
 375   It is important to not confuse these options with the ones listed in the
 376   :ref:`build info<build-info>` section. The ``*-options`` fields mentioned are in
 377   fact syntactic sugar for specific ``ghc-options`` that will be passed only on
 378   certain phases.
 379
 380 .. warning::
 381
 382   These options will be used when ``cabal`` invokes the tool as part of the build process or as part of a
 383   :pkg-field:`build-tool-depends` declaration, not whenever the tool is invoked by
 384   third parties.
 385
 386   In particular this means that for example ``gcc-options`` will be used when ``cabal``
 387   invokes ``gcc``, which is **not** when C sources are compiled by GHC (even though GHC
 388   might invoke ``gcc`` internally). In order to provide options through GHC for those programs, one has to check the
 389   GHC User guide's `Section <https://downloads.haskell.org/ghc/latest/docs/users_guide/phases.html#forcing-options-to-a-particular-phase>`_.
 390   In short, those options have to be given as ``-opt<phase>`` flags to GHC.
 391
 392 .. note::
 393
 394   The only case that violates the rule specified in this last warning above is
 395   ``ld-options``, which get passed as ``-optl`` options when GHC is invoked for
 396   linking, as with the :pkg-field:`ld-options` field in package descriptions.
 397   Notably, although ``gcc-options`` could be passed as :pkg-field:`cc-options`
 398   in the appropriate phases, they are actually **not** passed.