Extended set of environment modification commands. (#8996)

1 files changed, 24 insertions, 6 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 622860b75f..d61ca699ad 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -684,11 +684,12 @@ Compiler environment variables and additional RPATHs
 
 In the exceptional case a compiler requires setting special environment
 variables, like an explicit library load path. These can bet set in an
-extra section in the compiler configuration.  The user can also specify
-additional ``RPATHs`` that the compiler will add to all executables
-generated by that compiler.  This is useful for forcing certain compilers
-to RPATH their own runtime libraries, so that executables will run
-without the need to set ``LD_LIBRARY_PATH``.
+extra section in the compiler configuration (the supported environment
+modification commands are: ``set``, ``unset``, ``append-path``, and
+``prepend-path``). The user can also specify additional ``RPATHs`` that the
+compiler will add to all executables generated by that compiler.  This is
+useful for forcing certain compilers to RPATH their own runtime libraries, so
+that executables will run without the need to set ``LD_LIBRARY_PATH``.
 
 .. code-block:: yaml
 
@@ -701,12 +702,29 @@ without the need to set ``LD_LIBRARY_PATH``.
           f77: /opt/gcc/bin/gfortran
           fc: /opt/gcc/bin/gfortran
         environment:
+          unset:
+            BAD_VARIABLE: # The colon is required but the value must be empty
           set:
-            LD_LIBRARY_PATH : /opt/gcc/lib
+            GOOD_VARIABLE_NUM: 1
+            GOOD_VARIABLE_STR: good
+          prepend-path:
+            PATH: /path/to/binutils
+          append-path:
+            LD_LIBRARY_PATH: /opt/gcc/lib
         extra_rpaths:
         - /path/to/some/compiler/runtime/directory
         - /path/to/some/other/compiler/runtime/directory
 
+
+.. note::
+
+   The section `environment` is interpreted as an ordered dictionary, which
+   means two things. First, environment modification are applied in the order
+   they are specified in the configuration file. Second, you cannot express
+   environment modifications that require mixing different commands, i.e. you
+   cannot `set` one variable, than `prepend-path` to another one, and than
+   again `set` a third one.
+
 ^^^^^^^^^^^^^^^^^^^^^^^
 Architecture specifiers
 ^^^^^^^^^^^^^^^^^^^^^^^