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.
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
...
@@ -62,32 +62,7 @@ Please file the bug reports and feature requests in the issue tracker
## Building
## Building
To build the shared library please read the following.
For a full reference on building please refer to the [documentation](doc/build.md). This is a small summary of the standard building steps.
### 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
This should replace the call to cmake in the previous section.
This should replace the call to cmake in the previous section.
### Build Flags
### Running tests and benchmark
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:
```bash
Please refer to the full [documentation](doc/build.md).
./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
```
## Installing
## 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.
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
### System Dependencies
...
@@ -231,47 +126,6 @@ sudo make install
...
@@ -231,47 +126,6 @@ sudo make install
The shared library will be installed to /usr/local/lib on Debian/Ubuntu systems.
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
...
@@ -9,7 +9,7 @@ The project has two types of dependencies, those required by the toolchain, and
* libpqxx - Modern C++ Postgresql library (Submodule)
* libpqxx - Modern C++ Postgresql library (Submodule)
* spdlog - Logging system (Submodule)
* spdlog - Logging system (Submodule)
* Catch2 - Unit test subsystem (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)