HDB++ backend library for the TimescaleDb extenstion to Postgresql. This library is loaded by libhdbpp to archive events from a Tango Controls system. Currently in a pre v1 release phase.
HDB++ backend library for the TimescaleDb extenstion to Postgresql. This library is used by events subscribers to archive events from a Tango Controls system.
The library requires a correctly configured [TimescaleDb](https://www.timescale.com/) installation.
...
...
@@ -62,32 +62,7 @@ Please file the bug reports and feature requests in the issue tracker
## Building
To build the shared library please read the following.
### Dependencies
The project has two types of dependencies, those required by the toolchain, and those to do the actual build. Other dependencies are integrated directly into the project as submodules. The following thirdparty modules exists:
* libpqxx - Modern C++ Postgresql library (submodule)
* spdlog - Logging system (submodule)
* Catch2 - Unit test subsystem (submodule)
* libhdbpp - Configuration can now fetch [original](https://github.com/tango-controls-hdbpp/libhdbpp) to aid development. See build flags.
#### Toolchain Dependencies
If wishing to build the project, ensure the following dependencies are met:
* CMake 3.11 or higher (for FetchContent)
* C++14 compatible compiler (code base is using c++14)
#### Build Dependencies
Ensure the development version of the dependencies are installed. These are as follows:
* Tango Controls 9 or higher development headers and libraries
* omniORB release 4 or higher development headers and libraries
* libzmq3-dev or libzmq5-dev
* libpq-dev - Postgres C development library
For a full reference on building please refer to the [documentation](doc/build.md). This is a small summary of the standard building steps.
This should replace the call to cmake in the previous section.
### Build Flags
The following build flags are available
#### Standard CMake Flags
The following is a list of common useful CMake flags and their use:
| Flag | Setting | Description |
|------|-----|-----|
| CMAKE_INSTALL_PREFIX | PATH | Standard CMake flag to modify the install prefix. |
| CMAKE_INCLUDE_PATH | PATH[S] | Standard CMake flag to add include paths to the search path. |
| CMAKE_LIBRARY_PATH | PATH[S] | Standard CMake flag to add paths to the library search path |
| CMAKE_BUILD_TYPE | Debug/Release | Build type to produce |
#### Project Flags
| Flag | Setting | Default | Description |
|------|-----|-----|-----|
| BUILD_UNIT_TESTS | ON/OFF | OFF | Build unit tests |
| BUILD_BENCHMARK_TESTS | ON/OFF | OFF | Build benchmark tests (Forces a Release build) |
| ENABLE_CLANG | ON/OFF | OFF | Clang code static analysis, readability, and cppcore guideline enforcement |
| FETCH_LIBHDBPP | ON/OFF | OFF | Enable to have the build fetch and use a local version of libhdbpp |
| FETCH_LIBHDBPP_TAG | | master | When FETCH_LIBHDBPP is enabled, this is the git tag to fetch |
### Running Tests
#### Unit Tests
The project has extensive unit tests to ensure its functioning as expect. Build the project with testing enabled:
```bash
mkdir-p build
cd build
cmake -DBUILD_UNIT_TESTS=ON ..
make
```
To run all unit tests, a postgresql database node is required with the project schema loaded up. There is a default connection string inside test/TestHelpers.hpp:
If you run the hdb timescale docker image associated with this project locally then this will connect automatically. If you wish to use a different database, edit the string in test/TestHelpers.hpp.
To run all tests:
```bash
./test/unit-tests
```
To look at the available tests and tags, should you wish to run a subset of the test suite (for example, you do not have a postgresql node to test against), then tests and be listed:
### Running tests and benchmark
```bash
./bin/unit-tests --list-tests
```
Or:
```bash
./bin/unit-tests --list-tags
```
To see more options for the unit-test command line binary:
```bash
./bin/unit-tests --help
```
#### Benchmark Tests
These are a work in progress to explore future optimisation point. If built, they can be run as follows:
```bash
mkdir-p build
cd build
cmake -DBUILD_BENCHMARK_TESTS=ON ..
make
```
```bash
./benchmark/benchmark-tests
```
Please refer to the full [documentation](doc/build.md).
## Installing
For a full reference on installation please refer to the [documentation](doc/install.md). This is a small summary of the standard installation steps.
All submodules are combined into the final library for ease of deployment. This means just the libhdbpp-timescale.so binary needs deploying to the target system.
### System Dependencies
...
...
@@ -231,47 +126,6 @@ sudo make install
The shared library will be installed to /usr/local/lib on Debian/Ubuntu systems.
## Configuration
### Library Configuration Parameters
Configuration parameters are as follows:
| Parameter | Mandatory | Default | Description |
|------|-----|-----|-----|
| libname | true | None | Must be "libhdb++timescale.so" |
| log_file_name | false | None | When logging to file, this is the path and name of file to use. Ensure the path exists otherwise this is an error conditions. |
The logging_level parameter is case insensitive. Logging levels are as follows:
@@ -9,7 +9,7 @@ The project has two types of dependencies, those required by the toolchain, and
* libpqxx - Modern C++ Postgresql library (Submodule)
* spdlog - Logging system (Submodule)
* Catch2 - Unit test subsystem (Submodule)
* libhdbpp - Part of the hdb++ library loading chain (Modified version of [original](https://github.com/tango-controls-hdbpp/libhdbpp) project. This will be pushed back to the original repository in time)
* libhdbpp - Header from the hdb++ library loading chain (Modified version of [original](https://github.com/tango-controls-hdbpp/libhdbpp) project. This will be pushed back to the original repository in time)
