# How to Develop and Use Libcaosdb ## Dependencies * See [DEPENDENCIES.md](Dependencies.md) ## Build We use [cmake](https://cmake.org) 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](https://visualstudio.microsoft.com/de/vs/features/cplusplus/) as compiler. We use [cmake](https://cmake.org/download/) 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](https://google.github.io/googletest/) for unit testing. ### Coverage We use [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) and [lcov](https://github.com/linux-test-project/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](https://google.github.io/styleguide/cppguide.html#Naming). ## 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)