Package: libzenohc Version: 1.0.0.4-1 Architecture: armel Maintainer: zenoh-dev@eclipse.org Installed-Size: 17102 Filename: 1.0.0.4/libzenohc_1.0.0.4-1_armel.deb Size: 4194120 MD5sum: b81dcbe11b30b46d4da9c05fee7ed145 SHA1: d62c8d663207001b8ad91348cff8f89431750aa1 SHA256: 9a0da7cf7f7fae381ade8711fa7c051da9e9de47d1638f8e309005c712b3541d Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc Version: 1.0.0.4-1 Architecture: arm64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 15866 Filename: 1.0.0.4/libzenohc_1.0.0.4-1_arm64.deb Size: 3878844 MD5sum: c24138828941a5a22a244db0d2d73e73 SHA1: fd7a3570531bc7c242716a8b0beced2a26f1aad9 SHA256: 61a8f505ae6612f27e0ea878576465b0cdc6ca94d482061c4df4211f22f8fcaf Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc Version: 1.0.0.4-1 Architecture: amd64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 17686 Depends: libc6 (>= 2.29) Filename: 1.0.0.4/libzenohc_1.0.0.4-1_amd64.deb Size: 4318476 MD5sum: ecb5f227ff4b246b719bdff0b95f7322 SHA1: aba1368e067b81ac5a373694585c81860d6282f9 SHA256: bb373bd5ee91050ce988205977df690d10c88104f381d06b29ecf3fcec867e13 Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc Version: 1.0.0.4-1 Architecture: armhf Maintainer: zenoh-dev@eclipse.org Installed-Size: 16882 Filename: 1.0.0.4/libzenohc_1.0.0.4-1_armhf.deb Size: 4233952 MD5sum: 82be67e48f8d8e5090cd56884a953d4a SHA1: dea8ecb52c66702b080804d6ab2cde038a140b8f SHA256: a94dfa1b2445ef63f4f4197cff7de225dcf70131a9cd57b8674a04ec1aace67d Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc-dev Version: 1.0.0.4-1 Architecture: arm64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 240 Depends: libzenohc (=1.0.0.4) Filename: 1.0.0.4/libzenohc-dev_1.0.0.4-1_arm64.deb Size: 38516 MD5sum: 3131d0f8f32b4a3c849d0efa61761dea SHA1: fd8d9f266b978ec7443051b958e0c67f280a9281 SHA256: 3a2b54bad84ca522926957965f4cd810581210773f79bd72ad0229fe67626e0d Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc-dev Version: 1.0.0.4-1 Architecture: armhf Maintainer: zenoh-dev@eclipse.org Installed-Size: 240 Depends: libzenohc (=1.0.0.4) Filename: 1.0.0.4/libzenohc-dev_1.0.0.4-1_armhf.deb Size: 38536 MD5sum: 94773fc621d82e91a9f8f4d151e1b341 SHA1: 0e3f63640ff554b5f01555e9318271d7f5fe966e SHA256: 61eda859988d76e18a2d020dadee8ebd049465b50429c1b8d3d05ac0d54f461d Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc-dev Version: 1.0.0.4-1 Architecture: armel Maintainer: zenoh-dev@eclipse.org Installed-Size: 240 Depends: libzenohc (=1.0.0.4) Filename: 1.0.0.4/libzenohc-dev_1.0.0.4-1_armel.deb Size: 38532 MD5sum: bc3afbf94e2d1088d062852edfbc84f4 SHA1: fe8d1ab6e2d86df55db9455c3fcaf6be14f62245 SHA256: ad5778718e892e4b4b45636ac26f1f22370bcf8959a99c32043e3f03e77dd2cb Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c Package: libzenohc-dev Version: 1.0.0.4-1 Architecture: amd64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 240 Depends: libzenohc (=1.0.0.4) Filename: 1.0.0.4/libzenohc-dev_1.0.0.4-1_amd64.deb Size: 38532 MD5sum: 0d425889e933555bb2cf5ce3cb6f2bc5 SHA1: c5b5ea7c37f83d64fe694b124c8595231334d38c SHA256: cb1d5722a4e2b3f17792511d967e0c7194f4c228977c13bed99115bb797246e7 Section: net Priority: optional Homepage: http://zenoh.io Description: The Zenoh C API . [![CI](https://github.com/eclipse-zenoh/zenoh-c/workflows/CI/badge.svg)](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22) [![Documentation Status](https://readthedocs.org/projects/zenoh-c/badge/?version=latest)](https://zenoh-c.readthedocs.io/en/latest/?badge=latest) [![Discussion](https://img.shields.io/badge/discussion-on%20github-blue)](https://github.com/eclipse-zenoh/roadmap/discussions) [![Discord](https://img.shields.io/badge/chat-on%20discord-blue)](https://discord.gg/2GJ958VuHs) [![License](https://img.shields.io/badge/License-EPL%202.0-blue)](https://choosealicense.com/licenses/epl-2.0/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) . # 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](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. . ------------------------------- . # C API . This repository provides a C binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). . ------------------------------- . ## How to build it . > :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in maintaining compatibility between the various git repositories in the Zenoh project. . 1. Make sure that [Rust](https://www.rust-lang.org) is available on your platform. Please check [here](https://www.rust-lang.org/tools/install) to learn how to install it. If you already have the Rust toolchain installed, make sure it is up-to-date with: . ```bash rustup update ``` . 2. Clone the [source] with `git`: . ```bash git clone https://github.com/eclipse-zenoh/zenoh-c.git ``` . [source]: https://github.com/eclipse-zenoh/zenoh-c . 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. . ```bash 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: . ```bash cmake ../zenoh-c -GNinja cmake --build . ``` . [build-configurations]: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations [Visual Studio generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14 [Ninja Multi-Config]: https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html . 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`. . ```bash cmake --build . --target install ``` . If you want to install zenoh-c libraries locally, you can set the installation directory with `CMAKE_INSTALL_PREFIX` . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local cmake --build . --target install ``` . By default only dynamic library is installed. Set `ZENOHC_INSTALL_STATIC_LIBRARY` variable to true to install static library also: . ```bash cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local -DZENOHC_INSTALL_STATIC_LIBRARY=TRUE 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 `ZENOHC_LIB_STATIC` . For `Debug` configuration the library package `zenohc_debug` is installed side-by-side with release `zenohc` library. Suffix `d` is added to names of library files (libzenohc**d**.so). . 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`. . [CMake Tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools . ## 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): . ```bash cmake ../zenoh-c cmake --build . --target examples ``` . You may also use `--target ` 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: . ```bash cmake ../zenoh-c/examples cmake --build . ``` . In this case, the examples executables will be built in the current directory. . As a root project the `examples` project links `zenoh-c` with CMake's [add_subdirectory] command by default. There are also other ways to link `zenoh-c` - with [find_package] or [FetchContent]: . [add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html [find_package]: https://cmake.org/cmake/help/latest/command/find_package.html [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html . Link with `zenoh-c` installed into default location in the system (with [find_package]): . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE ``` . Link with `zenoh-c` installed in `~/.local` directory: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=PACKAGE -DCMAKE_INSTALL_PREFIX=~/.local ``` . Download specific `zenoh-c` version from git with [FetchContent]: . ```bash cmake ../zenoh-c/examples -DZENOHC_SOURCE=GIT_URL -DZENOHC_GIT_TAG=0.11.0-rc ``` . See also `configure_include_project` function in [helpers.cmake] for more information . [helpers.cmake]: cmake/helpers.cmake . ## Running the Examples . ### Basic Pub/Sub Example . ```bash ./target/release/examples/z_sub ``` . ```bash ./target/release/examples/z_pub ``` . ### Queryable and Query Example . ```bash ./target/release/examples/z_queryable ``` . ```bash ./target/release/examples/z_get ``` . ### Running the Throughput Examples . ```bash ./target/release/examples/z_sub_thr ``` . ```bash ./target/release/examples/z_pub_thr ``` . ## API conventions . Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`. . For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11. . We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`. . Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11). . Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program. . The examples have been written with C11 in mind, using the conventions we encourage you to follow. . Finally, we strongly advise that you refrain from using structure field that starts with `_`: . - We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting. - We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates. . ## Logging . By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function. . ## Cross-Compilation . The following alternative options have been introduced to facilitate cross-compilation. > :warning: **WARNING** :warning: : Perhaps additional efforts are necessary, that will depend of your environment. . - `-DZENOHC_CARGO_CHANNEL="+nightly"|"+beta"|"+stable"`: refers to a specific rust toolchain release [[rust-channels](https://rust-lang.github.io/rustup/concepts/channels.html)] - `-DZENOHC_CARGO_FLAGS`: several optional flags can be used for compilation. [[cargo flags](https://doc.rust-lang.org/cargo/commands/cargo-build.html)] - `-DZENOHC_CUSTOM_TARGET`: specifies a crosscompilation target. Currently rust support several Tire-1, Tire-2 and Tire-3 targets [[targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)]. But keep in mind that zenoh-c only have support for following targets: `aarch64-unknown-linux-gnu`, `x86_64-unknown-linux-gnu`, `arm-unknown-linux-gnueabi` . Let's put all together in an example: Assuming you want to crosscompile for aarch64-unknown-linux-gnu. . 1. Install required packages - `sudo apt install gcc-aarch64-linux-gnu` 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 . ```bash export RUSTFLAGS="-Clinker=aarch64-linux-gnu-gcc -Car=aarch64-linux-gnu-ar" mkdir -p build && cd build cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+nightly" -DZENOHC_CARGO_FLAGS="-Zbuild-std=std,panic_abort" -DZENOHC_CUSTOM_TARGET="aarch64-unknown-linux-gnu" -DCMAKE_INSTALL_PREFIX=../aarch64/stage cmake --build . --target install ``` . Additionally you can use `RUSTFLAGS` environment variable for lead the compilation. . If all goes right the building files will be located at: `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` and release files will be located at `/path/to/zenoh-c/target/aarch64-unknown-linux-gnu/release` . ## Rust Version . The Rust version we use is defined in [rust-toolchain.toml](rust-toolchain.toml), which is `1.72.0`. There might be some memory mapping issue if you use the later version. . You can also specify the Rust version. . ```bash cmake ../zenoh-c -DZENOHC_CARGO_CHANNEL="+1.72.0" ``` . ## 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 Zenoh [Cargo.toml](https://github.com/eclipse-zenoh/zenoh/blob/main/zenoh/Cargo.toml) . ```bash cmake ../zenoh-c -DZENOHC_CARGO_FLAGS="--no-default-features;--features=zenoh/transport_tcp,zenoh/transport_udp" ``` . ## Versioning . Being a CMake project, zenoh-c is limited to the `MAJOR.MINOR.PATCH.TWEAK` version scheme [inherent to CMake](https://gitlab.kitware.com/cmake/cmake/-/issues/16716). 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: . | CMake version | SemVer equivalent | Meaning | |-------------------------|-------------------|----------------------| | `1.2.3` | `1.2.3` | Release version | | `1.2.3.0` | `1.2.3-dev` | Developement version | | `1.2.3.x if x >= 1` | `1.2.3-pre.x` | Pre-release version | Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-c Vcs-Git: https://github.com/eclipse-zenoh/zenoh-c