diff --git a/CHANGELOG.md b/CHANGELOG.md index 2405288016839fff12ad564e61fe5c6e2252d7f9..3dcb5ae0ca9954a577dc52d74e657c313408f489 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed +- Removed public headers as the only needed one is AbstractDB from libhdbpp. - Moved some system documentation to hdbpp-timescale-project (the consolidated project). - Consolidated remaining build/install instructions into README - Modified build system to use fetch libhdbpp and include it when requested. This is an aid to development. -- Supported LIBHDBPP_PROJECT_BUILD flag, that is injected into the build from hdbpp-timescale-project - Made compatible with new libhdbpp (namespace, function and path changes) ### Removed diff --git a/README.md b/README.md index bbcd545dc14cf358943952247eeaa1c8406bcf65..486be0f1f6c82188e40c47788b188ec3eb86d04e 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ - [Configuration Example](#configuration-example) - [License](#license) -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. ### Building Process @@ -124,93 +99,13 @@ cmake -DPostgreSQL_TYPE_INCLUDE_DIR=/usr/include/postgresql/ .. 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: - -``` -user=postgres host=localhost port=5432 dbname=hdb password=password -``` - -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" | -| connect_string | true | None | Postgres connection string, eg user=postgres host=localhost port=5432 dbname=hdb password=password | -| logging_level | false | error | Logging level. See table below | -| log_file | false | false | Enable logging to file | -| log_console | false | false | Enable logging to the console | -| log_syslog | false | false | Enable logging to syslog | -| 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: - -| Level | Description | -|------|-----| -| error | Log only error level events (recommended unless debugging) | -| warning | Log only warning level events | -| info | Log only warning level events | -| debug | Log only warning level events. Good for early install debugging | -| trace | Trace level logging. Excessive level of debug, good for involved debugging | -| disabled | Disable logging subsystem | - -### Configuration Example - -Short example LibConfiguration property value on an EventSubscriber or ConfigManager. You will HAVE to change the various parts to match your system: - -```bash -connect_string=user=hdb-user password=password host=hdb-database port=5432 dbname=hdb -logging_level=debug -log_file=true -log_syslog=false -log_console=false -libname=libhdb++timescale.so -log_file_name=/tmp/hdb/es-name.log -``` - ## License The source code is released under the LGPL3 license and a copy of this license is provided with the code. diff --git a/doc/README.md b/doc/README.md index d4368d95bd5686da5bac2e83a218df8b0af3e554..8e6dfc9d59b2f66cb7b387429a62dc1925cab405 100644 --- a/doc/README.md +++ b/doc/README.md @@ -19,8 +19,8 @@ The overview is in the main project [README](../README.md). ## DB Schema -* [Schema](db-schema-config) guidelines and setup. +* [Schema](db-schema-config.md) guidelines and setup. ## Configuration -* [Configuration](configuration) parameter details. \ No newline at end of file +* [Configuration](configuration.md) parameter details. diff --git a/doc/build.md b/doc/build.md index 3f6496096e3f2c56538eeb00d623189177452306..d072ab650cc163e8492a07e49e2031bb4bc6fed6 100644 --- a/doc/build.md +++ b/doc/build.md @@ -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) ### Toolchain Dependencies @@ -133,4 +133,4 @@ make ```bash ./benchmark/benchmark-tests -``` \ No newline at end of file +``` diff --git a/doc/configuration.md b/doc/configuration.md index a35efb0fc95be6dcd5b7c25bc99b5ef0d2434ad7..f7342ad0060f5057a47a8e7de3a9623310b7531f 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -1,12 +1,14 @@ # Configuration +This is the configuration to use for [event subscribers](https://github.com/tango-controls-hdbpp/hdbpp-es) to use this backend + ## Library Configuration Parameters Configuration parameters are as follows: | Parameter | Mandatory | Default | Description | |------|-----|-----|-----| -| libname | true | None | Must be "libhdb++timescale.so" | +| libname | true | None | Must be "libhdb++timescale.so", this parameter is getting deprecated as the backend is enforced during compilation | | connect_string | true | None | Postgres connection string, eg user=postgres host=localhost port=5432 dbname=hdb password=password | | logging_level | false | error | Logging level. See table below | | log_file | false | false | Enable logging to file | @@ -27,7 +29,7 @@ The logging_level parameter is case insensitive. Logging levels are as follows: ## Configuration Example -Short example LibConfiguration property value on an EventSubscriber or ConfigManager. You will HAVE to change the various parts to match your system: +Short example LibConfiguration property value on an EventSubscriber. You will HAVE to change the various parts to match your system: ``` connect_string=user=hdb-user password=password host=hdb-database port=5432 dbname=hdb @@ -37,4 +39,4 @@ log_syslog=false log_console=false libname=libhdb++timescale.so log_file_name=/tmp/hdb/es-name.log -```` \ No newline at end of file +````