Eclipse Zenoh

The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.

Zenoh (pronounce /zeno/) unifies data in motion, data at rest and computations. It carefully blends traditional pub/sub with geo-distributed storages, queries and computations, while retaining a level of time and space efficiency that is well beyond any of the mainstream stacks.

Check the website zenoh.io and the roadmap for more detailed information.

C++ API

The Zenoh C++ API are headers only C++ bindings for [zenoh-c] and [zenoh-pico] libraries.

C++ bindings are still under active development so the Zenoh team will highly appreciate any help in testing them on various platforms, system architecture, etc. and to report any issue you might encounter. This will help in greatly improving its maturity and robustness.

Requirements

The only hard requirement for building the library is a C++17-compliant compiler. Using the library requires either [zenoh-c] or [zenoh-pico] to be installed.

---

How to build and install it

To install [zenoh-cpp] do the following steps:

1. Clone the sources.

   git clone https://github.com/eclipse-zenoh/zenoh-cpp.git

2. Build and install.

   By default it is expected that you have [zenoh-c] installed. If you want to install for [zenoh-pico] backend or for both (or to not specify any backend), please set ZENOHCXX_ZENOHC or ZENOHCXX_ZENOHPICO Cmake variables toON or OFF accordingly. Notice that at least one of the backends is required for using the library and/or building tests and examples.

   Use option CMAKE_INSTALL_PREFIX for specifying installation location. Without this parameter installation is performed to default system location /usr/local which requires root privileges.

   mkdir build && cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=~/.local # to configure only for zenoh-c backend
   cmake .. -DZENOHCXX_ZENOHC=OFF -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to configure  only for zenoh-pico backend
   cmake .. -DZENOHCXX_ZENOHC=OFF -DZENOHCXX_ZENOHPICO=OFF  -DCMAKE_INSTALL_PREFIX=~/.local # to configure for none of the backends
   cmake .. -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to configure for both backends
   cmake --install .

Building and running tests

By default it is expected that you have [zenoh-c] installed. If you want to build and run tests for [zenoh-pico] backend or for both, please set ZENOHCXX_ZENOHC or ZENOHCXX_ZENOHPICO Cmake variables toON or OFF accordingly.

To build tests run:

mkdir build && cd build
cmake ..  -DCMAKE_INSTALL_PREFIX=~/.local # to build tests only for zenoh-c backend
cmake .. -DZENOHCXX_ZENOHC=OFF -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to build tests only for zenoh-pico backend
cmake .. -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to build tests for both backends
cmake --build . --target tests
ctest

Notice that the output of cmake ../zenoh-cpp shows where [zenoh-c] and/or [zenoh-pico] the dependencies were found.

Building the Examples

Examples are splitted into two subdirectories. Subdirectory universal contains [zenoh-cpp] examples buildable with both [zenoh-c] and [zenoh-pico] backends. The zenohc subdirectory contains examples with zenoh-c specific functionality.

By default it is expected that you have [zenoh-c] installed. If you want to build examples for [zenoh-pico] backend or for both, please set ZENOHCXX_ZENOHC or ZENOHCXX_ZENOHPICO Cmake variables toON or OFF accordingly.

To build examples run:

cmake ..  -DCMAKE_INSTALL_PREFIX=~/.local # to build examples only for zenoh-c backend
cmake .. -DZENOHCXX_ZENOHC=OFF -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to build examples only for zenoh-pico backend
cmake .. -DZENOHCXX_ZENOHPICO=ON  -DCMAKE_INSTALL_PREFIX=~/.local # to build examples for both backends
cmake --build . --target examples

Examples are placed into build/examples/zenohc and build/examples/zenohpico directories.

Running the examples

See information about running examples here.

Examples of linking [zenoh-cpp] to an external project can be found here.

Library usage

Below are the steps to include [zenoh-cpp] into CMake project. See also examples/simple directory for short examples of CMakeLists.txt.

• include [zenoh-c] or [zenoh-pico] into your CMake project before dependency on [zenoh-cpp] itself. This is important as the library targets you need (zenohcxx::zenohpico, zenohcxx::zenohc::lib) are defined only if their backend library targets (zenohpico::lib and/or zenohc::lib are defined)

• include [zenoh-cpp] using [find_package] CMake function:

  find_package(zenohc) #if using zenoh-c backend
  find_package(zenohpico) #if using zenoh-pico backend
  find_package(zenohcxx)

• add dependency on zenoh-cpp to your project:

  target_link_libraries(yourproject PUBLIC zenohcxx::zenohc) #if using zenoh-c backend
  target_link_libraries(yourproject PUBLIC zenohcxx::zenohpico) #if using zenoh-pico backend

• include the [zenoh.hxx] header. All zenoh functionality is available under the namespace zenoh:

  #include "zenoh.hxx"
  using namespace zenoh;

Documentation

The documentation is on [zenoh-cpp.readthedocs.io]. Instruction how to build documentation locally is at [docs/README.md].

rust-lang zenoh zenoh-c zenoh-cpp zenoh-pico zenoh.hxx add_subdirectory find_package FetchContent zenoh-cpp.readthedocs.io docs/README.md