README_SETUP.md

How to Develop and Use Libcaosdb

Dependencies

• See DEPENDENCIES.md

Build

We use cmake as build tool.

0. clone/update the subrepo git submodule update --init proto
1. mkdir build && cd build
2. conan install .. -s "compiler.libcxx=libstdc++11"
3. cmake -B . ..
4. cmake --build .

You may also want to install libcaosdb system-wide to CMAKE_INSTALL_PREFIX/lib by

5. cmake --install .

The default install prefix is ~/.local. It can be set by adding -DCMAKE_INSTALL_PREFIX=/path/to/install/prefix to the first cmake command (3.).

How to build on MacOS

Instead of the above conan command (2.) use

2. conan install .. -s "cppstd=11"

and continue as you would when building on a Linux system. You may have to add build/lib/ (or, alternatively after installation, CMAKE_INSTALL_PREFIX/lib) to your DYLD_LIBRARY_PATH environmental variable.

How to build on Windows

We use Visual Studio 2019 as compiler. We use cmake as build tool.

0. clone/update the subrepo git submodule update --init proto
1. mkdir build
2. cd build
3. conan install .. -g visual_studio -s arch=x86_64 -s build_type=Release -s compiler.toolset=v142 -s compiler.version=16 -s compiler.runtime=MD --build=missing --update
4. cmake -B . ..
5. open libcaosdb.sln with Visual Studio, change the buildtype to Release and build the project. (You can open Tools/Command Line/Developer Command Prompt and execute msbuild libcaosdb.sln /property:Configuration=Release)

Creating a local Conan package

Building and installing libcaosdb with Conan is just a single command:
conan create . -s "compiler.libcxx=libstdc++11"

For MacOS, you probably should adjust the option as mentioned above.

Troubleshooting

conan install Fails Due to Missing Prebuilts

When conan install fails during the installation of the dependencies because a precompiled package is not available for your specific settings, try adding the --build=missing option: conan install .. [ other options ] --build=missing. This should download and compile the sources of the dependencies.

Unit Tests

Build

For the tests there is a slightly different setup required (with option -D CMAKE_BUILD_TYPE=Debug)

1. mkdir build && cd build/
2. conan install .. -s "compiler.libcxx=libstdc++11"
3. cmake -B . -D CMAKE_BUILD_TYPE=Debug ..
4. cmake --build .

Run

In the build directory, run ctest

Framework

We use GoogleTest for unit testing.

Coverage

We use gcov and lcov for generating test coverage reports.

In the build directory, generate the coverage report by running cmake --build . --target unit_test_coverage.

Note that this special target will run the tests again. Thus it is not necessary to run ctest prior to this target.

The coverage report can be viewed in a browser by opening <build_directory>/unit_test_coverage/index.html.

Code Formatting

• install clang-format on your system.
• clang-format -i --verbose $(find test/ src/ include/ -type f -iname "*.cpp" -o -iname "*.h" -o -iname "*.h.in")

Naming Convention

Please adhere to Google's C++ naming conventions.

Client Configuration

You can use a json file for the configuration of the client. See test/test_data/test_caosdb_client.json for an example. You may use caosdb-client-configuration-schema.json to validate your schema.

The client will load the configuration file from the first existing file in the following locations (precedence from highest to lowest):

1. A file specified by the environment variable $CAOSDB_CLIENT_CONFIGURATION.
2. $PWD/caosdb_client.json
3. $PWD/caosdb-client.json
4. $PWD/.caosdb_client.json
5. $PWD/.caosdb-client.json
6. $HOME/caosdb_client.json
7. $HOME/caosdb-client.json
8. $HOME/.caosdb_client.json
9. $HOME/.caosdb-client.json

Documentation

In the build directory, run

• cmake --build . --target doc-doxygen (generate Doxygen)
• cmake --build . --target doc-sphinx (generate Sphinx)