eclipse-cyclonedds-sys 0.0.4

Raw FFI Bindings for Eclipse Cyclone DDS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# Raw FFI Bindings for Eclipse Cyclone DDS

[![Latest Version][crates.io-shield]][crates.io]
[![Build Status][check-workflow-status-shield]][check-workflow]
[![Community][community-shield]][community]
[![Website][cyclonedds-homepage-shield]][cyclonedds-homepage]

[![Code Coverage][codecov-shield]][codecov]
[![Documentation][docs.rs-shield]][docs.rs]
[![Dependency Status][deps.rs-shield]][deps.rs]

Raw Rust FFI bindings for [Eclipse Cyclone DDS][cyclonedds-github].

This crate is the low-level `bindgen` layer used by
[`eclipse-cyclonedds`][eclipse-cyclonedds]. Most applications should depend on
`eclipse-cyclonedds`, which provides the safe Rust API, topic support, QoS
builders, readers, writers, waitsets, and sample handling.

Depend on `eclipse-cyclonedds-sys` directly only when you need access to the C
API surface itself.

- [Quick Start](#quick-start)
- [Linking Cyclone DDS](#linking-cyclone-dds)
- [Generated Bindings](#generated-bindings)

## Quick Start

For normal DDS applications, add the main binding:

```toml
[dependencies]
eclipse-cyclonedds = "0.0.4"
```

Use this crate directly for raw FFI integration:

```toml
[dependencies]
eclipse-cyclonedds-sys = "0.0.4"
```

The crate exposes the generated bindings under the Rust library name
`cyclonedds_sys`:

```rust
use cyclonedds_sys as sys;

fn main() {
    let domain = sys::DOMAIN_DEFAULT;
    println!("default DDS domain: {domain}");
}
```

Direct use of these bindings follows the safety contract of the Cyclone DDS C
API. Prefer the safe `eclipse-cyclonedds` crate unless you specifically need raw
FFI.

## Linking Cyclone DDS

By default, this crate expects the Cyclone DDS C library and headers to be
available on the system. The build script links against `ddsc` and generates
bindings from `wrapper.h`.

If Cyclone DDS is installed outside the system search paths, set
`CYCLONEDDS_HOME` to the installation prefix:

```sh
CYCLONEDDS_HOME=/opt/cyclonedds cargo build
```

The build script will then look for headers under `$CYCLONEDDS_HOME/include` and
libraries under `$CYCLONEDDS_HOME/lib` or `$CYCLONEDDS_HOME/lib64`.

To build Cyclone DDS from the sources bundled with this crate, enable the
`vendored` feature:

```toml
[dependencies]
eclipse-cyclonedds-sys = { version = "0.0.4", features = ["vendored"] }
```

It requires `cmake` and `libclang` to be available.

## Generated Bindings

Bindings are generated at build time with `bindgen` and included from Cargo's
`OUT_DIR`. It contains raw pointers, C layout types, platform-specific
definitions, and functions that are unsafe to call without satisfying the C API
preconditions.

See the [main crate documentation][eclipse-cyclonedds-docs] for the safe
ergonomic Rust API.

## Minimum Supported Rust Version

For now, the MSRV is the latest stable Rust version at the time of release.

## References

- [Rust binding for Eclipse Cyclone DDS][eclipse-cyclonedds]
- [Cyclone DDS][cyclonedds-github]
- [Cyclone DDS Documentation][cyclonedds-docs]
- [OMG DDS Specification][dds-spec]
- [OMG DDSI-RTPS specification][ddsi-rtps-spec]
- [OMG DDS Wiki][omg-dds-wiki]
- [Contributing](../CONTRIBUTING.md)
- [Security Policy](../SECURITY.md)

[check-workflow]: https://github.com/eclipse-cyclonedds/cyclonedds-rust/actions/workflows/check.yml
[check-workflow-status-shield]: https://shieldcn.dev/github/ci/eclipse-cyclonedds/cyclonedds-rust?no-track&mode=light&size=xs
[codecov]: https://codecov.io/github/eclipse-cyclonedds/cyclonedds-rust
[codecov-shield]: https://codecov.io/gh/eclipse-cyclonedds/cyclonedds-rust/graph/badge.svg
[community]: https://discord.gg/4QQvWZrFKF
[community-shield]: https://shieldcn.dev/discord/960814229844291604.svg?no-track&variant=branded&size=xs
[crates.io]: https://crates.io/crates/eclipse-cyclonedds-sys
[crates.io-shield]: https://shieldcn.dev/group/crates/eclipse-cyclonedds-sys+crates/license/eclipse-cyclonedds-sys.svg?no-track&mode=light&size=xs
[cyclonedds-docs]: https://cyclonedds.io/docs
[cyclonedds-github]: https://github.com/eclipse-cyclonedds/cyclonedds
[cyclonedds-homepage]: https://cyclonedds.io
[cyclonedds-homepage-shield]: https://shieldcn.dev/badge/web-cyclonedds.io-blue.svg?no-track&mode=light&logo=lu%3ATornado&size=xs
[dds-spec]: https://www.omg.org/spec/DDS/1.4/About-DDS/
[ddsi-rtps-spec]: https://www.omg.org/spec/DDSI-RTPS/
[deps.rs]: https://deps.rs/repo/github/eclipse-cyclonedds/cyclonedds-rust
[deps.rs-shield]: https://deps.rs/repo/github/eclipse-cyclonedds/cyclonedds-rust/status.svg
[docs.rs]: https://docs.rs/eclipse-cyclonedds-sys
[docs.rs-shield]: https://docs.rs/eclipse-cyclonedds-sys/badge.svg
[eclipse-cyclonedds]: https://crates.io/crates/eclipse-cyclonedds
[eclipse-cyclonedds-docs]: https://docs.rs/eclipse-cyclonedds
[omg-dds-wiki]: https://www.omgwiki.org/ddsf/doku.php?id=ddsf:public:guidebook:01_front:4_toc