update how-to-build

docs/src/Introduction/05-How-to-build.md

@@ -1,11 +1,26 @@
+## Dependencies:
+
+- CMake
+- Boost
+- OpenMP
+- Vulkan SDK
+- Cuda
+- H5
+- Python3
+    - matplotlib
+
 # How to Build
 
 For building and running the project, we recommend using [Visual Studio Code](https://code.visualstudio.com/) (VSCode) as your IDE, along with the C/C++ and CMake Tools extensions. These extensions significantly simplify the building process. However, you are free to use any IDE of your choice. If you are on a UNIX-like system, the `compile.sh` script can be used for compilation (see [using compile.sh](#using-compile.sh)).
 
+- [Widnows](#on-windows)
+- [Linux](#on-linux)
+
 ## CMake Options:
 
-- `RAYX_ENABLE_CUDA:BOOL` `default = ON` `enable search for Cuda on your system. If found, build with Cuda`
-- `RAYX_REQUIRES_CUDA:BOOL` `default = OFF` `require Cuda to be found on your system. Otherwise throw an error`
+- `WERROR:BOOL=OFF` `Treat warnings as errors. If warnings occur, compilation is aborted.`
+- `RAYX_ENABLE_CUDA:BOOL=ON` `Enable search for Cuda on your system, if it is found, the project will be built with cuda.`
+- `RAYX_REQUIRE_CUDA:BOOL=OFF` `Requires Cuda to be found on your system, otherwise an error will be thrown.`
 
 ## Cloning the Repository
 
@@ -22,23 +37,26 @@ Clone the git repository by running one of the following commands:
 ## On Windows
 
 ### Prerequisites
+- We recommend using the MSVC compiler for Windows, available through [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/).
 - Install [CMake](https://cmake.org/download/).
 - Install the [Vulkan SDK](https://vulkan.lunarg.com/sdk/home#windows) for Windows (at least version 1.3 or newer).
 - Install the [HDF5](https://www.hdfgroup.org/downloads/hdf5/) library.
 - Install Python3, python3-dev, and python3-matplotlib.
-- We recommend using the MSVC compiler for Windows, available through [Visual Studio](https://visualstudio.microsoft.com/downloads/) (2019 or newer).
 - Install the [Boost](https://www.boost.org/users/download/) library.
-- Add Boost to your PATH.
+    - Add Boost to your PATH.
 - Optional (required for Tracing on the GPU):
-    - Install [Cuda](https://developer.nvidia.com/Cuda-downloads?target_os=Windows).
-    Tested with Cuda version 12.5.1
-    - Add Cuda to your PATH.
+    - Install [Cuda](https://developer.nvidia.com/Cuda-downloads?target_os=Windows&target_arch=x86_64).
+    Tested with [Cuda 12.5.1](https://developer.nvidia.com/cuda-12-5-1-download-archive?target_os=Windows&target_arch=x86_64)
+        - Add Cuda to your PATH.
 
-### Known Issues
-- Installing the VulkanSDK at the root directory of your drive may cause issues. If you encounter problems with the VulkanSDK, consider installing it in a different directory.
+- Ensure cmake, gcc, gdb, and make are installed and up to date.
+- Install the Vulkan SDK from [here](https://vulkan.lunarg.com/sdk/home). Select a version under Linux -> Ubuntu Packages.
+- Install Python3, python3-dev, and python3-matplotlib.
+- The project leverages [libhdf5](https://github.com/BlueBrain/HighFive) for data management and incorporates various other libraries for graphical user interfaces, linear algebra computations, and handling different aspects of the X11 window system. Install the necessary libraries with the following command:
+- Install boost
 
 ### Building with VSCode
-- Open the project in VSCode. You will be prompted to select a build kit (e.g., gcc).
+- Open the project in VSCode. You will be prompted to select a build kit (e.g., Visual Studio 2019).
 - Allow the CMake Extension to configure the project.
 - You can then build the project using the build button in the bottom panel.
 
@@ -53,42 +71,63 @@ To use a custom generator for CMake, such as Ninja for faster builds, you can se
 
 see: [Cmake Options](#cmake-options)
 
+### Known Issues
+- Installing the VulkanSDK at the root directory of your drive may cause issues. If you encounter problems with the VulkanSDK, consider installing it in a different directory.
+
 ## On Linux
 
 ### Prerequisites
-- Ensure cmake, gcc, gdb, and make are installed and up to date.
-- Install the Vulkan SDK from [here](https://vulkan.lunarg.com/sdk/home). Select a version under Linux -> Ubuntu Packages.
-- Install Python3, python3-dev, and python3-matplotlib.
-- The project leverages [libhdf5](https://github.com/BlueBrain/HighFive) for data management and incorporates various other libraries for graphical user interfaces, linear algebra computations, and handling different aspects of the X11 window system. Install the necessary libraries with the following command:
-- Install boost
-- Optional (required for Tracing on the GPU):
-    - Install Cuda
-    - see [Determining Cuda and compiler version](#determining-cuda-and-compiler-version)
 
-### Ubuntu
-`apt update && apt -y install libblas-dev liblapack-dev libhdf5-dev libgtk-3-dev pkg-config libxi-dev libxcursor-dev libxinerama-dev libxrandr-dev`
+- See [Dependencies](#dependencies)
+- See [Determining Cuda and compiler version](#determining-cuda-and-compiler-version)
+- Or use one of following commands to install all dependencies on your linux distribution:
+
+#### Ubuntu
+
+`apt update && apt -y cmake g++ gdb install libblas-dev liblapack-dev libhdf5-dev libgtk-3-dev pkg-config libxi-dev libxcursor-dev libxinerama-dev libxrandr-dev`
 - Ensure the libraries are installed at `/usr/include/hdf5/serial` and `/usr/lib/x86_64-linux-gnu/hdf5/serial`.
 
-### Arch Linux
-Arch Linux users can obtain all necessary packages through pacman, yay, or other package managers. Specific instructions will be provided later.
+#### Arch Linux / Manjaro
+
+`sudo pacman -Sy cmake gcc vulkan-headers vulkan-icd-loader vulkan-validation-layers shaderc cuda hdf5 libaec zlib lib boost openmpi python-matplotlib`
 
-### Fedora
-To install the required packages on Fedora, run the following command:
+#### Fedora
 
 `sudo dnf install cmake gcc gdb vulkan vulkan-tools vulkan-validation-layers hdf5-devel ninja-build gcc-c++ vulkan-loader-devel glslc blas-devel lapack-devel gtk3-devel pkg-config libXi-devel libXcursor-devel libXinerama-devel libXrandr-devel boost`
 
 ### Determining Cuda and compiler version
-- GCC: Depending on the Cuda version, different versions of GCC may be supported.
-This projects is tested with Cuda version 12.4.1 and GCC version 13.3
-Please take a look at the supported versions of GCC for your Cuda installation:
+- Our dependency [Alpaka](https://github.com/alpaka-group/alpaka) currently supports Cuda up to version 12.3.2 (See: related [github issue](https://github.com/alpaka-group/alpaka/issues/2279))
     - <https://stackoverflow.com/questions/6622454/Cuda-incompatible-with-my-gcc-version>
     - <https://gist.github.com/ax3l/9489132>
-- Clang: Using clang as Cuda compiler is currently not supported.
+- MSVC: Depending on the Cuda version, different versions of MSVC may be supported.
+    - Please take a look at the supported versions of GCC for your Cuda installation:
+        - <https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html>
+        - Visual Studio 2019 is no longer supported, beginning at Cuda version 12.5.1
+    - This projects is tested with following versions:
+        - Cuda version 12.5.1 and Visual Studio 2022
+- GCC: Depending on the Cuda version, different versions of GCC may be supported.
+    - Please take a look at the supported versions of GCC for your Cuda installation:
+        - <https://stackoverflow.com/questions/6622454/Cuda-incompatible-with-my-gcc-version>
+        - <https://gist.github.com/ax3l/9489132>
+    - If you install cuda through the package manager, we recommend using the associated GCC.
+        - Ubuntu: /usr/bin/cuda-g++
+        installed by package `nvidia-cuda-dev` for Cuda and `nvidia-cuda-toolkit-gcc` for associated GCC.
+        - Arch / Manjaro: /opt/cuda/bin/g++
+        installed by package: `cuda` for with Cuda and associated GCC
+    - This projects is tested with following versions:
+        - Cuda version 12.3.2 and GCC version 13.3
+        - Cuda version 12.5.1 and GCC version 13.3
+- Clang: Using clang as Cuda compiler is currently not supported. Only builds with cuda disabled are supported. See [Cmake Options](#cmake-options).
 
 ### Using compile.sh
-usage: `./compile.sh`
+usage: `CXX=<path/to/compiler> ./compile.sh [OPTIONS]...`
 #### Options:
 - `--release` build in release mode (default: build in debug mode)
 - `--cuda` enable compilation with Cuda (default: build without Cuda)\
 see [Determining Cuda and compiler version](#determining-cuda-and-compiler-version) \
-example usage: `CXX=g++-13 ./compile.sh --cuda`
+example usage: `CXX=/opt/cuda/bin/g++ ./compile.sh --cuda`
+
+## Troubleshooting:
+
+In case you encounter issues, feel free to seek help on [github issues](https://github.com/hz-b/rayx/issues).
+Please provide system information, the build command and error log.