diff --git a/CMakeLists.txt b/CMakeLists.txt index 3f36c8f..e3e1a76 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,8 @@ cmake_minimum_required(VERSION 3.28) -include(${CMAKE_SOURCE_DIR}/cmake/option_settings.cmake) +list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake) + +include(option_settings) set(ENV{CMAKE_ENABLE_TEST} ${ENABLE_TEST}) project( @@ -8,9 +10,10 @@ project( VERSION 0.1.1 LANGUAGES CXX C) -include(${CMAKE_SOURCE_DIR}/cmake/install_config.cmake) -include(${CMAKE_SOURCE_DIR}/cmake/project_config.cmake) -include(${CMAKE_SOURCE_DIR}/cmake/check_compilers.cmake) +include(sphinx_setup) +include(install_config) +include(project_config) +include(check_compilers) set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_EXTENSIONS ON) @@ -21,7 +24,7 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang") list(APPEND CMAKE_CXX_FLAGS "-fexperimental-library") endif() -include(${CMAKE_SOURCE_DIR}/cmake/import_packages.cmake) +include(import_packages) add_subdirectory(frontend) add_subdirectory(backend) diff --git a/README.md b/README.rst similarity index 53% rename from README.md rename to README.rst index c45b1f7..899e062 100644 --- a/README.md +++ b/README.rst @@ -1,40 +1,55 @@ -# srs-daq - A data acquisition program for SRS FEC & VMM3 +====================================================================== +srs-daq - A data acquisition program for SRS FEC & VMM3 +====================================================================== + +.. |codacyBadge| image:: https://app.codacy.com/project/badge/Grade/7e8c956af1bc46c7836524f1ace32c11 + :alt: Codacy badge + :target: https://app.codacy.com/gh/YanzhaoW/srs-daq/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade +.. |ciPipeline| image:: https://github.com/YanzhaoW/srs-daq/actions/workflows/ci.yml/badge.svg?branch=dev + :alt: ci pipeline + :target: https://github.com/YanzhaoW/srs-daq/actions?query=branch%3Adev +.. |githubReleases| image:: https://img.shields.io/github/release/YanzhaoW/srs-daq.svg + :alt: github releases + :target: https://github.com/YanzhaoW/srs-daq/releases +.. |license| image:: https://img.shields.io/badge/License-MIT-yellow.svg + :alt: License: MIT + :target: https://opensource.org/licenses/MIT + +Introduction +================================================= -[![Codacy Badge](https://app.codacy.com/project/badge/Grade/7e8c956af1bc46c7836524f1ace32c11)](https://app.codacy.com/gh/YanzhaoW/srs-daq/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -[![CI pipeline](https://github.com/YanzhaoW/srs-daq/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/YanzhaoW/srs-daq/actions?query=branch%3Adev) -[![Github Releases](https://img.shields.io/github/release/YanzhaoW/srs-daq.svg)](https://github.com/YanzhaoW/srs-daq/releases) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +srs-daq is an asynchronous data IO program for SRS system. It communicates with the SRS system through the UDP socket with different commands to, for example, start or stop the data transferring from the system. Data sent from the SRS system is then analyzed in the program in different stages, such as the deserialization, monitoring, data conversion and writing to different files or sockets. There are 4 types of output formats supported: binary file, root file (require ROOT), JSON file and UDP socket. Binary file can store either **as-is** data sent from the SRS system or the Google's Protobuf binary. UDP socket can only send the Google's Protobuf binary due to its easy deserialization. -## Introduction +Technical information about classes and functions can be found in this `Doxygen documentation `_. -srs-daq is an asynchronous data IO program for SRS system. It communicates with the SRS system through the UDP socket with different commands to, for example, start or stop the data transferring from the system. Data sent from the SRS system is then analyzed in the program in different stages, such as the deserialization, monitoring, data conversion and writing to different files or sockets. There are 4 types of output formats supported: binary file, root file (require ROOT), JSON file and UDP socket. Binary file can store either **as-is** data sent from the SRS system or the Google's Protobuf binary. UDP socket can only send the Google's Protobuf binary due to its easy deserialization. +Download the project +---------------------------------------- -Technical information about classes and functions can be found in this [Doxygen documentation](https://yanzhaow.github.io/srs-daq/). +Please visit the `release page `_ and download the latest release for your operating system: -## Download the project +.. code-block:: bash -Please visit the [release page](https://github.com/YanzhaoW/srs-daq/releases) and download the latest release for your operating system: + wget [download-link] + tar -xvzf [download-file] -```bash -wget [download-link] -tar -xvzf [download-file] -``` After unzipping the downloaded file, a new folder `srs-daq` will be put in the current folder. If your operating system is not in the download link list. Please either [build the project from source](doc/build_source.md) or create an issue to make the request. -> [!IMPORTANT] -> If the ROOT support is needed, please install the same ROOT version used in the download link. +.. note:: + If the ROOT support is needed, please install the same ROOT version used in the download link. -## srs_control - The main program +srs_control - The main program +================================================= Go to `srs-daq/bin` directory and run -```bash -./srs_control [-p DATA_PRINT_OPTION] [-v LOG_LEVEL] [-h] -``` +.. code-block:: bash + + ./srs_control [-p DATA_PRINT_OPTION] [-v LOG_LEVEL] [-h] -### Run-time options +Run-time options +------------------------------------------- - `-h` or `--help`: print the help message. - `-v` or `--version`: show the current version. @@ -47,7 +62,8 @@ Go to `srs-daq/bin` directory and run - all: print all data, including header, hit and marker data, but no raw data. - `-o` or `--output-files`: set the file outputs (more detail below). -### Data output to multiple files +Data output to multiple files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `srs_control` can output received data into multiple files with different types at the same time. Currently, following output types are available (or planned): @@ -62,31 +78,35 @@ Users have to use the correct file extensions to enable the corresponding output To output the same data to multiple different output types at the same time: -```bash -./srs_control -o "output1.root" -o "output2.root" \ - -o "output.bin" -o "output.binpb" \ - -o "output.json" -o "localhost:9999" -``` +.. code-block:: bash -## Usage of other executables + ./srs_control -o "output1.root" -o "output2.root" \ + -o "output.bin" -o "output.binpb" \ + -o "output.json" -o "localhost:9999" -### `srs_check_binpb` +Usage of other executables +------------------------------------------- + +`srs_check_binpb` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is used for checking the contents of a Protobuf binary file. -```bash -./srs_check_binpb -f filename.binpb -``` +.. code-block:: bash + + ./srs_check_binpb -f filename.binpb -### `srs_check_udp` +`srs_check_udp` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The executable checks the data output from a UDP socket. -```bash -./srs_check_udp --port [port number] --ip "localhost" -``` +.. code-block:: bash + + ./srs_check_udp --port [port number] --ip "localhost" -## Usage of SRS library +Usage of SRS library +------------------------------------------- The program also has APIs to provide following functionality: @@ -94,15 +114,18 @@ The program also has APIs to provide following functionality: For more information, please check the [library usage](doc/library_usage.md). -### Custom configuration +Custom configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To be added ... -## Acknowledgments +Acknowledgments +------------------------------------------- -- A lot of information was used from the existing codebase of the VMM slow control software [vmmsc](https://gitlab.cern.ch/rd51-slow-control/vmmsc.git). +- A lot of information was used from the existing codebase of the VMM slow control software `vmmsc `_. -## TODO list +TODO list +------------------------------------------- - unit tests - Control/monitoring for SRS FEC & VMM3a hybrids diff --git a/cmake/option_settings.cmake b/cmake/option_settings.cmake index 609625b..e1ffd4e 100644 --- a/cmake/option_settings.cmake +++ b/cmake/option_settings.cmake @@ -2,3 +2,7 @@ option(USE_ROOT "Force to use ROOT dependency." OFF) option(NO_ROOT "Disable the usage of ROOT dependency." OFF) option(BUILD_STATIC "Enable static linking of libstdc++." OFF) option(ENABLE_TEST "Enable testing framework of the project." ON) + +set(SPHINX_BUILDER + "html" + CACHE STRING "Set the builder for sphnix-build.") diff --git a/cmake/sphinx_setup.cmake b/cmake/sphinx_setup.cmake new file mode 100644 index 0000000..1aee926 --- /dev/null +++ b/cmake/sphinx_setup.cmake @@ -0,0 +1,7 @@ +configure_file(${CMAKE_SOURCE_DIR}/doc/conf.py.in ${CMAKE_BINARY_DIR}/conf.py) + +add_custom_target( + sphinx + COMMENT "launching sphinx build" + COMMAND sphinx-build --build ${SPHINX_BUILDER} --write-all -c ${CMAKE_BINARY_DIR} + ${CMAKE_SOURCE_DIR}/doc ${CMAKE_BINARY_DIR}/sphinx) diff --git a/doc/build_source.md b/doc/build_source.md deleted file mode 100644 index 9047e29..0000000 --- a/doc/build_source.md +++ /dev/null @@ -1,72 +0,0 @@ -## Build the project from source - -### Prerequisites - -- C++ compiler (choose either one below) - - gcc ≥ 14.3. - - clang ≥ 18 -- oneTBB -- **(Optional)** ROOT ≥ 6.32 - -- (mini) Conda. See [this instruction](install_conda.md) to install miniconda quickly. - -> [!CAUTION] -> DO NOT USE Conda to install ROOT. Use latest compiler to install ROOT from the source. - -### Installation - -#### Step 1: Clone the latest version - -```bash -git clone -b [latest version] https://github.com/YanzhaoW/srs-daq.git -cd srs-daq -git submodule update --init -``` - -#### Step 2: Activate the Conda environment - -```bash -conda env create -f environment.yml -conda activate srs -``` - -#### Step 3: Build the project - -**Make sure conda environment `srs` is activated.** - -```bash -cmake --workflow --preset default -``` - -or - -```bash -cmake --preset default -DCMAKE_INSTALL_PREFIX=[/usr/local] [optional settings] -cmake --build ./build --target install -- -j[nproc] -``` - -Following CMake preset optional settings are available: - -- `-DUSE_ROOT=` - - `OFF` or `FALSE` (default). The program would only compile with ROOT if ROOT exists. - - `ON` or `TRUE`. CMake configuration will fail if `ROOT` is not found. -- `-DNO_ROOT=` - - `OFF` or `FALSE` (default). Same as `-DUSE_ROOT=OFF`. - - `ON` or `TRUE`. The program does NOT compiler with ROOT even if ROOT exists. - -For example, to disable the ROOT dependency, run the `cmake --preset` with: - -```bash -cmake --preset default . -DNO_ROOT=TRUE -``` - -### Update to the latest version - -srs-daq is under a continuous development. To update to the latest version, run the following git commands: - -```bash -git fetch origin -git checkout latest -git submodule update --init -``` -After this, build the project again from [Step 3](#step-3-build-the-project). diff --git a/doc/build_source.rst b/doc/build_source.rst new file mode 100644 index 0000000..48911bd --- /dev/null +++ b/doc/build_source.rst @@ -0,0 +1,83 @@ +################################### +Build the project from source +################################### + +Prerequisites +############################## + +- C++ compiler (choose either one below) + - gcc ≥ 14.3. + - clang ≥ 18 +- oneTBB +- **(Optional)** ROOT ≥ 6.32 + +- (mini) Conda. See [this instruction](install_conda.md) to install miniconda quickly. + +.. warning:: + DO NOT USE Conda to install ROOT. Use latest compiler to install ROOT from the source. + +Installation +############################## + +Step 1: Clone the latest version +------------------------------------ + +.. code-block:: bash + + git clone -b [latest version] https://github.com/YanzhaoW/srs-daq.git + cd srs-daq + git submodule update --init + +Step 2: Activate the Conda environment +------------------------------------------- + +.. code-block:: bash + + conda env create -f environment.yml + conda activate srs + +Step 3: Build the project +------------------------------------ + +**Make sure conda environment `srs` is activated.** + +.. code-block:: bash + + cmake --workflow --preset default + +or + +.. code-block:: bash + + cmake --preset default -DCMAKE_INSTALL_PREFIX=[/usr/local] [optional settings] + cmake --build ./build --target install -- -j[nproc] + + +Following CMake preset optional settings are available: + +- `-DUSE_ROOT=` + - `OFF` or `FALSE` (default). The program would only compile with ROOT if ROOT exists. + - `ON` or `TRUE`. CMake configuration will fail if `ROOT` is not found. +- `-DNO_ROOT=` + - `OFF` or `FALSE` (default). Same as `-DUSE_ROOT=OFF`. + - `ON` or `TRUE`. The program does NOT compiler with ROOT even if ROOT exists. + +For example, to disable the ROOT dependency, run the `cmake --preset` with: + +.. code-block:: bash + + cmake --preset default . -DNO_ROOT=TRUE + + +Update to the latest version +--------------------------------- + +srs-daq is under a continuous development. To update to the latest version, run the following git commands: + +.. code-block:: bash + + git fetch origin + git checkout latest + git submodule update --init + +After this, build the project again from Step 3. diff --git a/doc/conf.py.in b/doc/conf.py.in new file mode 100644 index 0000000..c13b823 --- /dev/null +++ b/doc/conf.py.in @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = '@CMAKE_PROJECT_NAME@' +copyright = '2024, Yanzhao Wang' +author = 'Yanzhao Wang' +release = '@CMAKE_PROJECT_VERSION@' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["myst_parser"] + +templates_path = ['_templates'] +exclude_patterns = [] + +source_suffix = ['.rst', '.md', '.cpp'] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = [] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..85dcae4 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,11 @@ +.. include:: ../README.rst + +.. toctree:: + :maxdepth: 2 + :hidden: + + introduction + build_source + install_conda + library_usage + Source Code @ GitHub diff --git a/doc/install_conda.md b/doc/install_conda.md deleted file mode 100644 index a835e87..0000000 --- a/doc/install_conda.md +++ /dev/null @@ -1,45 +0,0 @@ -## Installation of required software using Conda - -Conda is a package manager for easily installing required libraries and software. - -### Install mini-conda - -Go to [mini-conda quick command line install](https://docs.anaconda.com/free/miniconda/#quick-command-line-install) and choose the method for your operating system. For example, Linux users can do - -```bash -mkdir -p ~/miniconda3 -wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh -bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 -rm ~/miniconda3/miniconda.sh -``` - -After this, for bash user: - -```bash -~/miniconda3/bin/conda init bash -``` - -and for zsh user: - -```bash -~/miniconda3/bin/conda init zsh -``` -Once all is done successfully, log out and restart your shell. - -## Troubleshooting - -### libarchive error - -#### Error message - -```text -Error while loading conda entry point: conda-libmamba-solver (libarchive.so.20: cannot open shared object file: No such file or directory) -``` - -This could happen if you are in an old operating system. - -#### Solution - -```bash -conda install --solver=classic conda-forge::conda-libmamba-solver conda-forge::libmamba conda-forge::libmambapy conda-forge::libarchive -``` diff --git a/doc/install_conda.rst b/doc/install_conda.rst new file mode 100644 index 0000000..1573c1d --- /dev/null +++ b/doc/install_conda.rst @@ -0,0 +1,54 @@ +################################################# +Installation of required software using Conda +################################################# + +Conda is a package manager for easily installing required libraries and software. + +Install mini-conda +############################################ + +Go to `mini-conda quick command line install `_ and choose the method for your operating system. For example, Linux users can do + +.. code-block:: bash + + mkdir -p ~/miniconda3 + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh + bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + rm ~/miniconda3/miniconda.sh + +After this, for bash user: + +.. code-block:: bash + + ~/miniconda3/bin/conda init bash + + +and for zsh user: + +.. code-block:: bash + + ~/miniconda3/bin/conda init zsh + +Once all is done successfully, log out and restart your shell. + +Troubleshooting +########################################### + +libarchive error +-------------------------------------- + +Error message +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: text + + Error while loading conda entry point: conda-libmamba-solver (libarchive.so.20: cannot open shared object file: No such file or directory) + +This could happen if you are in an old operating system. + +Solution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: text + + conda install --solver=classic conda-forge::conda-libmamba-solver conda-forge::libmamba conda-forge::libmambapy conda-forge::libarchive diff --git a/doc/introduction.rst b/doc/introduction.rst new file mode 100644 index 0000000..f00621f --- /dev/null +++ b/doc/introduction.rst @@ -0,0 +1,3 @@ +Introduction +=================== + diff --git a/doc/library_usage.md b/doc/library_usage.md deleted file mode 100644 index b0d8bb3..0000000 --- a/doc/library_usage.md +++ /dev/null @@ -1,38 +0,0 @@ -## Usage of SRS library - -Link the SRS library with CMake `find_package`: - -```cmake -find_package(srs REQUIRED) - -add_executable(main PRIVATE srs::srs) -``` - -Please make sure add the directory path of the program folder `srs-install` to `CMAKE_PREFIX_PATH`: - -```bash -cmake -DCMAKE_PREFIX_PATH=[...]/srs-install .. -``` - -### Convert the proto binary data to data structure - -The full example can be found in this [script](../examples/readUDP/main.cpp). - -The class `srs::ProtoMsgReader` converts the proto binary data to the data structure. The memory allocation is done in the constructor and no allocation happens during the conversion. If multiple conversions needs to be done, the object should be kept alive to reduce the memory allocation. - -Minimum example: - -```c++ -#include - -auto main() -> int -{ - auto msg_reader = srs::ProtoMsgReader{}; - - std::string_view proto_binary = get_proto_msg(); - - const auto& data_struct = msg_reader.convert(proto_binary); - - return 0; -} -``` diff --git a/doc/library_usage.rst b/doc/library_usage.rst new file mode 100644 index 0000000..4d5e169 --- /dev/null +++ b/doc/library_usage.rst @@ -0,0 +1,41 @@ +################################################ +Usage of SRS library +################################################ + +Link the SRS library with CMake `find_package`: + +.. code-block:: cmake + + find_package(srs REQUIRED) + add_executable(main PRIVATE srs::srs) + +Please make sure add the directory path of the program folder `srs-install` to `CMAKE_PREFIX_PATH`: + +.. code-block:: bash + + cmake -DCMAKE_PREFIX_PATH=[...]/srs-install .. + +Convert the proto binary data to data structure +#################################################### + +The full example can be found in this :ref:`script<../examples/readUDP/main.cpp>` . + +The class `srs::ProtoMsgReader` converts the proto binary data to the data structure. The memory allocation is done in the constructor and no allocation happens during the conversion. If multiple conversions needs to be done, the object should be kept alive to reduce the memory allocation. + +Minimum example: + +.. code-block:: cpp + :linenos: + + #include + + auto main() -> int + { + auto msg_reader = srs::ProtoMsgReader{}; + + std::string_view proto_binary = get_proto_msg(); + + const auto& data_struct = msg_reader.convert(proto_binary); + + return 0; + }