Document new environment variable expansion in projections (#42963)

Adding docs and test for #42917

Co-authored-by: Alec Scott <hi@alecbcs.com>

2 files changed, 30 insertions, 0 deletions

diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst
index 963903ec64..4104af619f 100644
--- a/lib/spack/docs/environments.rst
+++ b/lib/spack/docs/environments.rst
@@ -952,6 +952,17 @@ function, as shown in the example below:
      ^mpi: "{name}-{version}/{^mpi.name}-{^mpi.version}-{compiler.name}-{compiler.version}"
      all: "{name}-{version}/{compiler.name}-{compiler.version}"
 
+Projections also permit environment and spack configuration variable
+expansions as shown below:
+
+.. code-block:: yaml
+
+   projections:
+     all: "{name}-{version}/{compiler.name}-{compiler.version}/$date/$SYSTEM_ENV_VARIBLE"
+
+where ``$date`` is the spack configuration variable that will expand with the ``YYYY-MM-DD``
+format and ``$SYSTEM_ENV_VARIABLE`` is an environment variable defined in the shell.
+
 The entries in the projections configuration file must all be either
 specs or the keyword ``all``. For each spec, the projection used will
 be the first non-``all`` entry that the spec satisfies, or ``all`` if
diff --git a/lib/spack/spack/test/projections.py b/lib/spack/spack/test/projections.py
new file mode 100644
index 0000000000..c01b48440a
--- /dev/null
+++ b/lib/spack/spack/test/projections.py
@@ -0,0 +1,19 @@
+# Copyright 2013-2024 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)
+
+from datetime import date
+
+import spack.projections
+import spack.spec
+
+
+def test_projection_expansion(mock_packages, monkeypatch):
+    """Test that env variables and spack config variables are expanded in projections"""
+
+    monkeypatch.setenv("FOO_ENV_VAR", "test-string")
+    projections = {"all": "{name}-{version}/$FOO_ENV_VAR/$date"}
+    spec = spack.spec.Spec("fake@1.0")
+    projection = spack.projections.get_projection(projections, spec)
+    assert "{name}-{version}/test-string/%s" % date.today().strftime("%Y-%m-%d") == projection