From cb7e814f91baaecc610585a8f51a97c3e768876c Mon Sep 17 00:00:00 2001
From: lintao <lintao@ihep.ac.cn>
Date: Sun, 20 Oct 2024 14:24:22 +0800
Subject: [PATCH] Doc: add build related docs.
---
docs/source/development/build.md | 50 ++++++++++++++++++++++++++++++++
docs/source/index.rst | 1 +
2 files changed, 51 insertions(+)
create mode 100644 docs/source/development/build.md
diff --git a/docs/source/development/build.md b/docs/source/development/build.md
new file mode 100644
index 00000000..4e897af8
--- /dev/null
+++ b/docs/source/development/build.md
@@ -0,0 +1,50 @@
+# CMake: building software
+There is a script `build.sh` to build the CEPCSW. Inside this script, it consists of three major steps:
+* configure: in this step, a *build directory* is created and the cmake reads `CMakeLists.txt` in *source code directory* and generates config files which will be used to build the project.
+* build: in this step, the project is built according to the config files under *build directory*.
+* install: in this step, the libraries, header files and python scripts are installed into *install directory*, which is `InstallArea`.
+
+The `cmake` command reads the `CMakeLists.txt` files recursively to produce the config files. As there are some common patterns to build the packages in the project, we use some macros from Gaudi framework.
+
+* `gaudi_add_library`: produce a shared library, which will be linked by other libraries.
+ * The source code files need to be added after `SOURCES` option.
+ * The link libraries need to be added after `LINK` option.
+* `gaudi_add_module`: produce a module library, which will be imported by Gaudi. Note, this library should not be linked by other libraries.
+ * Options `SOURCES` and `LINK` are same as `gaudi_add_library`.
+
+We also use some macros from CMake.
+* `target_include_directories`: specify the include directories when build a target.
+* `install`: install the targets.
+
+Examples could be found in CEPCSW.
+
+For example, the `RecPFACyber` package uses all the macros:
+```cmake
+gaudi_add_library(CrystalCaloRecLib
+ SOURCES src/Objects/CaloUnit.cc
+ src/Objects/CaloHit.cc
+ ...
+ LINK k4FWCore::k4FWCore
+ GearSvc
+ CrystalEcalSvcLib
+ ...
+)
+
+gaudi_add_module(CrystalCaloRec
+ SOURCES src/CyberPFAlg.cpp
+ src/CyberDataCol.cpp
+ ...
+ LINK CrystalCaloRecLib
+)
+
+target_include_directories(CrystalCaloRec PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>/include
+ $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+
+install(TARGETS CrystalCaloRecLib CrystalCaloRec
+ EXPORT CEPCSWTargets
+ RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT bin
+ LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}" COMPONENT shlib
+ COMPONENT dev)
+```
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f737e312..1861f060 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,6 +23,7 @@ Contents
:caption: Development Process
development/overview.md
+ development/build.md
development/doc.md
.. toctree::
--
GitLab