PythonPackage: add --config-settings support (#31823)

1 files changed, 49 insertions, 1 deletions

diff --git a/lib/spack/docs/build_systems/pythonpackage.rst b/lib/spack/docs/build_systems/pythonpackage.rst
index a21648b063..0a35c46419 100644
--- a/lib/spack/docs/build_systems/pythonpackage.rst
+++ b/lib/spack/docs/build_systems/pythonpackage.rst
@@ -215,7 +215,7 @@ Note that ``py-wheel`` is already listed as a build dependency in the
 need to specify a specific version requirement or change the
 dependency type.
 
-See `PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ and
+See `PEP 517 <https://www.python.org/dev/peps/pep-0517/>`__ and
 `PEP 518 <https://www.python.org/dev/peps/pep-0518/>`_ for more
 information on the design of ``pyproject.toml``.
 
@@ -412,6 +412,34 @@ packages. However, the installation instructions for a package may
 suggest passing certain flags to the ``setup.py`` call. The
 ``PythonPackage`` class has two techniques for doing this.
 
+"""""""""""""""
+Config settings
+"""""""""""""""
+
+These settings are passed to
+`PEP 517 <https://peps.python.org/pep-0517/>`__ build backends.
+For example, ``py-scipy`` package allows you to specify the name of
+the BLAS/LAPACK library you want pkg-config to search for:
+
+.. code-block:: python
+
+   depends_on('py-pip@22.1:', type='build')
+
+   def config_settings(self, spec, prefix):
+       return {
+           'blas': spec['blas'].libs.names[0],
+           'lapack': spec['lapack'].libs.names[0],
+       }
+
+
+.. note::
+
+   This flag only works for packages that define a ``build-backend``
+   in ``pyproject.toml``. Also, it is only supported by pip 22.1+,
+   which requires Python 3.7+. For packages that still support Python
+   3.6 and older, ``install_options`` should be used instead.
+
+
 """"""""""""""
 Global options
 """"""""""""""
@@ -431,6 +459,16 @@ has an optional dependency on ``libyaml`` that can be enabled like so:
        return options
 
 
+.. note::
+
+   Direct invocation of ``setup.py`` is
+   `deprecated <https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html>`_.
+   This flag forces pip to use a deprecated installation procedure.
+   It should only be used in packages that don't define a
+   ``build-backend`` in ``pyproject.toml`` or packages that still
+   support Python 3.6 and older.
+
+
 """""""""""""""
 Install options
 """""""""""""""
@@ -451,6 +489,16 @@ allows you to specify the directories to search for ``libyaml``:
        return options
 
 
+.. note::
+
+   Direct invocation of ``setup.py`` is
+   `deprecated <https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html>`_.
+   This flag forces pip to use a deprecated installation procedure.
+   It should only be used in packages that don't define a
+   ``build-backend`` in ``pyproject.toml`` or packages that still
+   support Python 3.6 and older.
+
+
 ^^^^^^^
 Testing
 ^^^^^^^