debug: initial global debug flag support (#24285)

The developer can export environment variables that
are seen by the compiler wrapper to then add the flags

1 files changed, 32 insertions, 0 deletions

diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst
index 0ceb5d84a1..fe67b90950 100644
--- a/lib/spack/docs/developer_guide.rst
+++ b/lib/spack/docs/developer_guide.rst
@@ -785,6 +785,38 @@ Unit tests
 Unit testing
 ------------
 
+---------------------
+Developer environment
+---------------------
+
+.. warning::
+
+    This is an experimental feature. It is expected to change and you should
+    not use it in a production environment.
+
+
+When installing a package, we currently have support to export environment
+variables to specify adding debug flags to the build. By default, a package
+install will build without any debug flag. However, if you want to add them,
+you can export:
+
+.. code-block:: console
+
+   export SPACK_ADD_DEBUG_FLAGS=true
+   spack install zlib
+
+
+If you want to add custom flags, you should export an additional variable:
+
+.. code-block:: console
+
+   export SPACK_ADD_DEBUG_FLAGS=true
+   export SPACK_DEBUG_FLAGS="-g"
+   spack install zlib
+
+These environment variables will eventually be integrated into spack so
+they are set from the command line.
+
 ------------------
 Developer commands
 ------------------