From fa9ef0ac8986d9fba8b919c0bfcf75bfba179e72 Mon Sep 17 00:00:00 2001
From: Harmen Stoppels <me@harmenstoppels.nl>
Date: Wed, 8 Jan 2025 16:02:11 +0100
Subject: [PATCH] config.py: deprecate config:install_path_scheme (#48463)

---
 lib/spack/docs/config_yaml.rst   | 58 +++++++++++++++-----------------
 lib/spack/spack/schema/config.py |  9 ++++-
 2 files changed, 36 insertions(+), 31 deletions(-)

diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst
index 0a4daecd2a1..fd7f86db486 100644
--- a/lib/spack/docs/config_yaml.rst
+++ b/lib/spack/docs/config_yaml.rst
@@ -25,14 +25,23 @@ These settings can be overridden in ``etc/spack/config.yaml`` or
 The location where Spack will install packages and their dependencies.
 Default is ``$spack/opt/spack``.
 
----------------------------------------------------
-``install_hash_length`` and ``install_path_scheme``
----------------------------------------------------
+---------------
+``projections``
+---------------
 
-The default Spack installation path can be very long and can create problems
-for scripts with hardcoded shebangs. Additionally, when using the Intel
-compiler, and if there is also a long list of dependencies, the compiler may
-segfault. If you see the following:
+.. warning::
+
+   Modifying projections of the install tree is strongly discouraged.
+
+By default Spack installs all packages into a unique directory relative to the install
+tree root with the following layout:
+
+.. code-block::
+
+   {architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}
+
+In very rare cases, it may be necessary to reduce the length of this path. For example,
+very old versions of the Intel compiler are known to segfault when input paths are too long:
 
      .. code-block:: console
 
@@ -40,36 +49,25 @@ segfault. If you see the following:
        ** Segmentation violation signal raised. **
        Access violation or stack overflow. Please contact Intel Support for assistance.
 
-it may be because variables containing dependency specs may be too long. There
-are two parameters to help with long path names. Firstly, the
-``install_hash_length`` parameter can set the length of the hash in the
-installation path from 1 to 32. The default path uses the full 32 characters.
+Another case is Python and R packages with many runtime dependencies, which can result
+in very large ``PYTHONPATH`` and ``R_LIBS`` environment variables. This can cause the
+``execve`` system call to fail with ``E2BIG``, preventing processes from starting.
 
-Secondly, it is also possible to modify the entire installation
-scheme. By default Spack uses
-``{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}``
-where the tokens that are available for use in this directive are the
-same as those understood by the :meth:`~spack.spec.Spec.format`
-method. Using this parameter it is possible to use a different package
-layout or reduce the depth of the installation paths. For example
+For this reason, Spack allows users to modify the installation layout through custom
+projections. For example
 
      .. code-block:: yaml
 
        config:
-         install_path_scheme: '{name}/{version}/{hash:7}'
+         install_tree:
+           root: $spack/opt/spack
+           projections:
+             all: "{name}/{version}/{hash:16}"
 
-would install packages into sub-directories using only the package
-name, version and a hash length of 7 characters.
+would install packages into sub-directories using only the package name, version and a
+hash length of 16 characters.
 
-When using either parameter to set the hash length it only affects the
-representation of the hash in the installation directory. You
-should be aware that the smaller the hash length the more likely
-naming conflicts will occur. These parameters are independent of those
-used to configure module names.
-
-.. warning:: Modifying the installation hash length or path scheme after
-   packages have been installed will prevent Spack from being
-   able to find the old installation directories.
+Notice that reducing the hash length increases the likelihood of hash collisions.
 
 --------------------
 ``build_stage``
diff --git a/lib/spack/spack/schema/config.py b/lib/spack/spack/schema/config.py
index b9101147c4d..26c646c23b7 100644
--- a/lib/spack/spack/schema/config.py
+++ b/lib/spack/spack/schema/config.py
@@ -106,10 +106,17 @@
             {
                 "names": ["install_missing_compilers"],
                 "message": "The config:install_missing_compilers option has been deprecated in "
-                "Spack v0.23, and is currently ignored. It will be removed from config after "
+                "Spack v0.23, and is currently ignored. It will be removed from config in "
                 "Spack v1.0.",
                 "error": False,
             },
+            {
+                "names": ["install_path_scheme"],
+                "message": "The config:install_path_scheme option was deprecated in Spack v0.16 "
+                "in favor of config:install_tree:projections:all. It will be removed in Spack "
+                "v1.0.",
+                "error": False,
+            },
         ],
     }
 }