docs: add section on concretizer configuration

* Document `concretizer.yaml`, `--reuse`, and `--fresh`.

5 files changed, 59 insertions, 13 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 5fc1757c03..e7375c43da 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -194,9 +194,9 @@ Reusing installed dependencies
 
 .. warning::
 
-   The ``--reuse`` option described here is experimental, and it will
-   likely be replaced with a different option and configuration settings
-   in the next Spack release.
+   The ``--reuse`` option described here will become the default installation
+   method in the next Spack version, and you will be able to get the current
+   behavior by using ``spack install --fresh``.
 
 By default, when you run ``spack install``, Spack tries to build a new
 version of the package you asked for, along with updated versions of
@@ -216,6 +216,9 @@ the ``mpich`` will be build with the installed versions, if possible.
 You can use the :ref:`spack spec -I <cmd-spack-spec>` command to see what
 will be reused and what will be built before you install.
 
+You can configure Spack to use the ``--reuse`` behavior by default in
+``concretizer.yaml``.
+
 .. _cmd-spack-uninstall:
 
 ^^^^^^^^^^^^^^^^^^^
@@ -1280,7 +1283,7 @@ Normally users don't have to bother specifying the architecture if they
 are installing software for their current host, as in that case the
 values will be detected automatically.  If you need fine-grained control
 over which packages use which targets (or over *all* packages' default
-target), see :ref:`concretization-preferences`.
+target), see :ref:`package-preferences`.
 
 .. admonition:: Cray machines
 
diff --git a/lib/spack/docs/build_settings.rst b/lib/spack/docs/build_settings.rst
index a3353a4314..8de28f8a07 100644
--- a/lib/spack/docs/build_settings.rst
+++ b/lib/spack/docs/build_settings.rst
@@ -209,11 +209,49 @@ Specific limitations include:
   then Spack will not add a new external entry (``spack config blame packages``
   can help locate all external entries).
 
-.. _concretization-preferences:
+.. _concretizer-options:
 
---------------------------
-Concretization Preferences
---------------------------
+----------------------
+Concretizer options
+----------------------
+
+``packages.yaml`` gives the concretizer preferences for specific packages,
+but you can also use ``concretizer.yaml`` to customize aspects of the
+algorithm it uses to select the dependencies you install:
+
+.. _code-block: yaml
+
+   concretizer:
+     # Whether to consider installed packages or packages from buildcaches when
+     # concretizing specs. If `true`, we'll try to use as many installs/binaries
+     # as possible, rather than building. If `false`, we'll always give you a fresh
+     # concretization.
+     reuse: false
+
+^^^^^^^^^^^^^^^^
+``reuse``
+^^^^^^^^^^^^^^^^
+
+This controls whether Spack will prefer to use installed packages (``true``), or
+whether it will do a "fresh" installation and prefer the latest settings from
+``package.py`` files and ``packages.yaml`` (``false``). .
+
+You can use ``spack install --reuse`` to enable reuse for a single installation,
+and you can use ``spack install --fresh`` to do a fresh install if ``reuse`` is
+enabled by default.
+
+.. note::
+
+   ``reuse: false`` is the current default, but ``reuse: true`` will be the default
+   in the next Spack release. You will still be able to use ``spack install --fresh``
+   to get the old behavior.
+
+
+.. _package-preferences:
+
+-------------------
+Package Preferences
+-------------------
 
 Spack can be configured to prefer certain compilers, package
 versions, dependencies, and variants during concretization.
@@ -269,6 +307,7 @@ concretization rules.  A provider lists a value that packages may
 ``depend_on`` (e.g, MPI) and a list of rules for fulfilling that
 dependency.
 
+
 .. _package_permissions:
 
 -------------------
diff --git a/lib/spack/docs/build_systems/intelpackage.rst b/lib/spack/docs/build_systems/intelpackage.rst
index a4197694b9..5da16157d7 100644
--- a/lib/spack/docs/build_systems/intelpackage.rst
+++ b/lib/spack/docs/build_systems/intelpackage.rst
@@ -649,7 +649,7 @@ follow `the next section <intel-install-libs_>`_ instead.
 
    * If you specified a custom variant (for example ``+vtune``) you may want to add this as your
      preferred variant in the packages configuration for the ``intel-parallel-studio`` package
-     as described in :ref:`concretization-preferences`. Otherwise you will have to specify
+     as described in :ref:`package-preferences`. Otherwise you will have to specify
      the variant everytime ``intel-parallel-studio`` is being used as ``mkl``, ``fftw`` or ``mpi``
      implementation to avoid pulling in a different variant.
 
@@ -811,13 +811,13 @@ by one of the following means:
      $ spack install libxc@3.0.0%intel
 
 
-* Alternatively, request Intel compilers implicitly by concretization preferences.
+* Alternatively, request Intel compilers implicitly by package preferences.
   Configure the order of compilers in the appropriate ``packages.yaml`` file,
   under either an ``all:`` or client-package-specific entry, in a
   ``compiler:`` list. Consult the Spack documentation for
   `Configuring Package Preferences <https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html#configuring-package-preferences>`_
   and
-  :ref:`Concretization Preferences <concretization-preferences>`.
+  :ref:`Package Preferences <package-preferences>`.
 
 Example: ``etc/spack/packages.yaml`` might simply contain:
 
@@ -867,7 +867,7 @@ virtual package, in order of decreasing preference.  To learn more about the
 ``providers:`` settings, see the Spack tutorial for
 `Configuring Package Preferences <https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html#configuring-package-preferences>`_
 and the section
-:ref:`Concretization Preferences <concretization-preferences>`.
+:ref:`Package Preferences <package-preferences>`.
 
 Example: The following fairly minimal example for ``packages.yaml`` shows how
 to exclusively use the standalone ``intel-mkl`` package for all the linear
diff --git a/lib/spack/docs/configuration.rst b/lib/spack/docs/configuration.rst
index 8f62e8a40f..a7b0a6c74b 100644
--- a/lib/spack/docs/configuration.rst
+++ b/lib/spack/docs/configuration.rst
@@ -13,12 +13,16 @@ Spack has many configuration files.  Here is a quick list of them, in
 case you want to skip directly to specific docs:
 
 * :ref:`compilers.yaml <compiler-config>`
+* :ref:`concretizer.yaml <concretizer-options>`
 * :ref:`config.yaml <config-yaml>`
 * :ref:`mirrors.yaml <mirrors>`
 * :ref:`modules.yaml <modules>`
 * :ref:`packages.yaml <build-settings>`
 * :ref:`repos.yaml <repositories>`
 
+You can also add any of these as inline configuration in ``spack.yaml``
+in an :ref:`environment <environment-configuration>`.
+
 -----------
 YAML Format
 -----------
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index efb0232e19..293e83a118 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -2859,7 +2859,7 @@ be concretized on their system.  For example, one user may prefer packages
 built with OpenMPI and the Intel compiler.  Another user may prefer
 packages be built with MVAPICH and GCC.
 
-See the :ref:`concretization-preferences` section for more details.
+See the :ref:`package-preferences` section for more details.
 
 
 .. _group_when_spec: