Updated README.md.

README.md

@@ -5,25 +5,35 @@ Installation Instructions for for CbmRoot
 
 ## 1.1 Compiler
 
-To be able to compile CbmRoot a compiler with full C++11 support is needed. 
+To be able to compile CbmRoot, a compiler with full C++11 support is needed. 
 GCC since version 4.8 and clang since version 3.4 are known to work without
 problems. 
 
 ## 1.2 FairSoft
 
-To install, compile, and run CbmRoot several external programs are required. 
-This are for example Root, Geant3 or Geant4. The complete list can be found 
-on the FairRoot webpage (fairroot.gsi.de). Since most of these programs can't 
-be installed using the package manager of the used Linux distribution, or at 
-least can't be installed in the required version, the FairRoot team provides 
-a GIT repository with all needed packages and some scripts to automatically 
-build and install these so called external packages.
+To install, compile, and run CbmRoot, several external programs are required. 
+These are for example Root, Geant3 or Geant4 and many others. Installing these
+is the first step of the CbmRoot installation. As the individual installation of 
+each of these programs is very time consuming, the FairRoot team provides a 
+software bundle known as FairSoft, which contains all the needed packages, and also 
+provides tools for its automated installation on several platforms. The most up-to-date 
+information regarding the installation of FairSoft, together with a complete list of 
+the contained packages, can be found on the project's GitHub page:
 
-Detailed instructions how to get and compile FairSoft (aka external packages) 
-can be found at the following webpage
+  https://github.com/FAirRootgroup/FairSoft
+
+This page should be considered the primary source of information regarding FairSoft,
+which takes precedence over any others (which may in some cases be outdated). 
+Additional information, for instance regarding older versions, can be found on 
+Cbm Redmine:
 
   https://redmine.cbm.gsi.de/projects/cbmroot/wiki/Install_External_Packages
 
+We recommend to always use the latest FairSoft relase version. Currently this is
+"apr21p2", which is compatible with the latest version of CbmRoot. Different
+combinations of older versions of FairSoft, FairRoot and CbmRoot may work in 
+principle, but are not endorsed or actively supported. 
+
 Please make sure SQLite is installed on your system before compiling 
 FairSoft, as this is required by CbmRoot. Failing compile FairSoft
 with SQLite support will lead to a crash during the CbmRoot compilation. 
@@ -43,50 +53,103 @@ existing software. For an installation which is to be shared between users
 on a MacOS or linux system it is recommended to use the opt/ folder.
 Consider also using the auto installer (see section 3). 
 
-If you are working at GSI there are always ready-to-use versions of 
-FairSoft available. For detailed information please check the following 
-wiki page
+The compilation of FairSoft is the most time-consuming part of the CbmRoot installation
+and can take several hours, depending on your system. If you are working at GSI there are 
+always ready-to-use versions of FairSoft available. For detailed information please check 
+the following wiki page
 
   https://redmine.cbm.gsi.de/projects/cbmroot/wiki/RunCbmGSI
 
 ## 1.3 FairRoot
 
-CbmRoot is based on FairRoot, a package which meanwhile serves several
+CbmRoot is based on FairRoot, a simulation, reconstruction and analysis 
+framework based on the ROOT system, which by now is used by several
 experiments as base for their developments. Beside FairSoft you need also
-to install FairRoot to be able to compile CbmRoot 
+to install FairRoot to be able to compile CbmRoot.
+
+Detailed instructions how to get and compile FairRoot can be found on
+the project's GitHub page at:
+
+  https://github.com/FairRootGroup/FairRoot
 
-Detailed instructions how to get and compile FairRoot can be found at the 
-following webpage
+We again recommend this official repository as the primary source of
+information, and recommend using the latest release version. 
+
+Other information can be found at: 
 
   https://redmine.cbm.gsi.de/projects/cbmroot/wiki/InstallFairRoot
 
-# 2. Recommended versions
+In order to compile FairRoot, you must set the environment variable SIMPATH
+to contain the path to your FairSoft installation, i.e.:
 
-GCC  : >= 4.8
-  or
-Clang: >= 3.4
+    export SIMPATH=[path_to_fairsoft]
+
+Not setting this variable (or FAIRROOTPATH, defined below) properly is a common
+source of problems. 
+
+# 2. Installing CbmRoot
+
+After installing FairSoft and FairRoot, to install CbmRoot first
+create a local clone of the Git repository using: 
+ 
+    git clone git@git.cbm.gsi.de:computing/cbmroot.git
+
+Subsequently, create a build directory:
+
+    mkdir build_cbmroot
+  
+To proceed, you must set the environment variables SIMPATH and FAIRROOTPATH,
+to the folders of your FairSoft and FairRoot installations, i.e. 
 
-FairSoft: jun19p2
+    export SIMPATH=[path_to_fairsoft]
+    export FAIRROOTPATH=[path_to_fairroot install]
 
-FairRoot: v18.2.1
+From your build directory, then call
+
+    cmake [path_to_cbmroot]
+    make -j[number_of_cores]
+
+After your build is complete, before running any part of CbmRoot from a shell, 
+a large number of environment variables must be set, which contain various
+library and include paths. This is done automatically by executing the "config.sh"
+or "config.csh" script from your CbmRoot build directory. If you are using
+a Bash shell, we recommend adding the following line to .bashrc to further automate
+this step:
+
+    source ~/build_cbmroot/config.sh > /dev/null 2>&1
 
 # 3. Automatic installation
 
 To make the installation more easy we provide a script which automatically
-gets and installs FairSoft, FairRoot, and CbmRoot in one go. The script
-always take the correct FairSoft and FairRoot versions. 
-The full description of this process is at 
+compiles and installs FairSoft, FairRoot, and CbmRoot in one go. The script
+always combines the correct FairSoft and FairRoot versions. The full description 
+of this process is at 
 
   https://redmine.cbm.gsi.de/projects/cbmroot/wiki/InstallCbmRootAuto
 
-The one line command which has to be executed inside the CbmRoot source
+The one-line command which has to be executed inside the CbmRoot source
 directory is
 
-  ./autoinstall_framework.sh 1 1 1
+    ./autoinstall_framework.sh 1 1 1
+
+The same scipt can be used to only install any subset of the three packages. See
+the Redmine page or the script itself for further details. 
+
+**(The auto-install script currently doesn't work with the latest version of FairSoft)**
+
+# 4. Recommended versions
+
+GCC  : >= 4.8
+  or
+Clang: >= 3.4
+
+FairSoft: apr21p2
+
+FairRoot: v18.6.6
 
-# 4. Further remarks
+# 5. Further remarks
 
 Compiling CbmRoot with multicore support using "make -j", without 
-specifying the number of threads is known to cause MacOS and Ubuntu 
+specifying the number of threads, is known to cause MacOS and Ubuntu 
 20.04 LTS systems to freeze. Please explicitly choose a number of cores 
 which is suitable for your system.