IDL & codegen

OMG IDL — the Interface Definition Language — is a language-agnostic way to describe data types and remote interfaces. It first shipped in 1991 alongside CORBA. The current revision, IDL 4.2 (ISO/IEC 19516), drops legacy CORBA-only constructs and adds a clean set of annotations for modern middleware.

An IDL file looks roughly like a C header: it declares structs, unions, enums, interfaces and modules. The IDL compiler reads that file and generates language-native code — Rust types, C++ headers, Java classes, Python modules — that all encode and decode the same byte layout on the wire.

IDL is what makes DDS, CORBA, DDS-RPC and DDS-XRCE language-agnostic. Write the contract once, generate for every consumer. The wire format (XCDR1, XCDR2 for DDS; CDR for CORBA) is defined by the standard, not by the language.

@topic
@appendable
struct SensorReading {
    @key long sensor_id;
    double    value;
    @optional sequence<string> tags;
};

Three reasons IDL is non-negotiable for a serious middleware stack. First, language coverage: without a single source of truth, a multi-language deployment turns into N hand-written serializers, all subtly out of sync. With IDL, every binding renders the same type from the same source — and a CI step verifies that the renders stay aligned.

Second, wire-stable evolution: XTypes 1.3 annotations (@mutable, @final, @appendable, @optional) tell the codegen how a type may change over time. The annotation system means an old reader stays compatible with a new writer, and CI can flag breaking changes before they leave the merge request.

Third, vendor-lock-in avoidance: IDL is an OMG standard, not a vendor format. Move your IDL from RTI Connext, OpenSplice, Cyclone DDS or Fast-DDS into ZeroDDS without rewriting interfaces — only the codegen target changes.

ZeroDDS' own IDL parser is grammar-driven (not regex-based), with a vendor-extension pipeline that accepts dialect quirks from the four established vendors. That is the migration enabler: existing IDL files just compile.

At the centre is the parser. Around it sit seven codegen back-ends — one per target language — plus a CLI (idlc) that orchestrates them. The parser produces a typed AST; each codegen back-end is a small visitor that emits language-native source.

Install

The idlc CLI ships as a separate crate. Install from crates.io or as a signed binary.

cargo install zerodds-idlc

Generate code

Pick a target language and point idlc at your .idl file. The output is one file per top-level module.

zerodds-idlc --c      -o gen/c      types.idl
zerodds-idlc --cpp    -o gen/cpp    types.idl
zerodds-idlc --rust   -o gen/rust   types.idl
zerodds-idlc --ts     -o gen/ts     types.idl
zerodds-idlc --csharp -o gen/cs     types.idl
zerodds-idlc --java   -o gen/java   types.idl
zerodds-idlc --python -o gen/py     types.idl

Build-system integration

Every binding ships a thin build helper. The Rust example below regenerates types.rs whenever types.idl changes.

// build.rs
fn main() {
    zerodds_idlc::build()
        .file("types.idl")
        .out_dir(env!("OUT_DIR"))
        .generate()
        .expect("idl codegen");
}

Lint your IDL

dds-lint reads .idl files and flags common issues: missing @key annotations, types that break wire compatibility, accidental @mutable on hot-path messages. Use it as a pre-commit hook or CI step.

dds-lint check types.idl

Annotations cheatsheet

XTypes 1.3 annotations control wire-compatible evolution. Pick the right annotation up front — changing it later is a breaking change.

Annotation	Use
@topic	@topic — mark a struct as a top-level DDS topic type. CI checks topic-name uniqueness.
@key	@key — designate fields as the keyset for instance handling. Must be invariant across the lifetime of an instance.
@appendable	@appendable — default. Fields may be added at the end without breaking older readers.
@mutable	@mutable — fields may be added or removed by name. Slightly larger wire size; more flexibility.
@final	@final — frozen. Adding a field is a breaking change. Use for high-rate, locked-in types.
@optional	@optional — field may be absent on the wire. Readers see Option<T>.

Per-language pointers

Rust

cargo add zerodds-dcps zerodds-idlc. Use build.rs to regenerate types.rs on every cargo build. Async via dcps-async.

• Mapping doc
• Man page
• Source
• docs.rs

C++

zerodds-idlc --cpp emits C++17 headers under your include path. Configure CMake to call zerodds-idlc before compilation.

• Mapping doc
• Man page
• Source
• docs.rs

C# / .NET

zerodds-idlc --csharp emits a .cs file per module. Add it to your MSBuild project. Target .NET 8+ or netstandard2.1.

• Mapping doc
• Man page
• Source
• docs.rs

Java

zerodds-idlc --java emits a .java file per IDL declaration under the standard Maven layout (one file per package). Pure Java — no JNI.

• Mapping doc
• Man page
• Source
• docs.rs

Python

zerodds-idlc --python emits one Python module per IDL module with @idl_struct decorators and type hints. Same wire bytes as the Rust path.

• Crate doc
• Vendor spec
• Source
• PyPI

TypeScript

zerodds-idlc --ts emits a TypeScript module. Pair with ts-node for the Node.js bundle or ts-wasm for the browser bundle (WebSocket-only). Strict TypeScript.

• Mapping doc
• Man page
• Source
• docs.rs

C

zerodds-idlc --c emits a plain C99 header with POD structs and XCDR2 typesupport tables for your IDL types — wire-compatible with every other ZeroDDS codegen target. Independent from the runtime: combine with the zerodds-c-api FFI library (-lzerodds) for full DCPS access from C.

• Per-crate doc
• Runtime FFI (Quickstart)
• Source
• Vendor spec