Developer Guide

For contributors working on the ZeroDDS codebase. Eight-section condensed handbook.

Codebase Tour

Single Cargo workspace, ~95 crates organised in nine layers:

LayerTopicCrate count
0Foundation (errors, time, monitor, observability, flatdata)8
1Transport (UDP, TCP, SHM, TSN)5
2Wire Protocol (RTPS, discovery, builtin-topics)6
3Core Services (DCPS, QoS, security, types, sql-filter)12
4Schema (CDR, IDL, per-language code generators)8
5Protocol Bridges (WS / MQTT / CoAP / AMQP / gRPC / CORBA + bridge-security)10
6Language Bindings (C / C++ / C# / Java / Python / TS / Flutter)11
7Bridging Services (ROS-2 RMW, DLRL, OPC-UA, XRCE, web, soap)11
8CORBA + CCM (full OMG CORBA 3.3 + DDS4CCM 1.1 stack)17

Cargo + MSRV

Workspace pins to Rust 1.88.0, Edition 2024 via rust-toolchain.toml. Layer-N crates may depend only on layers 0 .. N-1; cycles are detected by cargo run -p dds-lint -- check. No [workspace.dependencies] table — each crate manages its own dependency versions.

RC1 Definition-of-Done

Every crate must satisfy 13 checks before its tracker entry flips to ✅ rc1-ready. See RC1_GUARDRAILS.md:

  1. Cargo.toml metadata complete
  2. lib.rs / main.rs header with safety class + spec ref
  3. README.md
  4. CHANGELOG.md
  5. Public-API audit
  6. Coherence audit (CONNECTED / TEST-ONLY / DEAD)
  7. Spec-coverage doc updated
  8. Forbidden-token sweep
  9. SPDX license headers per file
  10. Tests + lints + doc build green
  11. Review doc under docs/release/rc1-reviews/
  12. Tracker entry ✅ rc1-ready
  13. Public mirror under github/ + website/

Wire-Format Conventions

Two contracts:

  • RTPS 2.5 — crates/rtps/. Wire bytes verified against Cyclone DDS captures. Cross-vendor fixtures under crates/discovery/tests/fixtures/cyclone-xcdr2/.
  • XCDR1 / XCDR2 — crates/cdr/. Encoder + decoder for all primitive types, sequences, optionals, maps, unions, mutable structs (DHEADER + EMHEADER + PID), bitmasks. See the CDR Wire-Format Handbook.

Test Categories

  • Unit — in #[cfg(test)] mod tests alongside source.
  • Integration — in tests/ per crate.
  • Cross-vendor — gated behind #[ignore], run against external broker / DDS implementations in CI lab.
  • Fuzz — cargo fuzz harnesses in fuzz/ per protocol crate.
  • End-to-end — tests/interop/ with docker-compose for mosquitto / RabbitMQ / libcoap / omniORB / grpcurl / ros2-cyclone.

Spec-Coverage Workflow

Each OMG spec has a coverage doc under docs/spec-coverage/<spec>.md. Per section: Status ∈ {done, partial, open, n/a (informative), n/a (rejected)}, Repo link to source, Tests link to test functions. partial + open are RC1 blockers; n/a (rejected) needs an ADR under docs/adr/.

Public-Mirror Sync

Three trees in one repository:

  • ./ — internal development tree, may contain internal hostnames, sprint markers.
  • github/ — public mirror after forbidden-token sweep. This is what gets pushed to github.com/zero-objects/zero-dds.
  • website/ — Public landing pages, manuals, claims, commercial. Deployed to zerodds.org.

The forbidden-token sweep runs in CI. Anything in github/ or website/ matching the forbidden list (internal hostnames, WP X.Y.Z sprint markers, etc.) blocks the merge.

Release Process

  1. Audit all 90+ crates via cargo run -p tools/cargo-dag for publish-order.
  2. Green CI on main: clippy, fmt, test, dds-lint, cargo-deny.
  3. Tag 1.0.0-rc.3 on the workspace + per-crate tags.
  4. Push github/ tree to github.com/zero-objects/zero-dds.
  5. Publish to crates.io in DAG order.
  6. Build packaging artifacts (.deb, .rpm, AppImage, Homebrew, MSI, Docker).
  7. Deploy website/ to zerodds.org.

Full handbook on GitHub →

Developer Guide

Für Contributor, die am ZeroDDS-Codebase arbeiten. Kompaktes Handbuch in acht Abschnitten.

Codebase-Tour

Ein einzelner Cargo-Workspace, ~95 Crates in neun Schichten organisiert:

SchichtThemaCrate-Anzahl
0Foundation (Errors, Time, Monitor, Observability, flatdata)8
1Transport (UDP, TCP, SHM, TSN)5
2Wire-Protokoll (RTPS, Discovery, Builtin-Topics)6
3Core-Services (DCPS, QoS, Security, Types, sql-filter)12
4Schema (CDR, IDL, Sprach-Codegeneratoren)8
5Protokoll-Bridges (WS / MQTT / CoAP / AMQP / gRPC / CORBA + bridge-security)10
6Sprach-Bindings (C / C++ / C# / Java / Python / TS / Flutter)11
7Bridging-Services (ROS-2 RMW, DLRL, OPC-UA, XRCE, web, soap)11
8CORBA + CCM (voller OMG-CORBA-3.3- + DDS4CCM-1.1-Stack)17

Cargo + MSRV

Der Workspace pinnt via rust-toolchain.toml auf Rust 1.88.0, Edition 2024. Layer-N-Crates dürfen nur von den Schichten 0 .. N-1 abhängen; Zyklen erkennt cargo run -p dds-lint -- check. Keine [workspace.dependencies]-Tabelle — jede Crate verwaltet ihre eigenen Dependency-Versionen.

RC1-Definition-of-Done

Jede Crate muss 13 Checks erfüllen, bevor ihr Tracker-Eintrag auf ✅ rc1-ready springt. Siehe RC1_GUARDRAILS.md:

  1. Cargo.toml-Metadaten vollständig
  2. lib.rs / main.rs-Header mit Safety-Klasse + Spec-Ref
  3. README.md
  4. CHANGELOG.md
  5. Public-API-Audit
  6. Kohärenz-Audit (CONNECTED / TEST-ONLY / DEAD)
  7. Spec-Coverage-Doc aktualisiert
  8. Forbidden-Token-Sweep
  9. SPDX-Lizenz-Header pro Datei
  10. Tests + Lints + Doc-Build grün
  11. Review-Doc unter docs/release/rc1-reviews/
  12. Tracker-Eintrag ✅ rc1-ready
  13. Public-Mirror unter github/ + website/

Wire-Format-Konventionen

Zwei Verträge:

  • RTPS 2.5 — crates/rtps/. Wire-Bytes gegen Cyclone-DDS-Captures verifiziert. Cross-Vendor-Fixtures unter crates/discovery/tests/fixtures/cyclone-xcdr2/.
  • XCDR1 / XCDR2 — crates/cdr/. Encoder + Decoder für alle primitiven Typen, Sequences, Optionals, Maps, Unions, mutable Structs (DHEADER + EMHEADER + PID), Bitmasks. Siehe das CDR-Wire-Format-Handbuch.

Test-Kategorien

  • Unit — in #[cfg(test)] mod tests neben dem Source.
  • Integration — in tests/ pro Crate.
  • Cross-Vendor — hinter #[ignore] gegated, laufen gegen externe Broker / DDS-Implementierungen im CI-Lab.
  • Fuzz — cargo fuzz-Harnesses in fuzz/ pro Protokoll-Crate.
  • End-to-End — tests/interop/ mit docker-compose für mosquitto / RabbitMQ / libcoap / omniORB / grpcurl / ros2-cyclone.

Spec-Coverage-Workflow

Jede OMG-Spec hat ein Coverage-Doc unter docs/spec-coverage/<spec>.md. Pro Sektion: Status ∈ {done, partial, open, n/a (informative), n/a (rejected)}, Repo-Link zur Quelle, Tests-Link zu den Test-Funktionen. partial + open sind RC1-Blocker; n/a (rejected) braucht ein ADR unter docs/adr/.

Public-Mirror-Sync

Drei Bäume in einem Repository:

  • ./ — interner Entwicklungs-Baum, darf interne Hostnamen und Sprint-Marker enthalten.
  • github/ — Public-Mirror nach dem Forbidden-Token-Sweep. Das wird nach github.com/zero-objects/zero-dds gepusht.
  • website/ — öffentliche Landing-Pages, Manuals, Claims, Commercial. Deployed nach zerodds.org.

Der Forbidden-Token-Sweep läuft in der CI. Alles in github/ oder website/, das auf der Forbidden-Liste matcht (interne Hostnamen, WP X.Y.Z-Sprint-Marker etc.), blockiert den Merge.

Release-Prozess

  1. Alle 90+ Crates via cargo run -p tools/cargo-dag auf Publish-Reihenfolge auditieren.
  2. Grüne CI auf main: clippy, fmt, test, dds-lint, cargo-deny.
  3. 1.0.0-rc.3 auf dem Workspace + per-Crate-Tags taggen.
  4. github/-Baum nach github.com/zero-objects/zero-dds pushen.
  5. In DAG-Reihenfolge auf crates.io publishen.
  6. Packaging-Artefakte bauen (.deb, .rpm, AppImage, Homebrew, MSI, Docker).
  7. website/ nach zerodds.org deployen.

Vollständiges Handbuch auf GitHub →