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

Small docs additions

Cabal/doc/developing-packages.rst

@@ -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``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Cabal/doc/installing-packages.rst

@@ -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