From 4f1295521204ae7aee4680b75deb5517a98fd6ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADt=20Ku=C4=8Dera?= <vit.kucera@cern.ch>
Date: Thu, 14 Nov 2024 13:38:07 +0100
Subject: [PATCH] Fix and improve installation instructions

Fixing wrong recompilation instructions. https://its.cern.ch/jira/browse/O2-5530
---
 docs/gettingstarted/installing.md | 64 +++++++++++++++----------------
 1 file changed, 31 insertions(+), 33 deletions(-)

diff --git a/docs/gettingstarted/installing.md b/docs/gettingstarted/installing.md
index d294fcae..b388ee88 100644
--- a/docs/gettingstarted/installing.md
+++ b/docs/gettingstarted/installing.md
@@ -56,41 +56,51 @@ See the [Troubleshooting](../troubleshooting/README.md) section for debugging ti
 
 ## Use your local software installations
 
-You will not find the packages you have built immediately available on your shell: we provide a tool
-called `alienv` that configures your shell according to the packages you want to load. `alienv` is
-capable of switching between different versions of the same package without a hassle.
+You will not find the packages you have built immediately available on your shell.
+We provide a tool called `alienv` that configures your shell according to the packages you want to load.
+`alienv` is capable of switching between different versions of the same package without a hassle.
 
-**List your available packages with:**
+Load the latest O2Physics version you have built.
 
 ```bash
-alienv q
+alienv enter O2Physics/latest
 ```
 
-**Load the latest version you have built of a package (O2Physics for instance):**
+The `alienv enter` command drops you to a new shell with the O2Physics environment. Unload the packages by simply exiting the environment with
+the `exit` command.
 
-```bash
-alienv enter O2Physics/latest
+```warning
+Dependencies are loaded automatically. Do not attempt to load O2 or ROOT as well! You will find them automatically in the environment. `alienv enter` is verbose and will inform you about the loaded packages.
 ```
 
-_⚠️  Dependencies are loaded automatically. Do not attempt to load O2 or ROOT as well, you will
-find them automatically in the environment! `alienv enter` is verbose and will inform you about the
-loaded packages if you have doubts._
+```tip
+If you have built several Git branches of O2Physics, you can enter the environment of a given branch `[branch]` with `alienv enter O2Physics/latest-[branch]-o2`.
 
-The `alienv enter` command drops you to a new shell. Unload the packages by simply exiting it with
-the `exit` command.
+You can list all your available packages with `alienv q`.
+```
 
 ## Building partially for development using ninja
 
-This requires that the O2Physics build succeeded. Enter the environment as explained in the previous step specifying in addition the ninja package:
+```note
+This requires that you have successfully built Git branch `[branch]` (e.g. `master`) of O2Physics with aliBuild (see Section [Build and rebuild](#build-and-rebuild)).
+
+You also need to have [`direnv`](https://direnv.net/docs/installation.html) installed to load the correct build environment automatically when you enter the build directory (and to unload it when you exit).
+```
+
+```warning
+This only builds O2Physics. If you have updated O2 or alidist, you first need to do a full build with aliBuild.
+```
+
+Go to the build directory.
 
 ```bash
-alienv enter O2Physics/latest ninja/latest
+cd "$ALIBUILD_WORK_DIR/BUILD/O2Physics-latest-[branch]/O2Physics"
 ```
 
-Go to the build directory
+Allow `direnv` to load the build environment. (Needed only once in a given directory.)
 
 ```bash
-cd ~/alice/sw/BUILD/O2Physics-latest/O2Physics
+direnv allow
 ```
 
 You can now rebuild and install entire O2Physics with
@@ -105,13 +115,9 @@ or just a specific directory with
 ninja <directory>/install
 ```
 
-For example:
+For example: `ninja PWGCF/Tasks/install`
 
-```bash
-ninja PWGCF/Tasks/install
-```
-
-You can redirect the terminal output to the standard aliBuild log file and see whether the build succeeded:
+**Tip:** You can redirect the terminal output to the standard aliBuild log file and see whether the build succeeded:
 
 ```bash
 ninja install > ../log 2>&1 && echo "Good" || echo "Bad"
@@ -123,18 +129,10 @@ A specific executable can be built in the staging directory `stage/bin` with
 ninja stage/bin/<target>
 ```
 
-For example:
-
-```bash
-ninja stage/bin/o2-analysis-cf-correlations
-```
+For example: `ninja stage/bin/o2-analysis-cf-correlations`
 
 The executable can then be executed directly from the staging directory:
 
 ```bash
-./stage/bin/o2-analysis-cf-correlations
-```
-
-```danger
-This only builds O2Physics. If you have updated O2 or alidist, you first need to do a full build with aliBuild. Then enter the environment again before using ninja.
+stage/bin/<target>
 ```