From cc82fe5632fba47c8b3c732f8fb9dbc6d190aedc Mon Sep 17 00:00:00 2001
From: Davide Marchegiani <davide.marchegiani@gmail.com>
Date: Fri, 11 Oct 2024 11:46:52 +1100
Subject: [PATCH] Addressed Harshula and Anton's comments

---
 docs/models/run-a-model/build_a_model.md | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/docs/models/run-a-model/build_a_model.md b/docs/models/run-a-model/build_a_model.md
index 15170227c..d432a8def 100644
--- a/docs/models/run-a-model/build_a_model.md
+++ b/docs/models/run-a-model/build_a_model.md
@@ -39,10 +39,11 @@ cd /g/data/$PROJECT/$USER/spack/0.22
 ## Enable spack
 
 !!! warning
-    This step needs to be carried out for any new login or new shell environment
+    This step needs to be carried out for any new login or new shell environment.
 
 To add the `spack` command to your shell, as well as other settings, run:
 ```
+module purge
 . spack-config/spack-enable.bash
 ```
 
@@ -102,7 +103,7 @@ It is recommended to first compile all the packages in the newly created _Spack_
 Compiling all the packages present in a _Spack_ environment is referred to as [installing the environment](https://spack.readthedocs.io/en/latest/environments.html#installing-an-environment).
 
 ### Concretize the Spack environment
-[Concretizing](https://spack.readthedocs.io/en/latest/environments.html#concretizing) the _Spack_ environment is necessary to force _Spack_ to update its knowledge of all the packages (their specs) within the environment.
+[Concretizing](https://spack.readthedocs.io/en/latest/environments.html#concretizing) the _Spack_ environment is necessary anytime the environment's `spack.yaml` gets changed, to force _Spack_ to update its knowledge of the environment configuration.
 
 To concretize the `mom5_dev` environment, run:
 ```
@@ -369,7 +370,7 @@ The source code is automatically copied inside the [environment's folder](#spack
 
 ## Compile modified Spack environment packages
 
-After the source code has been modified, the new package can be built following the same steps listed in [Compile Spack environment packages](#compile-spack-environment-packages-optional):
+After setting a development package the _Spack_ environment needs to be re-concretized (because the `spack.yaml` file changed). The _Spack_ environment can be concretized following the same steps listed in [Concretize the Spack environment](#concretize-the-spack-environment). Then, the new package can be built following the steps listed in [Compile Spack environment packages](#compile-spack-environment-packages-optional):
 
 ```
 spack concretize -f --fresh
@@ -502,10 +503,14 @@ spack install
 !!! info
     The full output has been truncated for brevity.
 
+!!! tip
+  From now on, the source code can be modified and the _Spack_ environment installed without repeating the concretization step.<br>
+  The _Spack_ environment will need to be re-concretized only if further changes occur in the `spack.yaml` file.
+
 ## Output directory for compiled packages
-For the Spack instance obtained through the [Spack setup instructions]({{spack_setup}}), all compiled packages will be placed in directories having the following format: `<install_tree:root>/<architecture>/<compiler>/<package-name>`.
+For the Spack instance obtained through the [Spack setup instructions]({{spack_setup}}), all compiled packages will be placed in directories having the following format: `<install_tree.root>/{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}`.
 
-`<install_tree:root>` depends on the [`install_tree`](https://spack.readthedocs.io/en/latest/config_yaml.html#install-tree-root) configuration field. _Spack_ reads this configuration field from files in several directories, following [Spack's configuration scopes](https://spack.readthedocs.io/en/latest/configuration.html#configuration-scopes).
+`<install_tree.root>` depends on the [`install_tree.root`](https://spack.readthedocs.io/en/latest/config_yaml.html#install-tree-root) configuration field. _Spack_ reads this configuration field from files in several directories, following [Spack's configuration scopes](https://spack.readthedocs.io/en/latest/configuration.html#configuration-scopes).
 
 !!! warning
     For instances of _Spack_ on _Gadi_ you should ignore the **system** scope.