second draft of eessi doc

Author: claudia-lola

docs/eessi.md

@@ -1,57 +1,86 @@
 # EESSI Guide
 
-## How to load EESSI
-Loading an EESSI environment module:
-```[bash]
-source /cvmfs/software.eessi.io/versions/2023.06/init/lmod/bash
-```
-Activating EESSI environment:
-```[bash]
-source /cvmfs/software.eessi.io/versions/2023.06/init/bash
-```
+## How to Load EESSI
+EESSI can be initialised using either of the following methods:
+
+1. Load the EESSI Environment Module.
+
+    The following command configures Lmod for your system and automatically loads the EESSI module:
+    ```[bash]
+    source /cvmfs/software.eessi.io/versions/2023.06/init/lmod/bash
+    ```
+    If Lmod is already installed, the following steps can be used to set up EESSI.
+    Check if the `module` command is already defined on your system and what version it has.
+    ```[bash]
+    command -v module && module --version
+    ```
+    - If you're already using Lmod with a version >= 8.6, resetting `$MODULEPATH` is recommended.
+        ```[bash]
+        module unuse $MODULEPATH
+        module use /cvmfs/software.eessi.io/init/modules
+        module load EESSI/2023.06
+        ```
+
+    - If you are using an older version of Lmod or another tool utilising `$MODULEPATH`, it is recommended to unset `$MODULEPATH` and then initialise a compatible version of Lmod. For example, the one shipped with EESSI.
+        ```[bash]
+        unset MODULEPATH
+        source /cvmfs/software.eessi.io/versions/2023.06/init/lmod/bash
+        ```
+
+2. `source` the EESSI initialisation script for `bash`.
 
-## GPU Support with EESI
-To enable GPU support you need a site-specific build that has `cuda` enabled. For guide to do this please refer to `docs/image-build`. This is
-because CUDA-drivers are host specific and EESSI can not ship NVIDIA drivers due to licensing + kernel specific constraints. This means that the
-host must provide the drivers in a known location (`host_injections`).
+    The EESSI environment can be sourced (in a non-reversible way) by running:
+    ```[bash]
+    source /cvmfs/software.eessi.io/versions/2023.06/init/bash
+    ```
+
+Successful environment setup will show `{EESSI 2023.06}` at the start of your CLI.
+
+## GPU Support with EESSI
+To enable GPU support, you need a site-specific build that has CUDA enabled. For a guide on how to do this, please refer to [docs/image-build.md](../image-build.md).
 
 ### Using GPUs
-All CUDA-enabled software in EESSI expects CUDA drivers in a specific `host_injections` subdirectory.<br>
+All CUDA-enabled software in EESSI expects CUDA drivers in a specific `host_injections` directory. This can be checked by running:
 ```[bash]
 ls -l /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/amd/zen3/software/CUDA/12.1.1/bin/nvcc
 ```
-The output of this should show a symlink to the EESSI `host_injections` dir like so:
+The output should show a symlink to the EESSI `host_injections` directory.
 ```[bash]
 lrwxrwxrwx 1 cvmfs cvmfs 109 May  6  2024 /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/amd/zen3/software/CUDA/12.1.1/bin/nvcc
 -> /cvmfs/software.eessi.io/host_injections/2023.06/software/linux/x86_64/amd/zen3/software/CUDA/12.1.1/bin/nvcc
 ```
-To expose the Nvidia GPU drivers.
+
+#### To expose the NVIDIA GPU drivers:
+Use the `link_nvidia_host_libraries.sh` script, provided by EESSI, to symlink your GPU drivers into `host_injections`.
 ```[bash]
 /cvmfs/software.eessi.io/versions/2023.06/scripts/gpu_support/nvidia/link_nvidia_host_libraries.sh
 ```
+Rerun this script when your NVIDIA GPU drivers are updated. It is also safe to rerun at any time as the script will detect if the driver versions have already been symlinked.
+
+### Building with GPUs
 
-### Buidling with GPUs
+Check `which nvcc` to confirm that the CUDA compiler is found.
 
-Checking `nvcc --version` and `which nvcc` to see if `CUDA` compiler is found.<br>
-<br>
-If `nvcc` not found run:<br>
+If `nvcc` is not found, add the CUDA path to your environment. Replace `13.0` with your specific CUDA version:
 ```[bash]
 export PATH=/usr/local/cuda-13.0/bin:$PATH
 ```
-(with your specific cuda version)<br>
-`which nvcc` should now show path to compiler.<br>
-<br>
-Running `which gcc` will give path `.../2023.06/compat...`<br>
-Loading EESSI module (It is important to load a `gcc` that is compatible with the host's CUDA version.):<br>
+
+`which nvcc` should now show the path to the CUDA compiler.
+
+#### Loading EESSI module for the GCC compiler
+
+Running `which gcc` should initially show a path `.../2023.06/compat...` which points to the compatibility compiler.
+It is important to load a `gcc` version that is compatible with the host's CUDA version:
 ```[bash]
 module load GCC/12.3.0
 ```
-Now running `which gcc` will give path `.../2023.06/software...`<br>
-<br>
-Now you can run `cmake` and `make` to compile `CUDA` using EESSI's `gcc`.<br>
+Running `which gcc` will now give a path `.../2023.06/software...` which is the full compiler provided by EESSI. This is what we want for CUDA builds.
+
+Now you can run `cmake` and `make` to compile CUDA using EESSI's `gcc`.
 
 #### Test setup: Compile deviceQuery from CUDA-Samples
-To test that your EESSI set up can compile `CUDA`, try compiling deviceQuery from CUDA-Samples with the following steps:<br>
+To test that your EESSI setup can compile CUDA, try compiling `deviceQuery` from CUDA-Samples with the following steps:
 ```[bash]
 git clone https://github.com/NVIDIA/cuda-samples.git
 cd cuda-samples/Samples/1_Utilities/deviceQuery