From 5cbbed42b4a03c5c12ab71b2347934df1553b470 Mon Sep 17 00:00:00 2001
From: psakiev <psakiev@sandia.gov>
Date: Tue, 12 Nov 2024 18:12:21 -0700
Subject: [PATCH] Add docs

---
 lib/spack/docs/environments.rst    | 35 ++++++++++++++++++++++++++++++
 lib/spack/docs/packaging_guide.rst | 29 ++++++++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst
index 2a9bb5c3f2f..25b92e9c864 100644
--- a/lib/spack/docs/environments.rst
+++ b/lib/spack/docs/environments.rst
@@ -470,6 +470,41 @@ The supplied location will become the build-directory for that package in all fu
     developers to only redirect the build directory if they understand their package's
     build-system.
 
+When doing active development it can often be nice to work inside the build environment
+to run tests, and compile the code natively (i.e. run ``make`` or ``ninja``) without the
+overhead of calling ``spack install``.
+
+The spack command ``build-env`` allows users to run processes inside the build environment
+or to dive directly into it.  An additional convenience alias is ``spack dev-dive [spec]``.
+This will navigate to the package's build directory and then launch a subshell with the
+build environment active.  Users can query if they are currently in a build environment
+subshell by running ``spack build-env --status``.  When users are finished exploring or 
+working in the subshell they can call ``exit`` to leave the build subshell.
+
+.. code-block:: console
+
+   $ spack env activate --temp
+   $ spack add zlib-ng
+   $ spack stage -p $SPACK_ENV zlib-ng
+   $ spack develop zlib-ng
+   $ spack install -u autoreconf zlib-ng
+   # fails
+   $ spack dev-dive zlib-ng
+   # prompt changed, let's check the location is the build directory
+   zlib-ng-build-env $ pwd
+   /private/var/folders/ln/1_3kxbwd35s_ylsjlm3zmqmc00307v/T/spack-ne8_m488/zlib-ng
+   # confirm build-env in case we forget where we are in subshell hierarchy
+   zlib-ng-build-env $ spack build-env --status
+   ==> In build env zlib-ng-wrsaadvkbg7rjj7kfjw5rhdrrfdswcmm
+   # fix code
+   zlib-ng-build-env $ make -j6
+   # builds  now
+   zlib-ng-build-env $ exit
+   # no longer in the build environment
+   $ spack build-env --status
+   ==> build environment not detected
+   $ spack install
+
 ^^^^^^^
 Loading
 ^^^^^^^
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index d9a37175b6c..807eb2a4b38 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -7081,7 +7081,34 @@ provide them after the spec argument to ``spack build-env``:
    $ spack build-env mpileaks@1.1%intel ./configure
 
 This will cd to the build directory and then run ``configure`` in the
-package's build environment.
+package's build environment. This could also be done in one command as follows.
+
+.. code-block:: console
+
+   $ spack build-env --cd build-dir mpileaks@1.1%intel ./configure
+
+Furthermore, ``spack build-env`` has the ability to dive into the build environment
+in a subshell to allow you to work natively without polluting your current shell.
+
+.. code-block:: console
+
+   $ spack build-env --cd build-dir --dive mpileaks@1.1%intel
+   mpileaks-build-env $ ./configure
+
+Note that the command prompt changed for this case. This will happen automatically
+if a Bourne or C-Shell to indicate that the user is in the build environment subshell.
+While automatic prompt changes only occur for a selection of shells, any shell can 
+query if they are in the build environment with the ``spack build-env --status``
+flag.
+
+.. code-block:: console
+
+   $ spack build-env --dive mpileaks@1.1%intel
+   $ spack build-env --status
+   ==> In build env mpileaks-wrsaadvkbg7rjj7kfjw5rhdrrfdswcmm
+   $ exit
+   $ spack build-env --status
+   ==> build environment not detected
 
 .. _cmd-spack-location: