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

This repository provides a C binding based on the main Zenoh implementation written in Rust.

---

How to build it

1. Make sure that Rust is available on your platform. Please check here to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with:

   rustup update
   

2. Clone the source with git:

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

3. Build:

   Good CMake practice is to perform build outside of source directory, leaving source tree untouched. The examples below demonstrates this mode of building. On the other hand VScode by default creates build directory named 'build' inside source tree. In this case build script slightly changes its behavior. See more about it in section 'VScode'.

   By default build configuration is set to Release, it's not necessary to add -DCMAKE_BUILD_TYPE=Release option on configuration step. But if your platform uses multi-config generator by default (this is the case on Windows), you may need to add option --config Release on build step. See more in CMake build-configurations documentation. Option--config Release is skipped in further examples for brewity. It's actually necessary for Visual Studio generators only. For Ninja Multi-Config the build script is able to select Release as the default configuration.

   mkdir -p build && cd build 
   cmake ../zenoh-c
   cmake --build . --config Release
   

   The generator to use is selected with option -G. If Ninja is installed on your system, adding -GNinja to cmake command can greatly speed up the build time:

   cmake ../zenoh-c -GNinja
   cmake --build .
   

   Unstable api and/or shared memory support can be enabled by setting repectively ZENOHC_BUILD_WITH_UNSTABLE_API and ZENOHC_BUILD_WITH_SHARED_MEMORY Cmake flags to true during configuration step.

   cmake -DZENOHC_BUILD_WITH_UNSTABLE_API=true -DZENOHC_BUILD_WITH_SHARED_MEMORY=true ../zenoh-c
   cmake --build . --config Release
   

4. Install:

   To install zenoh-c library into system just build target install. You need root privileges to do it, as the default install location is /usr/local.

   cmake --build . --target install
   

   If you want to install zenoh-c libraries locally, you can set the installation directory with CMAKE_INSTALL_PREFIX

   cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
   cmake --build . --target install
   

   By default only dynamic library is built and installed. Set BUILD_SHARED_LIBS variable to false to build and install static library:

   cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DBUILD_SHARED_LIBS=FALSE
   cmake --build . --target install
   

   The result of installation is the header files in include directory, the library files in lib directory and cmake package configuration files for package zenohc in lib/cmake directory. The library later can be loaded with CMake command find_package(zenohc). Add dependency in CMakeLists.txt on target

   • zenohc::shared for linking dynamic library
   • zenohc::static for linking static library
   • zenohc::lib for linking static or dynamic library depending on boolean variable BUILD_SHARED_LIBS

5. VScode

   When zenoh-c project is opened in VSCode the build directory is set to build inside source tree (this is default behavior of Microsoft CMake Tools). The project build script detects this situation. In this case it places build files in target directory and Cargo.toml file (which is generated from Cargo.toml.in) into the root of source tree, as the rust developers used to and as the rust build tools expects by default. This behavior also can be explicitly enabled by setting ZENOHC_BUILD_IN_SOURCE_TREE variable to TRUE.

Building the Examples

The examples can be built in two ways. One is to select examples as a build target of zenoh-c project (assuming here that the current directory is side-by-side with zenoh-c directory):

cmake ../zenoh-c
cmake --build . --target examples

You may also use --target <example_name> if you wish to only build a specific example.

All build artifacts will be in the target/release/examples directory in this case.

The second way is to directly build examples as a root project:

cmake ../zenoh-c/examples
cmake --build .

Link with zenoh-c installed into default location in the system (with [find_package]):

cmake ../zenoh-c/examples

Link with zenoh-c installed in ~/.local directory:

cmake ../zenoh-c/examples -DCMAKE_INSTALL_PREFIX=~/.local

Running the Examples

See information about running examples here.

Documentation

Zenoh-c API documentation is available on Read the Docs.

It can be built manually by performing the following steps:

cd docs
doxygen
sphinx-build -b html . _build/html

Cross-Compilation

Cross-compilation can be performed using standard cmake approach as described in [cmake-toolchains].

In addition the following project-specific options might need to be set for cross-compilation:

• -DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable": refers to a specific rust toolchain release [rust-channels]
• -DZENOHC_CARGO_FLAGS: several optional flags can be used for compilation. [cargo flags]
• -DZENOHC_CUSTOM_TARGET: specifies a crosscompilation target. Currently rust support several Tier-1, Tier-2 and Tier-3 targets [targets].

Let's put all together in an example: Assuming you want to cross-compile for x86_64-pc-windows-gnu from Ubuntu environment.

1. Install required packages

   • sudo apt-get install -y mingw-w64: cross-compilation toolchain for c/c++.
   • rustup toolchain install x86_64-pc-windows-gnu: cross-compilation toolchain for rust.

2. *(Only if you're using nightly)

   • rustup component add rust-src --toolchain nightly

3. Compile Zenoh-C. Assume that it's in zenoh-c directory. Notice that build in this sample is performed outside of source directory

   export RUSTFLAGS="-Clinker=x86_64-w64-mingw32-gcc -Car=x86_64-w64-mingw32-ar"
   mkdir -p build && cd build
   cmake ../zenoh-c  -DCMAKE_SYSTEM_NAME="Windows" -DCMAKE_C_COMPILER="x86_64-w64-mingw32-gcc" -DCMAKE_CXX_COMPILER="x86_64-w64-mingw32-g++" -DCMAKE_SYSTEM_PROCESSOR="x86_64" -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="x86_64-pc-windows-gnu" -DCMAKE_INSTALL_PREFIX="../x86_64-pc-windows-gnu/stage"
   cmake --build . --target install
   

If all goes right the building files will be located at: /path/to/zenoh-c/target/x86_64-pc-windows-gnu/release and release files will be located at /path/to/zenoh-c/target/x86_64-pc-windows-gnu/release

:warning: WARNING :warning: : Perhaps additional efforts are necessary, that will depend of your environment.

Minimal supported Rust Version

The minimal supported Rust version (MSRV) is 1.75, as specified in Cargo.toml. By default, builds and tests are run using the version defined in rust-toolchain.toml.

The following settings are related to building with a specific Rust version:

• ZENOHC_CARGO_CHANNEL allows selecting a specific toolchain version.
• ZENOHC_MSRV_1_75 should be set to TRUE to lock dependencies to versions that can be built with Rust 1.75.
• ZENOHC_COPY_SOURCE_CARGO_LOCK can be set to FALSE if the source Cargo.lock is incompatible with the selected channel. Automatically set to FALSE if ZENOHC_MSRV_1_75 is selected: the dependencies for Rust 1.75 are known to be incompatible with the source Cargo.lock.

For example to build with some old Rust version starting from Rust 1.75:

cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.75.0" -DZENOHC_MSRV_1_75=TRUE

To build with nigtly Rust:

cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly"

To build on a system with preinstalled Rust of some old version if cargo doesn't allow to select toolchain:

cmake ../zenoh-c -DZENOHC_MSRV_1_75=TRUE

Selecting the cargo command

By default the build invokes the cargo command found in the PATH. It can be overridden with the CARGO_COMMAND environment variable (the same variable as used by colcon-cargo). This is useful when Rust is installed via distribution packages providing versioned commands, such as the Ubuntu cargo-1.91 package:

CARGO_COMMAND=cargo-1.91 cmake ../zenoh-c
cmake --build .

The variable is read at cmake configuration time and baked into the generated build rules, so it has to be set when running cmake to configure the project. The same variable is also honored by the internal build.rs invocations of cargo.

:warning: CARGO_COMMAND selects the cargo executable, not the rustc executable: the compiler is the one that the selected cargo resolves for itself. A cargo installed from distribution packages resolves the matching rustc of its own toolchain, but on a system managed by rustup do not point CARGO_COMMAND at a toolchain binary such as ~/.rustup/toolchains/<toolchain>/bin/cargo. This bypasses the rustup proxies, leaving RUSTUP_TOOLCHAIN unset, and the rustc proxy then resolves a toolchain independently for each crate being compiled: dependencies from the registry get the rustup default toolchain, while crates whose sources are covered by a rust-toolchain.toml get the pinned one. The build ends up mixing rustc versions and fails with error[E0514]: found crate ... compiled by an incompatible version of rustc. To select a rustup toolchain, set RUSTUP_TOOLCHAIN=<toolchain>, run the build under rustup run <toolchain> ..., or use the ZENOHC_CARGO_CHANNEL option.

:warning: rust-toolchain.toml is a rustup feature. When CARGO_COMMAND designates a cargo that is not managed by rustup, the version pinned by that file is ignored and the build uses the toolchain of the selected cargo.

Zenoh features support (enabling/disabling protocols, etc)

It's necessary sometimes to build zenoh-c library with set of features different from default. For example: enable TCP and UDP only. This can be done by changing ZENOHC_CARGO_FLAGS parameter for cmake (notice ";" instead of space due to cmake peculiarities)

Available features can be found in Cargo.toml

cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=transport_tcp,transport_udp"

Versioning

Being a CMake project, zenoh-c is limited to the MAJOR.MINOR.PATCH.TWEAK version scheme inherent to CMake. However, zenoh-c also incorporates a Cargo package which cannot be versionned with the MAJOR.MINOR.PATCH.TWEAK version scheme (not SemVer compatible). Hence zenoh-c uses a one-to-one mapping between CMake versions and SemVer versions: