From 869c10e1a2eaff0e5c7d20ef3ba86a66b6b9936c Mon Sep 17 00:00:00 2001
From: Harshula Jayasuriya <harshula.jayasuriya@anu.edu.au>
Date: Tue, 1 Oct 2024 15:03:23 +1000
Subject: [PATCH] getting_started/spack.md: show how to update the Spack
 instance

* Create directories to support multiple versions of Spack.
* Clone Spack with full context.
---
 docs/getting_started/spack.md | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/getting_started/spack.md b/docs/getting_started/spack.md
index fa9253141..1e4c1ef53 100644
--- a/docs/getting_started/spack.md
+++ b/docs/getting_started/spack.md
@@ -1,5 +1,8 @@
 # Set up Spack for building ACCESS models
 
+!!! info
+    Last updated: 30/09/2024
+
 !!! danger
     This page is tailored to experienced users and collaborators developing ACCESS models.
 
@@ -15,19 +18,25 @@ These instructions are tailored specifically for _Gadi_. To use _Spack_ on _Gadi
 
 ## Set up Spack on Gadi
 
+!!! warning
+    The steps in this section only need to be done once.
+
 ### Create a directory for Spack
 
-Create a directory on the filesystem where _Spack_ will be installed (e.g. `/g/data/$PROJECT/$USER/<myspack>`). This directory shall be referred to as `<myspack>`.
+Create a directory on the filesystem where _Spack_ will be installed (e.g. `/g/data/$PROJECT/$USER/spack/0.22`).
 
 ```
-mkdir <myspack>
-cd <myspack>
+mkdir -p spack/0.22
+cd spack/0.22
 ```
 
 ### Clone the relevant git repositories
 
+!!! info
+    ACCESS-NRI maintains a fork of spack to enable back-porting fixes from more recent spack versions. This fork is the one used in these instructions.
+
 ```
-git clone -c feature.manyFiles=true https://github.com/ACCESS-NRI/spack.git --branch releases/v0.22 --single-branch --depth=100
+git clone -c feature.manyFiles=true https://github.com/ACCESS-NRI/spack.git --branch releases/v0.22
 git clone https://github.com/ACCESS-NRI/spack-packages.git --branch main
 git clone https://github.com/ACCESS-NRI/spack-config.git --branch main
 ```
@@ -47,7 +56,7 @@ To test _Spack_ we will create an `ACCESS-TEST` environment and build the releva
 
 ```
 module purge
-cd <myspack>
+cd spack/0.22
 . spack-config/spack-enable.bash
 git clone https://github.com/ACCESS-NRI/ACCESS-TEST.git
 spack env create test ACCESS-TEST/spack.yaml
@@ -61,3 +70,15 @@ spack env deactivate
 spack env rm test
 rm -rf ACCESS-TEST
 ```
+
+## Update Spack on Gadi
+
+Keep your Spack instance up-to-date by doing the following:
+
+```
+cd spack/0.22
+git -C spack fetch --all -Pp
+git -C spack reset --hard origin/releases/v0.22
+git -C spack-config pull
+git -C spack-packages pull
+```