From ecf414ed07295229c774d8eaff4130012d77f052 Mon Sep 17 00:00:00 2001 From: Harmen Stoppels Date: Wed, 19 Mar 2025 08:53:14 +0100 Subject: [PATCH] docs: add strong preferences to faq (#49556) --- lib/spack/docs/frequently_asked_questions.rst | 18 ++++++++++++++++-- lib/spack/docs/packages_yaml.rst | 2 ++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/lib/spack/docs/frequently_asked_questions.rst b/lib/spack/docs/frequently_asked_questions.rst index 77bd7d4834d..b8058ed9576 100644 --- a/lib/spack/docs/frequently_asked_questions.rst +++ b/lib/spack/docs/frequently_asked_questions.rst @@ -30,7 +30,7 @@ than always choosing the latest versions or default variants. .. note:: - As a rule of thumb: requirements + constraints > reuse > preferences > defaults. + As a rule of thumb: requirements + constraints > strong preferences > reuse > preferences > defaults. The following set of criteria (from lowest to highest precedence) explain common cases where concretization output may seem surprising at first. @@ -56,7 +56,19 @@ common cases where concretization output may seem surprising at first. concretizer: reuse: dependencies # other options are 'true' and 'false' -3. :ref:`Package requirements ` configured in ``packages.yaml``, +3. :ref:`Strong preferences ` configured in ``packages.yaml`` + are higher priority than reuse, and can be used to strongly prefer a specific version + or variant, without erroring out if it's not possible. Strong preferences are specified + as follows: + + .. code-block:: yaml + + packages: + foo: + prefer: + - "@1.1: ~mpi" + +4. :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: @@ -66,6 +78,8 @@ common cases where concretization output may seem surprising at first. foo: require: - "@1.2: +mpi" + conflicts: + - "@1.4" Requirements and constraints restrict the set of possible solutions, while reuse behavior and preferences influence what an optimal solution looks like. diff --git a/lib/spack/docs/packages_yaml.rst b/lib/spack/docs/packages_yaml.rst index d628f0d68c9..62e59ab13e0 100644 --- a/lib/spack/docs/packages_yaml.rst +++ b/lib/spack/docs/packages_yaml.rst @@ -486,6 +486,8 @@ present. For instance with a configuration like: you will use ``mvapich2~cuda %gcc`` as an ``mpi`` provider. +.. _package-strong-preferences: + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Conflicts and strong preferences ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^