[legacy] documentation: Add infos macosx

Describe some known problems on macosx and the corresponding
solutions.

Author: fuhlig1

legacy/README.md

@@ -51,6 +51,41 @@ cmake -S <path-to-source> -B <path-to-build> -C <path-to-source>/FairSoftConfig.
 
 Set the installation prefix and more customization options in the [`FairSoftConfig.cmake`](../FairSoftConfig.cmake) file itself.
 
+#### 3.1 CMake configure step for macOS users
+
+There are some known problems about the compilation of FairSoft on macosx.
+
+The first two problems are related to the version of the **patch** and **make**
+commands on macosx.
+
+The **patch** command does not support the needed parameters,
+so one needs ot install a version of the **patch** command with brew.
+The **make** command doesn't properly support the jobsserver which allows
+parallel builds of all the packages contained in FairSoft which slows down
+the installation enormously. The version provided by brew fixes the problem.
+Both packages are already added in the updated setup script for macosx.
+If found the packages from the homebrew installation directory will be used.
+
+The last problem is related to the macosx, compiler and SDK versions, such
+that it depends on the personal setup. As described in more detail at
+[macOS SDK](advanced.md#macos-sdk)! ROOT is very picky about the compiler
+and the connected SDK. Compiling older ROOT versions with newer compilers
+may need using an older SDK version. If not specified explicitely the
+latest SDK version is used. To use an older SDK version on needs to add the
+following parameter when running CMake
+
+```
+-DCMAKE_OSX_SYSROOT=<full path to SDK directory>
+```
+
+e.g. for Apple Clang 17 on macosx 15 or Apple Clang 16 on macosx 14
+
+```
+-DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX14.sdk
+```
+
+More information can be found at
+
 **macOS users**: Notice [macOS SDK](advanced.md#macos-sdk)!
 
 ### 4. CMake build/install step

legacy/advanced.md

@@ -59,6 +59,17 @@ installed SDK version is the most sensible course of action here. `brew`
 contains already some logic to detect and choose the latest SDK. See the
 "macOS SDK" section in [FairSoftConfig.cmake](../FairSoftConfig.cmake).
 
+The downside with picking the latest SDK version is that some older ROOT
+versions can't be compiled any longer after updating the compiler and the
+connected SDK. As described above the problems with compilation errors due
+to **wrong** SDKs are because of ROOT and there mainly becuase of rootcling.
+To overcome the problem and allow a more flexible compilation also with
+non default SDKs we add the possibilty to define an older SDK when running
+CMake. There are some additional changes in the build system of ROOT such
+that rootcling take the setting properly into account. With this changes it
+becomes possible to install FairSoft jan24 (ROOT 6.30.08) with Apple Clang
+17 on macosx 15.
+
 **If you have a deeper understanding of this issue and know a better
 solution, please let us know!**