From 55d2ee9160a74bcf9f271313322e8aa83db153d1 Mon Sep 17 00:00:00 2001 From: Harmen Stoppels Date: Mon, 20 Nov 2023 09:00:53 +0100 Subject: docs: document how spack picks a version / variant (#41070) --- lib/spack/docs/build_settings.rst | 6 ++- lib/spack/docs/frequently_asked_questions.rst | 77 +++++++++++++++++++++++++++ lib/spack/docs/index.rst | 1 + lib/spack/docs/packages_yaml.rst | 10 ++++ 4 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 lib/spack/docs/frequently_asked_questions.rst (limited to 'lib') diff --git a/lib/spack/docs/build_settings.rst b/lib/spack/docs/build_settings.rst index 9fa7eafcbe..0f53355a81 100644 --- a/lib/spack/docs/build_settings.rst +++ b/lib/spack/docs/build_settings.rst @@ -37,7 +37,11 @@ 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. -``reuse: true`` is the default. +``reuse: dependencies`` is the default. + +.. seealso:: + + FAQ: :ref:`Why does Spack pick particular versions and variants? ` ------------------------------------------ Selection of the target microarchitectures diff --git a/lib/spack/docs/frequently_asked_questions.rst b/lib/spack/docs/frequently_asked_questions.rst new file mode 100644 index 0000000000..345fa1a81a --- /dev/null +++ b/lib/spack/docs/frequently_asked_questions.rst @@ -0,0 +1,77 @@ +.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other + Spack Project Developers. See the top-level COPYRIGHT file for details. + + SPDX-License-Identifier: (Apache-2.0 OR MIT) + +========================== +Frequently Asked Questions +========================== + +This page contains answers to frequently asked questions about Spack. +If you have questions that are not answered here, feel free to ask on +`Slack `_ or `GitHub Discussions +`_. If you've learned the +answer to a question that you think should be here, please consider +contributing to this page. + +.. _faq-concretizer-precedence: + +----------------------------------------------------- +Why does Spack pick particular versions and variants? +----------------------------------------------------- + +This question comes up in a variety of forms: + + 1. Why does Spack seem to ignore my package preferences from ``packages.yaml`` config? + 2. Why does Spack toggle a variant instead of using the default from the ``package.py`` file? + +The short answer is that Spack always picks an optimal configuration +based on a complex set of criteria\ [#f1]_. These criteria are more nuanced +than always choosing the latest versions or default variants. + +.. note:: + + As a rule of thumb: requirements + constraints > reuse > preferences > defaults. + +The following set of criteria (from lowest to highest precedence) explain +common cases where concretization output may seem surprising at first. + +1. :ref:`Package preferences ` configured in ``packages.yaml`` + override variant defaults from ``package.py`` files, and influence the optimal + ordering of versions. Preferences are specified as follows: + + .. code-block:: yaml + + packages: + foo: + version: [1.0, 1.1] + variants: ~mpi + +2. :ref:`Reuse concretization ` configured in ``concretizer.yaml`` + overrides preferences, since it's typically faster to reuse an existing spec than to + build a preferred one from sources. When build caches are enabled, specs may be reused + from a remote location too. Reuse concretization is configured as follows: + + .. code-block:: yaml + + concretizer: + reuse: dependencies # other options are 'true' and 'false' + +3. :ref:`Package requirements ` configured in ``packages.yaml``, + and constraints from the command line as well as ``package.py`` files override all + of the above. Requirements are specified as follows: + + .. code-block:: yaml + + packages: + foo: + require: + - "@1.2: +mpi" + +Requirements and constraints restrict the set of possible solutions, while reuse +behavior and preferences influence what an optimal solution looks like. + + +.. rubric:: Footnotes + +.. [#f1] The exact list of criteria can be retrieved with the ``spack solve`` command diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst index 9b032ed313..7607181ada 100644 --- a/lib/spack/docs/index.rst +++ b/lib/spack/docs/index.rst @@ -55,6 +55,7 @@ or refer to the full manual below. getting_started basic_usage replace_conda_homebrew + frequently_asked_questions .. toctree:: :maxdepth: 2 diff --git a/lib/spack/docs/packages_yaml.rst b/lib/spack/docs/packages_yaml.rst index e91d22a8f3..e08f51e612 100644 --- a/lib/spack/docs/packages_yaml.rst +++ b/lib/spack/docs/packages_yaml.rst @@ -256,6 +256,11 @@ on the command line, because it can specify constraints on packages is not possible to specify constraints on dependencies while also keeping those dependencies optional. +.. seealso:: + + FAQ: :ref:`Why does Spack pick particular versions and variants? ` + + ^^^^^^^^^^^^^^^^^^^ Requirements syntax ^^^^^^^^^^^^^^^^^^^ @@ -435,6 +440,11 @@ them if it must, due to other constraints, and also prefers reusing installed packages over building new ones that are a better match for preferences. +.. seealso:: + + FAQ: :ref:`Why does Spack pick particular versions and variants? ` + + Most package preferences (``compilers``, ``target`` and ``providers``) can only be set globally under the ``all`` section of ``packages.yaml``: -- cgit v1.2.3-70-g09d2