Skip to content
Snippets Groups Projects
Verified Commit cfb253f1 authored by Daniel Hornung's avatar Daniel Hornung
Browse files

DOC: Added note about linking to Conan libraries. Also .md -> .rst

parent 2bb0a738
No related branches found
No related tags found
No related merge requests found
Pipeline #21601 failed
Stage: info
Stage: setup
Stage: test
Stage: deploy
Hide whitespace changes
Inline Side-by-side
doc/CMakeLists.txt
+ 2
− 2
View file @ cfb253f1
......@@ -84,7 +84,7 @@ if (DOXYGEN_FOUND)
sphinx_out
DEPENDS doc-doxygen
Examples.rst
Install_develop.md
Install_develop.rst
FEATURES.md
CHANGELOG.md
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
......@@ -94,7 +94,7 @@ if (DOXYGEN_FOUND)
# Copying files is necessary: https://stackoverflow.com/a/45808534/232888
file(COPY
Examples.rst
Install_develop.md
Install_develop.rst
DEPENDENCIES.md
CHANGELOG.md
FEATURES.md
......
doc/Install_develop.md deleted 100644 → 0
+ 0
− 177
View file @ 2bb0a738
# How to use and develop libcaosdb
## Dependencies
* See the [dependencies](DEPENDENCIES.md) file.
## Build
### Building with `make` ##
Make sure that the dependencies (see above) are fulfilled. On systems which have `make` installed,
type this in your command line terminal:
```console
make conan
```
### Manual build ##
We use [cmake](https://cmake.org) as build tool, with Conan as package manager.
The compiler must support the C++17 standard.
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.).
If you want to build or install libcaosdb without the use of Conan, feel free to rewrite the
CMakeLists.txt as needed. The CaosDB project is open to merge requests which support multiple ways
of installation.
### How to build on MacOS
If you use apple-clang as the compiler: Instead of the above conan command (2.) use
2. `conan install .. -s "compiler.cppstd=17"`
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.
#### Problems and solutions ####
- Make sure that your Conan version supports your XCode version. A typical symptom of version
mismatch is for example conan complaining about incompatible `compiler.version` settings. You may
need to rerun any conan and cmake commands (and delete cache files first) after compiler updates.
### 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`)
#### Known problems ####
- Linking dynamic libraries currently fails on Windows. So probably other CaosDB libraries which
make use of libcaosdb also will not build. This is a known bug and we hope to
fix this in the next release. See
[#34](https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/issues/34)
### 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.
#### cmake fails when using the debug flag
Depending on the clang version it might be necessary to additionally use the following flag:
`-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
#### conan uses outdated cppstd during install
If you experience compiler errors during a `conan install` process due
to, e.g., `std::string_view` being unavailable, try specifying the cpp
standard manually by `conan install .. [other options] -s
"compiler.cppstd=17"`.
## 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.
Typically, you will need to provide the path to your SSL certificate.
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`
## Develop ##
### 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 .. ` (with gcc, append ` -s "compiler.libcxx=libstdc++11"`, with apple-clang,
append ` -s compiler.cppstd=17`)
3. `cmake -B . -D CMAKE_BUILD_TYPE=Debug ..`
* If your clang-format version is too old, formatting, linting etc. can be skipped:
`cmake -B . -D CMAKE_BUILD_TYPE=Debug -D SKIP_LINTING=ON ..`
* Depending on the clang version it might be necessary to also add
`-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
5. `cmake --build .`
#### Run ####
In the build directory, run `ctest`
#### Framework ####
We use [GoogleTest](https://google.github.io/googletest/) for unit testing.
#### Test 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 conventions ###
Please adhere to [Google's C++ naming conventions](https://google.github.io/styleguide/cppguide.html#Naming).
### Documentation ###
To build the documentation, run in the build directory
* `cmake --build . --target doc-doxygen` (generate Doxygen)
* `cmake --build . --target doc-sphinx` (generate Sphinx)
doc/Install_develop.rst 0 → 100644
+ 222
− 0
View file @ cfb253f1
How to use and develop libcaosdb
================================
Dependencies
------------
- See the `dependencies <DEPENDENCIES.md>`__ file.
Build
-----
Building with ``make``
~~~~~~~~~~~~~~~~~~~~~~
Make sure that the dependencies (see above) are fulfilled. On systems
which have ``make`` installed, type this in your command line terminal:
.. code:: console
make conan
Manual build
~~~~~~~~~~~~
We use `cmake <https://cmake.org>`__ as build tool, with Conan as
package manager. The compiler must support the C++17 standard.
1. clone/update the subrepo ``git submodule update --init proto``
2. ``mkdir build && cd build``
3. ``conan install .. -s "compiler.libcxx=libstdc++11"``
4. ``cmake -B . ..``
5. ``cmake --build .``
You may also want to install libcaosdb system-wide to
``CMAKE_INSTALL_PREFIX/lib`` by
1. ``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.).
.. Note::
The C++ CaosDB library links against other libraries which are installed by Conan. So if you want
to switch to newer versions of those libraries (possible reasons may be security releases or bug
fixes), it is not sufficient to update your system libraries, but you have to update your Conan
content and then rebuild libcaosdb.
If you want to build or install libcaosdb without the use of Conan, feel
free to rewrite the CMakeLists.txt as needed. The CaosDB project is open
to merge requests which support multiple ways of installation.
How to build on MacOS
~~~~~~~~~~~~~~~~~~~~~
If you use apple-clang as the compiler: Instead of the above conan
command (2.) use
1. ``conan install .. -s "compiler.cppstd=17"``
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.
Problems and solutions
^^^^^^^^^^^^^^^^^^^^^^
- Make sure that your Conan version supports your XCode version. A
typical symptom of version mismatch is for example conan complaining
about incompatible ``compiler.version`` settings. You may need to
rerun any conan and cmake commands (and delete cache files first)
after compiler updates.
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.
1. clone/update the subrepo ``git submodule update --init proto``
2. ``mkdir build``
3. ``cd build``
4. ``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``
5. ``cmake -B . ..``
6. 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``)
Known problems
^^^^^^^^^^^^^^
- Linking dynamic libraries currently fails on Windows. So probably
other CaosDB libraries which make use of libcaosdb also will not
build. This is a known bug and we hope to fix this in the next
release. See
`#34 <https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/issues/34>`__
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.
cmake fails when using the debug flag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Depending on the clang version it might be necessary to additionally use
the following flag: ``-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"``
conan uses outdated cppstd during install
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you experience compiler errors during a ``conan install`` process due
to, e.g., ``std::string_view`` being unavailable, try specifying the cpp
standard manually by
``conan install .. [other options] -s "compiler.cppstd=17"``.
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.
Typically, you will need to provide the path to your SSL certificate.
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``
Develop
-------
Unit tests
~~~~~~~~~~
.. _build-1:
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 ..`` (with gcc, append
``-s "compiler.libcxx=libstdc++11"``, with apple-clang, append
``-s compiler.cppstd=17``)
3. ``cmake -B . -D CMAKE_BUILD_TYPE=Debug ..``
- If your clang-format version is too old, formatting, linting etc. can
be skipped:
``cmake -B . -D CMAKE_BUILD_TYPE=Debug -D SKIP_LINTING=ON ..``
- Depending on the clang version it may be necessary to also add
``-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"``
4. ``cmake --build .``
Run
^^^
In the build directory, run ``ctest``
Framework
^^^^^^^^^
We use `GoogleTest <https://google.github.io/googletest/>`__ for unit
testing.
Test 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 conventions
~~~~~~~~~~~~~~~~~~
Please adhere to `Google’s C++ naming
conventions <https://google.github.io/styleguide/cppguide.html#Naming>`__.
Documentation
~~~~~~~~~~~~~
To build the documentation, run in the build directory
- ``cmake --build . --target doc-doxygen`` (generate Doxygen)
- ``cmake --build . --target doc-sphinx`` (generate Sphinx)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment