add docs for cmake

.github/actions/ctest-cdash/action.yml

@@ -27,10 +27,6 @@ runs:
     - name: running ctest
       run: |
         source $GITHUB_WORKSPACE/util/generate_geo_test.sh
-        cat $GITHUB_WORKSPACE/build/neuland/test/testNeulandSimulation.sh
-        echo $PATH
-        echo $LD_LIBRARY_PATH
-        root-config --libdir --cflags --ldflags
         ctest -S cmake/CI_CD/CDash.cmake -DBUILD_J=${NUM_THREADS}\
               -DTEST_MODEL=${TEST_MODEL}\
               -DTEST_NAME=${{ env.TEST_NAME }}\

doc/cmake_usage.md

@@ -0,0 +1,83 @@
+## Quick look
+
+### Dependency graph of R3BRoot
+
+![r3bbase](pics/r3bbase_dependers.png)
+
+> [!NOTE]
+> This dependency graph should be generated and updated by a CI pipeline.
+
+### Adding a library with a ROOT dictionary
+
+```cmake
+add_library_with_dictionary(
+    LIBNAME # library name for the target
+    R3BLibName
+    LINKDEF # LinkDef file name for the ROOT dictionary
+    LibNameLinkDef.h
+    HEADERS # header file names used by the library
+    file1.h
+    file2.h
+    SRCS # source file names used by the library
+    file1.cxx
+    file2.cxx
+    INCLUDEDIRS # include directories of the target
+    ${CMAKE_CURRENT_SOURCE_DIR} # the folder of the current CMakeLists.cxx
+    dir1 # any sub folders of ${CMAKE_CURRENT_SOURCE_DIR}
+    dir2
+    DEPENDENCIES # Dependencies
+    R3BSource)
+```
+
+## Principles of CMake
+
+### What is CMake
+
+CMake is the most popular _build system_ for large C++ projects. Users can specify the build and linking options for C++ binaries using commands defined in `CMakeLists.txt` files.
+
+### CMake targets
+
+The most important conception of "modern" CMake is the so-called CMake **target**. A CMake target can either represent a library or an executable. However, what really makes the CMake target so useful is that a target can attach a library/executable with multiple "target properties", that can be propagated along the dependency chain. See [this list](https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html#properties-on-targets) for all available properties of CMake targets.
+
+#### Creating a simple target
+
+A target can be created either with `add_library` or `add_executable`. The dependencies between different targets can be specified by using `target_link_libraries`:
+
+```cmake
+# Creating a library as a target
+add_library(mylib SHARED mylib.cxx others.cxx) # Same for add_executable
+
+# Linking the library with other targets/libraries
+target_link_libraries(mylib PUBLIC R3BSource PRIVATE R3BNeulandShared)
+
+# add include directory to the target property
+target_include_directories(mylib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} dir1 PRIVATE dir2)
+```
+
+`add_library` creates a library or an executable from a list of C++ source files. The header files, such as `mylib.h` and `others.h`, don't need to be added. The keyword `SHARED` tells the target represents a dynamic library. If a static library is needed, use the keyword `STATIC`.
+
+`target_link_libraries` specifies the dependencies of a library. If your library use any classes or functions defined in the library `R3BSource`, you have to add the "R3BSource" either after `PUBLIC` or `PRIVATE` keywords. `target_include_directories` specifies the include directories of a target. The include directories are a set of directory paths that C++ compiler will search when you use a include macro, such as `#include<FileName.h>`. If `FileName.h` doesn't exist in any include directories of the target, the compilation would fail.
+
+The keywords "PUBLIC" and "PRIVATE" specifies whether the properties or dependencies can be propagated in the dependency chain. `PUBLIC` means any libraries (or directories) linked to the current target are also linked to any other targets that link the current target. On the other hand, `PRIVATE` means the dependencies and include directories are only for the current target.
+
+For example, if the following dependency chain exists:
+
+```cmake
+target_link_libraries(A PUBLIC B PRIVATE C)
+target_link_libraries(D PUBLIC A)
+```
+the `D` target can use all classes and functions defined in both `A` and `B`, but not in `C`. The functions and classes from `C` can only be used in the target `A`.
+
+Similarly, if the following exists:
+
+```cmake
+target_include_directories(A PUBLIC dir1 PRIVATE dir2)
+target_include_directories(B PUBLIC dir3)
+target_link_libraries(B PUBLIC A)
+```
+the include directory of the target `B` contains both `dir3` and `dir1`, but not `dir2`.
+
+> [!IMPORTANT]
+> It's strongly recommended that `PRIVATE` should always prioritized above `PUBLIC` to reduce unnecessary dependencies. Clean dependencies can improve the compile time of the project.
+
+#### Behind `add_library_with_dictionary`

neuland/test/CMakeLists.txt

@@ -11,21 +11,17 @@
 # or submit itself to any jurisdiction.                                      #
 ##############################################################################
 
-cmake_minimum_required(VERSION 3.23)
-set(PROJECT_TEST_NAME NeulandUnitTests)
-
 if(GTEST_FOUND)
-    file(GLOB TEST_SRC_FILES ${PROJECT_SOURCE_DIR}/neuland/test/*.cxx)
-    add_subdirectory(digitizing)
-
-    link_directories(${ROOT_LIBRARY_DIR} ${FAIRROOT_LIBRARY_DIR} ${Boost_LIBRARY_DIRS})
-
-    set(TEST_DEPENDENCIES GTest::gtest_main GTest::gmock_main R3BNeulandDigitizing
-                          R3BNeulandReconstruction)
-
-    add_executable(${PROJECT_TEST_NAME} ${TEST_SRC_FILES})
-    target_link_libraries(${PROJECT_TEST_NAME} PRIVATE ${TEST_DEPENDENCIES})
-    gtest_discover_tests(${PROJECT_TEST_NAME} DISCOVERY_TIMEOUT 600)
+    add_executable(
+        NeulandUnitTests
+        digitizing/testNeulandDigitizingPaddle.cxx
+        digitizing/testNeulandDigitizingTamex.cxx
+        NeulandUnitTests.cxx
+        testClusteringEngine.cxx
+        testNeulandMultiplicityCalorimetricPar.cxx)
+    target_link_libraries(NeulandUnitTests PRIVATE GTest::gtest_main GTest::gmock_main
+                                                   R3BNeulandDigitizing R3BNeulandReconstruction)
+    gtest_discover_tests(NeulandUnitTests DISCOVERY_TIMEOUT 600)
 endif(GTEST_FOUND)
 
 set(simuPars