... | ... | @@ -8,17 +8,17 @@ Code should be formatted consistently. Code should be mechanically formatted. |
|
|
This helps other readers jump into a code base without having to sort through various types of brace placement and indentation, it removes one level of noise.
|
|
|
|
|
|
## C/C++ Formatting ##
|
|
|
Formatting is done via clang-format. The canonical definition of the style is found in the advligorts source code in the .clang-format file.
|
|
|
Formatting is done via [clang-format](https://clang.llvm.org/docs/ClangFormat.html). The canonical definition of the style is found in the advligorts source code in the [.clang-format](https://git.ligo.org/cds/advligorts/-/raw/master/.clang-format) file.
|
|
|
|
|
|
Note: not all of the CDS code has been/can be reformatted at this time. Some code with complex #ifdefs will need to be checked after reformatting and will require better test suites.
|
|
|
|
|
|
_Note:_ This format definition comes out of work with LDAS in the framecpp & nds code bases, and is an effort to become more consistent across the LIGO lab.
|
|
|
|
|
|
## Python Formatting ##
|
|
|
Python code should be formatted according to PEP 8.
|
|
|
Python code should be formatted according to [PEP 8](https://www.python.org/dev/peps/pep-0008/).
|
|
|
|
|
|
## Go Formatting ##
|
|
|
Go code should be formatted according to go fmt.
|
|
|
Go code should be formatted according to [go fmt](https://go.dev/blog/gofmt).
|
|
|
|
|
|
_Note:_ Go prefers tabs to spaces. That is ok, that is the idiomatic way for this language.
|
|
|
|
... | ... | @@ -36,7 +36,7 @@ Some notes: |
|
|
|
|
|
# Build Systems #
|
|
|
# C/C++ use CMake by default
|
|
|
CMake is the current industry standard. This should be the preferred system to build C/C++ code. It provides the ability to build across Windows, OSX, Linux systems.
|
|
|
[CMake](https://cmake.org/) is the current industry standard. This should be the preferred system to build C/C++ code. It provides the ability to build across Windows, OSX, Linux systems.
|
|
|
|
|
|
Newer/Modern CMake idioms should be used. This is defined with target based operations instead of variable based declarations.
|
|
|
|
... | ... | @@ -45,9 +45,10 @@ There are places such as building Linux kernel modules or the RT models that CMa |
|
|
# Version Control #
|
|
|
Put code in version control.
|
|
|
|
|
|
Prefer git and hosting on git.ligo.org.
|
|
|
Prefer git and hosting on [git.ligo.org](https://git.ligo.org).
|
|
|
|
|
|
For development use topic and issue branches.
|
|
|
|
|
|
Do not be afraid to commit WIP (work in progress) code to your branches. It is better to save items and make sure we have a history than to have things perfect.
|
|
|
|
|
|
Keep the master/head/main branch clean and working.
|
... | ... | @@ -60,7 +61,7 @@ Reviews force us to write better code as we know that someone else will look at |
|
|
By using a git workflow with merge requests we can formalize a review.
|
|
|
|
|
|
# Software Licensing #
|
|
|
The lab policy on software licensing is at https://dcc.ligo.org/M1500244/.
|
|
|
The lab policy on software licensing is at [M1500244](https://dcc.ligo.org/M1500244/).
|
|
|
|
|
|
# Packaging CDS Software #
|
|
|
|
... | ... | @@ -128,7 +129,7 @@ Inputs must be converted to internal units before any other processing is done o |
|
|
|
|
|
Conversions between two units should be handled by a single function or macro (allowing for overloading for different types). A- hoc conversions must be avoided.
|
|
|
|
|
|
In C++ “Strong” types can be used to represent types and prevent unintentional/incorrect conversion of types.
|
|
|
In C++ "Strong" types can be used to represent types and prevent unintentional/incorrect conversion of types.
|
|
|
|
|
|
# Architecture #
|
|
|
## Architect code to be tested ##
|
... | ... | @@ -170,9 +171,9 @@ In Python functions can be extended to take clocks, sockets, … with default pa |
|
|
CMake integrates testing via the ctest system. Any tests integrated here can be run with the build system.
|
|
|
|
|
|
### C/C++ Catch/Boost Test ###
|
|
|
Catch is a simple/lightweight unit testing framework. It is used in parts of the daqd and other software.
|
|
|
[Catch](https://github.com/catchorg/Catch2) is a simple/lightweight unit testing framework. It is used in parts of the daqd and other software.
|
|
|
|
|
|
Boost::Testing is used by LDASTools
|
|
|
[Boost::Test](https://www.boost.org/doc/libs/1_77_0/libs/test/doc/html/index.html) is used by LDASTools
|
|
|
|
|
|
### Python ###
|
|
|
Use the python testing framework
|
... | ... | @@ -180,7 +181,7 @@ Use the python testing framework |
|
|
### Go ###
|
|
|
Go has a build in test/benchmark (and soon fuzzing) framework. It should be used for unit tests.
|
|
|
|
|
|
In addition GoConvey is a useful tool/runner for reloading and running your tests as you save files.
|
|
|
In addition [GoConvey](https://github.com/smartystreets/goconvey) is a useful tool/runner for reloading and running your tests as you save files.
|
|
|
|
|
|
# API Design #
|
|
|
Design APIs to keep objects in known good states.
|
... | ... | @@ -208,10 +209,10 @@ If we are creating a base library that will be consumed by outside applications |
|
|
# Interfacing with multiple languages #
|
|
|
|
|
|
## SWIG ##
|
|
|
Swig is useful when interfacing C/C++ code with many different languages.
|
|
|
[Swig](https://www.swig.org/) is useful when interfacing C/C++ code with many different languages.
|
|
|
|
|
|
## PyBind11 ##
|
|
|
When a C++ library need only be exported to Python (and not to Java/Matlab/…) PyBind11 may be a better choice as it provides good integration and keeps the bindings in C++ (instead of the including another language [the SWIG system] into the mix).
|
|
|
When a C++ library need only be exported to Python (and not to Java/Matlab/…) [PyBind11](https://pybind11.readthedocs.io/en/stable/) may be a better choice as it provides good integration and keeps the bindings in C++ (instead of the including another language [the SWIG system] into the mix).
|
|
|
|
|
|
## ROOT ##
|
|
|
Some older applications use a C++ interpreter built into ROOT to expose C++ classes to Python. **Future use of ROOT is discouraged**.
|
... | ... | |