Unverified Commit 0d3e4efc authored by Oleg Grenrus's avatar Oleg Grenrus Committed by GitHub

Merge pull request #6546 from phadej/small-docs-additions

Small docs additions
parents b419865c e758c306
......@@ -2187,6 +2187,7 @@ system-dependent values for these fields.
.. pkg-field:: hs-source-dir: directory list
:deprecated: 2.0
:removed: 3.0
:default: ``.``
Root directories for the module hierarchy.
......@@ -3281,6 +3282,18 @@ Declaring a ``custom-setup`` stanza also enables the generation of
:pkg-field:`build-depends` field for a description of the syntax expected by
this field.
If the field is not specified the implicit package set will be used.
The package set contains packages bundled with GHC (i.e. ``base``,
``bytestring``) and specifically ``Cabal``.
The specific bounds are put on ``Cabal`` dependency:
lower-bound is inferred from :pkg-field:`cabal-version`,
and the upper-bound is ``< 1.25``.
``Cabal`` version is additionally restricted by GHC,
with absolute minimum being ``1.20``, and for example ``Custom``
builds with GHC-8.10 require at least ``Cabal-3.2``.
Backward compatibility and ``custom-setup``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -41,6 +41,53 @@ executables by default, you would change this line to
You can also use ``cabal user-config update`` to migrate configuration
files created by older versions of ``cabal``.
Environment variables
---------------------
Various environment variables affect ``cabal-install``.
``CABAL_CONFIG``
The variable to find global configuration file.
``CABAL_DIR``
Default content directory for ``cabal-install`` files.
Default value is ``getAppUserDataDirectory "cabal"``, which is
``$HOME/.cabal`` on unix systems.
.. note::
The CABAL_DIR might be dropped in the future, when
``cabal-install`` starts to use XDG Directory specification.
``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.
``CABAL_SANDBOX_PACKAGE_PATH``
Variable related to deprecated sandbox functionality.
``CABAL_SANDBOX_CONFIG``
Variable related to deprecated sandbox functionality.
Configuration file discovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. If ``$CABAL_CONFIG`` is set use it,
2. otherwise if ``$CABAL_DIR`` is set use ``$CABAL_DIR/config``
3. otherwise use ``getAppUserDirectory "cabal"``
If the configuration file doesn't exist ``cabal-install``
will generate the default one, with directories based on
``$CABAL_DIR`` (if set) or ``getAppUserDirectory "cabal"`` prefix.
.. note:
If ``$CABAL_CONFIG`` is set, but the file doesn't exist,
one will be generated with ``$CABAL_DIR`` or ``getAppUserDirectory "cabal"``
based prefixes. In other words not the prefixes based on a
directory part of ``$CABAL_CONFIG`` path.
Repository specification
------------------------
......@@ -119,6 +166,11 @@ writable, you can append ``#shared-cache`` fragment to the URI,
then the cache will be stored inside the :cfg-field:`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
it 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
......@@ -260,6 +312,11 @@ Hackage_ web site.
Developing with sandboxes
-------------------------
.. warning::
This functionality is deprecated.
Please migrate to use nix-style builds.
By default, any dependencies of the package are installed into the
global or user package databases (e.g. using
``cabal install --only-dependencies``). If you're building several
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment