Merge pull request #233 from vkucera/troubleshooting

Update and extend installation and troubleshooting

Author: ddobrigk

docs/gettingstarted/gitbasics.md

@@ -22,7 +22,7 @@ Developers can review project history to find out:
 Selected sections:
 
 - [Saving changes](https://www.atlassian.com/git/tutorials/saving-changes) – `add`, `commit`, `diff`, `stash`
-- [Inspecting a repository](https://www.atlassian.com/git/tutorials/inspecting-a-repository) – `status`, `tag`, `blame`
+- [Inspecting a repository](https://www.atlassian.com/git/tutorials/inspecting-a-repository) – `status`, `log`, `tag`, `blame`
 - [Undoing changes](https://www.atlassian.com/git/tutorials/undoing-changes) – `checkout`, `clean`, `revert`, `reset`, `rm`
 - [Rewriting history](https://www.atlassian.com/git/tutorials/rewriting-history) – `commit`, `rebase`, `reflog`
 - [Syncing](https://www.atlassian.com/git/tutorials/syncing) – `remote`, `fetch`, `push`, `pull`
@@ -56,4 +56,4 @@ Selected sections:
 
 [Meld](https://meldmerge.org/) – Visual diff and merge tool that can be used with Git commands `git difftool` and `git mergetool`
 
-[Tig](https://jonas.github.io/tig/) – Git repository browser
+[Tig](https://jonas.github.io/tig/) – Git repository browser

docs/gettingstarted/installing.md

@@ -23,11 +23,11 @@ mkdir -p ~/alice
 cd ~/alice
 ```
 
-Download O2 and O2Physics (note the `--defaults o2`):
+Download O2 and O2Physics:
 
 ```bash
-aliBuild init O2@dev --defaults o2
-aliBuild init O2Physics@master --defaults o2
+aliBuild init O2@dev
+aliBuild init O2Physics@master
 ```
 
 If you perform `ls` under your work directory, you will see the packages you have downloaded via
@@ -40,7 +40,7 @@ to keep them up-to-date manually.
 ## Check your prerequisites
 
 ```bash
-aliDoctor O2Physics --defaults o2
+aliDoctor O2Physics
 ```
 
 aliDoctor will warn you that some packages have to be built as they could not be found from the
@@ -49,9 +49,11 @@ system.
 ## Build and rebuild
 
 ```bash
-aliBuild build O2Physics --defaults o2
+aliBuild build O2Physics
 ```
 
+See the [Troubleshooting](../troubleshooting/README.md) section for debugging tips if the build fails.
+
 ## Use your local software installations
 
 You will not find the packages you have built immediately available on your shell: we provide a tool
@@ -91,7 +93,13 @@ Go to the build directory
 cd ~/alice/sw/BUILD/O2Physics-latest/O2Physics
 ```
 
-You can now rebuild and install a specific directory with
+You can now rebuild and install entire O2Physics with
+
+```bash
+ninja install
+```
+
+or just a specific directory with
 
 ```bash
 ninja <directory>/install
@@ -103,6 +111,12 @@ For example:
 ninja PWGCF/Tasks/install
 ```
 
+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"
+```
+
 A specific executable can be built in the staging directory `stage/bin` with
 
 ```bash

docs/troubleshooting/README.md

@@ -9,13 +9,21 @@ title: Troubleshooting
 
 ### Compilation problems
 
-```todo
-To be added
+If your O2 code fails to compile and you have difficulties finding the reason, try the following tips.
+
+Search for errors (and warnings) in the compilation log file (here assumed `../log`) using the `grep` command.
+
+Get the list of executables that failed to build and the list of problems in the code (in the format `file:line:column`):
+
+```bash
+grep -e "FAILED:" -e "error:" -e "warning:" ../log | cut -d : -f -3
 ```
 
+If you want to see the full messages, remove the `| cut...` part.
+
 ### Runtime problems
 
-If your O2 code is crashing and you have difficulties finding out the reason, try the following tips.
+If your O2 code is crashing and you have difficulties finding the reason, try the following tips.
 
 Redirect the terminal output to a text file (here called `stdout.log`):
 
@@ -75,6 +83,23 @@ If the reported table is part of the main [AO2D tables](../datamodel/ao2dTables.
 You can check by opening it with ROOT if the corresponding table exists in the file by navigating to the reported folder (here: `DF_2853960297589372650`).
 
 Most likely however the table which is missing has to be produced by a [helper task](../datamodel/helperTaskTables.md).
+
+First, look for a solution in the list of [Special cases](#special-cases).
+If the missing table is not mentioned there, try to find the missing workflow following the instructions for [General cases](#general-cases).
+
+#### Special cases
+
+- Missing `track`: If you are running on Run 3 input, add `o2-analysis-track-propagation`.
+  - Please refer to the documentation on the [track propagation](../basics-usage/HelperTasks.md#track-propagation) for details.
+- Missing `collision_001`: Please add the `o2-analysis-collision-converter`.
+  - Missing `collision`: If you are executing `o2-analysis-collision-converter`, remove it.
+- Missing `zdc_001`: Please add the `o2-analysis-zdc-converter`.
+  - Missing `zdc`: If you are executing `o2-analysis-zdc-converter`, remove it.
+- Missing `fv0c`: If you are running on Run 3 input, please make sure that the process switches in the `bc-selection`, `event-selection` and `multiplicity-table` tasks are set to `"processRun2": "false", "processRun3": "true"` in your config JSON; see e.g. the `Configurables` section in the [event selection](../basics-usage/HelperTasks.md#event-selection) documentation.
+- Missing `tofsignal`: Please refer to the documentation on the [TOF PID](../basics-usage/HelperTasks.md#particle-identification) requirements.
+
+#### General cases
+
 You can identify the missing workflow by running the [`find_dependencies.py`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/find_dependencies.py) script.
 The procedure is simple: If the error message complains about a missing table `DF_<id>/O2<table>` then you have to run `$O2PHYSICS_ROOT/share/scripts/find_dependencies.py -t <table>`
 inside the O2Physics environment and add the correct one among the listed producer workflows to your command line.
@@ -97,13 +122,6 @@ o2-analysis-timestamp | o2-analysis-my-analysis ...
 
 and the table should be found.
 
-#### Special cases
-
-- Missing `track`: If you are running on Run 3 data or MC, please refer to the documentation on the [track propagation](../basics-usage/HelperTasks.md#track-propagation).
-- Missing `fv0c`: If you are running on Run 3 data or MC, please make sure that the process switches in the `bc-selection`, `event-selection` and `multiplicity-table` workflows are set to `"processRun2": "false", "processRun3": "true"` in your config JSON; see e.g. the `Configurables` section in the [event selection](../basics-usage/HelperTasks.md#event-selection) documentation.
-- Missing `tofsignal`: Please refer to the documentation on the [TOF PID](../basics-usage/HelperTasks.md#particle-identification) requirements.
-- Missing `collision_001`: Please add the `o2-analysis-collision-converter`.
-
 ### CCDB object not found
 
 Error messages:
@@ -126,9 +144,11 @@ How to check the timestamp?
 
 ### Alien connection failed
 
-```todo
 Error message:
+
+```text
+Alien Token Check failed - Please get an alien token before running with https CCDB endpoint, or alice-ccdb.cern.ch!
 ```
 
 - Create an Alien token by executing the `alien-token-init` command inside the O2Physics environment.
-- Verify that the connection can be established by executing `alien.py`.
+- Verify that the connection can be established by executing `alien.py`. You should be greeted with `Welcome to the ALICE GRID`. Exit with `exit`.