zerodds-build

A build.rs helper for ZeroDDS IDL: one Rust module per .idl, with #include dependency tracking so cargo re-runs when a header changes.

A prost-build-style build.rs helper for ZeroDDS IDL: Config::new().include_dir(...).compile(&["x.idl"]).

What it replaces

The supported way to generate Rust types from IDL inside a Cargo build. It replaces calling the CLI from a build.rs and the derive macro of the former zerodds-cdr-derive; a topic type is declared in IDL and gets its DdsType impl from dds_type_impls(true) (below). Migration notes: CHANGELOG, [1.0.0-rc.7], section “Removed”.

Layer position

Layer 3 (schema), build-time-only dependency: put it under [build-dependencies], not [dependencies]. Depends on zerodds-idl-compose for the composition pipeline and on zerodds-lang-rules + zerodds-lang-render for the emission.

Why it exists

zerodds-idlc generate --lang rust emits data types and codecs. This crate integrates generation into Cargo and, on request, adds the DdsType bridge. The composition in front of both is more than a parse: it preprocesses #include/#define/#ifdef/#pragma, applies vendor key pragmas (#pragma keylist / DCPS_DATA_KEY / cats), patches default extensibility and nestedness, and lowers XTypes TypeObjects. build.rs scripts that called the low-level parse and emit directly skipped those steps silently: no #include dependency tracking, no vendor key pragmas, no default extensibility, no TypeObject block. zerodds-build runs the same composition library the CLI uses, with a typed configuration surface for build-time consumers. This is shared machinery, not a claim that every CLI option has an identical build-script method.

Usage

[build-dependencies]
zerodds-build = "1.0.0-rc.7"
// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .include_dir("idl")
        .compile(&["idl/Robot.idl"])
}
// src/lib.rs
#[allow(non_snake_case, unused_imports)]
mod robot {
    include!(concat!(env!("OUT_DIR"), "/Robot.rs"));
}

include! splices the generated tokens into the including file, so any lint allow the generated code needs goes on the wrapping module as an outer attribute (as above).

Every .idl path passed to compile(), plus every file it transitively #includes, is reported via cargo:rerun-if-changed — editing an included .idl triggers a rebuild, not just editing the top-level file.

Topic types

The generated type carries a codec — a pair of inherent functions over zerodds_wire::Writer/Reader — but not the zerodds_dcps::DdsType trait that DomainParticipant::create_topic takes. dds_type_impls(true) writes that impl too:

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .dds_type_impls(true)
        .compile(&["idl/Robot.idl"])
}
participant.create_topic::<Robot>("entity.robot")?;

The impl carries TYPE_NAME from the IDL scoped name, EXTENSIBILITY from the annotation, HAS_KEY and the PLAIN_CDR2-BE key holder from the @key members, the complete TypeIdentifier and TypeObject from the same computation discovery uses, field_value for the SQL filter, and all four codec pairs — XCDR2 and XCDR1, little-endian and big-endian — from the same emitter under four layout keys.

It is off by default: it puts zerodds-dcps, zerodds-types and zerodds-wire into the consumer's [dependencies], which is the whole DCPS runtime, and this crate is also used by consumers that want the codec and no DDS in the graph at all.

Where XCDR1 cannot frame a type, the four XCDR1 methods are left out and the trait's own refusing defaults stand, with a comment in the generated file naming the type. They are not delegated to the XCDR2 codec: that would put version-2 octets under a CDR_LE/CDR_BE encapsulation header, which no peer can tell from a sample it is meant to read.

Config

Config method what it sets
include_dir(dir) a directory the preprocessor searches for #include
define(name, value) a preprocessor macro, as -D NAME[=VALUE] would
out_dir(dir) where the generated files go (default: $OUT_DIR)
default_extensibility(ext) what an unannotated aggregate is: Final, Appendable or Mutable (default: Appendable, XTypes 1.3 §7.3.1.2.1.8)
typeobject(bool) the type_objects_* module of raw TypeObject bytes (default: on)
header_comment(text) the header comment in the generated file
type_identifier_constants(bool) a zerodds_types::TypeIdentifier constant per type (default: off)
emit_cargo_directives(bool) whether compile() prints cargo:rerun-if-changed (default: on)
dds_type_impls(bool) impl zerodds_dcps::DdsType per type (default: off)
dialect(Dialect) reproduce one peer's answers to every wire axis at once (default: Dialect::default(), the specification)
axis(AxisFlag, value) override one answer of the dialect; several calls apply in the order given
rust_type(idl_path, rust_type) hold a typedef, struct member or union branch as a Rust type that implements zerodds_wire::WireRepr (below)
rust_type_with(idl_path, rust_type, adapter) the same through an adapter value that implements zerodds_wire::WireReprWith
strip_enum_prefix(bool) cut each enumeration's name off its enumerators' Rust names (below); default off
rust_naming(RustNaming) the naming scheme: RustNaming::Idl (default, the IDL names) or RustNaming::Rust (RFC 430) (below)

compile_bundle(idls, name) composes several input files into one generated module when they share declarations. compile(idls) emits per-input files.

Dialects and axis flags

Config::dialect and Config::axis are zerodds-idlc generate --dialect/--<axis> and wireprobe-zerodds --dialect/--<axis>, read from the same table in zerodds-ast-layout and applied in the same order: the dialect first, then each axis override. docs/wire-axis-flags.md has every dialect's answer to every axis and the values axis takes.

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .dialect(zerodds_ast_layout::Dialect::Cyclone)
        .axis(zerodds_ast_layout::AxisFlag::LengthCodes, "compact")
        .compile(&["idl/Robot.idl"])
}

The default — no dialect call, no axis call — is Dialect::default(), the specification's clause-by-clause reading. An unrecognised axis value is not a build-time panic: compile() and compile_bundle() return Err(Error::Axis { flag, value, detail }), naming which .axis(...) call was wrong.

External storage

Generated Rust stores @external T members in Box<T>, and @optional @external T members in Option<Box<T>>. This makes an optional self-reference finite without changing its wire representation.

A Rust type for an IDL type

An IDL typedef string UtcTimestamp; is a String in the generated Rust, and so is a text that is no timestamp. rust_type names a Rust type that stands for a typedef, a struct member or a union branch, and the generated code holds that type instead (GitHub #33):

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .rust_type("app::UtcTimestamp", "crate::time::UtcTimestamp")
        .rust_type("app::Track.id", "core::num::NonZeroU32")
        .rust_type_with("app::Track.source", "std::net::Ipv4Addr", "zerodds_wire::DisplayFromStr")
        .dds_type_impls(true)
        .compile(&["idl/app.idl"])
}
  • The path is the IDL scoped name: a typedef (app::UtcTimestamp), a struct member (app::Track.id) or a union branch (app::Choice.stamp). A member mapping wins over a typedef mapping of the member's type.
  • The Rust type implements zerodds_wire::WireRepr (zerodds-wire), whose Idl is the IDL type's Rust spelling: str for a string, u32 for an unsigned long. zerodds-wire carries the impls for core::num::NonZero*, String and Cow<'_, str>; a type from another crate goes through an adapter (rust_type_with), zerodds_wire::DisplayFromStr for a Display + FromStr type on a string. The IDL type is a string or a primitive other than wchar and long double.
  • The generated type holds the Rust type wherever the declaration is used: a member, a sequence, array or map element, a union branch, Option for @optional, Box for @external. A typedef is an alias of it.
  • Encode writes the IDL value through to_wire; decode reads it — a string lent out of the sample, not copied — and converts through from_wire. A value the Rust type refuses rejects the sample with that reason.
  • The octets, the TypeObject, the TypeIdentifier, assignability and the key hash are the IDL's. A C or C++ peer built from the same IDL reads the same samples.
  • A path that names no typedef, struct member or union branch of the compiled units, a declaration of another IDL type and a Rust type that is no type path fail the build with Error::RustType. A Rust type whose Idl is not the IDL type fails to compile: the generated file states every mapping as zerodds_wire::repr::idl_type_is::<T, Idl>().
  • The generated types derive Debug, Clone and PartialEq, so the Rust type implements them. A type with a member whose Rust type refuses the IDL default (a NonZeroU32 for the default zero) gets no impl Default, and a sample that leaves such a member out — an older @appendable writer, a key-only sample — is rejected.

The example rust-type holds a date-time group, DDHHMMZMONYY, for an IDL string and a NonZeroU32 for a uint32 key.

Rust names

The generated Rust takes the IDL's names by default, as the OMG mappings for Java and C# do (IDL4 to Java 1.0 and IDL4 to C# 1.0, §7.1.1); there is no adopted IDL4 to Rust mapping. Two settings change the Rust names and nothing else: the TypeObject, the member ids, the registered type names, a content filter and the paths rust_type takes read the IDL names, and the octets on the wire are the same.

zerodds_build::Config::new()
    .rust_naming(zerodds_build::RustNaming::Rust)
    .strip_enum_prefix(true)
    .compile(&["idl/sensor.idl"])?;

rust_naming(RustNaming::Rust) writes the names after the Rust API guidelines (RFC 430):

IDLRust
module Sensor_Datapub mod sensor_data
struct, union, enum, bit set, bit mask, typedef, exception reading_kind, HTTPReadingReadingKind, HttpReading
member sensorIdfield sensor_id
enumerator READING_KIND_rawvariant ReadingKindRaw; Raw with strip_enum_prefix(true)
union branch filtered_valuevariant FilteredValue
constant maxSamples, bit flagReadyMAX_SAMPLES, FLAG_READY
interface robot_arm, operation moveTo, parameter targetXtrait RobotArm, method move_to, parameter target_x; RobotArmClient, RobotArmDispatcher, RobotArmError
the DDS-RPC types robot_arm_moveTo_In, robot_arm_CallRobotArmMoveToIn, RobotArmCall; registered under the DDS-RPC names
  • A name is split into words at each _, where a lower-case letter is followed by an upper-case one, and before the last letter of an upper-case run that a lower-case letter follows. An acronym is one word.
  • strip_enum_prefix(true) cuts the enumeration's name off its enumerators, as prost-build does by default: MY_ENUM_A of MyEnum is A. The name matches without regard to case and underscores; it is cut only where a valid identifier is left (MY_ENUM_1 stays).
  • @rust_mapping(apply_naming_convention = RUST_NAMING_CONVENTION) or IDL_NAMING_CONVENTION on a module or on a type, constant, exception or interface sets the scheme for what that declaration encloses, over what the build chose. An interface and its base take one scheme.
  • Two declarations of one scope that come out as one Rust name (my_field and myField) fail the build and name both.
  • Under RustNaming::Rust the module that includes the generated file needs no #[allow(non_snake_case)].

A topic type defined in Rust

The other route of GitHub #33: the type is defined in Rust, and its IDL comes out of it for C, C++ and other vendors. derive(DdsType) of zerodds-codec (crate zerodds-derive) writes the type's description, its codec and its DdsType impl:

use zerodds_codec::{DdsType, WireRepr};

#[derive(WireRepr)]
#[wire(idl = "string")] // reads through TryFrom<&str>, writes through Display
struct Dtg(DateTimeGroup);

#[derive(DdsType)]
#[dds(name = "app::Track", extensibility = "appendable")]
struct Track {
    #[dds(key)]
    id: NonZeroU32,    // unsigned long
    at: Dtg,           // string
    #[dds(bound = 64)]
    label: String,     // string<64>
    note: Option<String>, // @optional string
}

println!("{}", Track::idl()?); // the IDL a C or C++ peer is generated from
  • Member types: bool, the integers (u8 is octet), f32, f64, char, String, core::num::NonZero*, a WireRepr type, Vec<T> (sequence), [T; N] (array), Option<T> (@optional), a derived struct, a field-less enum, std::time::Duration (DDS::Duration_t) and std::time::SystemTime (DDS::Time_t).
  • Attributes, after the IDL annotations: on the struct name, extensibility (default appendable), autoid, nested, codec = "manual"; on a field key, id, hashid, bound, name, optional, with (an adapter for a type from another crate); on an enum name and bit_bound, on a variant name and value.
  • The description becomes IDL, and that IDL goes through the IDL front end, the TypeObject builder and the layout planner a .idl file given to this crate goes through. The derived type and the type this crate generates from the equivalent IDL have the same TypeObject, the same TypeIdentifier and the same octets under XCDR1 and XCDR2 in both byte orders; a C peer generated from Track::idl() reads them.
  • A value the Rust type refuses on decode rejects the sample with its reason. The key hash is computed over the IDL value.
  • A codec written by hand (DdsSerialize, DdsDeserialize, see zerodds-wire) is checked at compile time against the description.
  • An enum whose variants carry data is an IDL union. discriminator = "i16" names the discriminator’s Rust type (an integer, bool, char or a derived field-less enum; i32, long, when not given). On a variant: case = 1 or case = [2, 3], or no case for one past the highest label before it; default; no_member on a variant V(D) that holds a discriminator no case takes; id, hashid, name, bound. A variant V(T) holds the branch member; a case with several labels and the default: case are V(D, T) and go out again under the discriminator they were read with. key on the enum makes the discriminator the union’s key (switch (@key D), DDS-XTypes 1.3 §7.2.2.4.4.4.8): as a topic type the union is keyed and its key holder is the discriminator; as a key field of a struct only its discriminator is part of that key. A content filter names a branch by its IDL member name and the discriminator as #discriminator (reading.#discriminator = 3 AND reading.kelvin > 290); an expression that names a branch the discriminator does not select is false (DDS-XTypes 1.4 Beta 1 §7.6.7.1).
  • A generic type is one IDL type per instantiation. Its name is a template in which {T} stands for the argument’s IDL type: Pair<T> is Pair_{T} unless name says otherwise, and Pair<u32> is Pair_unsigned_long, Pair<app::Point> Pair_app_Point. Each instantiation has its own TypeObject and TypeIdentifier.
  • A field may borrow from the received sample: &'a str, &'a [u8], Cow<'a, str>, Cow<'a, [u8]>. zerodds_codec::decode over &'de [u8] lends them out of the bytes. A type with a borrowed field has no DdsType impl: a DataReader takes an owned value until the loaned take exists.

The example rust-derive defines the date-time group, a union, a generic pair and the track in Rust, compares their octets with the IDL route, reads the track through a borrowed view and in a C peer.

Not yet covered

Only the Rust backend is wired. The composition pipeline (zerodds-idl-compose) is language-agnostic and zerodds-lang-rules carries the rules for every target the CLI knows, so a zerodds-build-style crate for another language would call the same compose() and the matching rule set.

Generation returns an error for an unsupported member rather than leaving it out.

zerodds-build

Ein Helfer für build.rs für ZeroDDS-IDL: ein Rust-Modul je .idl, mit Verfolgung der #include-Abhängigkeiten, damit cargo neu baut, wenn sich ein Header ändert.

Ein Helfer für build.rs nach dem Vorbild von prost-build für ZeroDDS-IDL: Config::new().include_dir(...).compile(&["x.idl"]).

Was er ersetzt

Der unterstützte Weg, in einem Cargo-Build Rust-Typen aus IDL zu erzeugen. Er ersetzt den Aufruf der CLI aus einem build.rs und das Derive-Makro der früheren Crate zerodds-cdr-derive; ein Topic-Typ wird in IDL deklariert und bekommt sein DdsType-Impl über dds_type_impls(true) (siehe unten). Migrationshinweise: CHANGELOG, [1.0.0-rc.7], Abschnitt „Removed“.

Schichten-Position

Layer 3 (Schema), nur zur Bauzeit gebraucht: unter [build-dependencies] eintragen, nicht unter [dependencies]. Hängt für die Komposition von zerodds-idl-compose ab und für die Ausgabe von zerodds-lang-rules und zerodds-lang-render.

Warum es ihn gibt

zerodds-idlc generate --lang rust erzeugt Datentypen und Codecs. Diese Crate bindet die Generierung in Cargo ein und fügt auf Wunsch die Brücke zu DdsType hinzu. Die Komposition davor ist mehr als ein Parsen: Sie verarbeitet #include/#define/#ifdef/#pragma, wendet die Key-Pragmas der Hersteller an (#pragma keylist / DCPS_DATA_KEY / cats), ergänzt Standard-Erweiterbarkeit und -Verschachtelung und senkt XTypes-TypeObjects ab. build.rs-Skripte, die Parser und Ausgabe direkt aufriefen, übersprangen diese Schritte stillschweigend: keine Verfolgung von #include-Abhängigkeiten, keine Key-Pragmas, keine Standard-Erweiterbarkeit, kein TypeObject-Block. zerodds-build nutzt dieselbe Kompositionsbibliothek wie die CLI, mit einer typisierten Konfiguration für Nutzer zur Bauzeit. Das ist gemeinsame Mechanik, keine Zusage, dass jede Option der CLI eine gleichwertige Methode im Build-Skript hat.

Verwendung

[build-dependencies]
zerodds-build = "1.0.0-rc.7"
// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .include_dir("idl")
        .compile(&["idl/Robot.idl"])
}
// src/lib.rs
#[allow(non_snake_case, unused_imports)]
mod robot {
    include!(concat!(env!("OUT_DIR"), "/Robot.rs"));
}

include! fügt die erzeugten Tokens in die einbindende Datei ein. Jede Lint-Freigabe, die der erzeugte Code braucht, steht deshalb als äußeres Attribut am umschließenden Modul (wie oben).

Jeder .idl-Pfad, der an compile() geht, und jede Datei, die er transitiv per #include einbindet, wird über cargo:rerun-if-changed gemeldet — auch eine Änderung an einer eingebundenen .idl löst einen neuen Build aus, nicht nur eine an der obersten Datei.

Topic-Typen

Der erzeugte Typ trägt einen Codec — ein Paar inhärenter Funktionen über zerodds_wire::Writer/Reader —, aber nicht den Trait zerodds_dcps::DdsType, den DomainParticipant::create_topic verlangt. dds_type_impls(true) schreibt dieses Impl dazu:

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .dds_type_impls(true)
        .compile(&["idl/Robot.idl"])
}
participant.create_topic::<Robot>("entity.robot")?;

Das Impl trägt TYPE_NAME aus dem qualifizierten IDL-Namen, EXTENSIBILITY aus der Annotation, HAS_KEY und den PLAIN_CDR2-BE-Key-Holder aus den @key-Membern, den vollständigen TypeIdentifier und das TypeObject aus derselben Berechnung, die die Discovery nutzt, field_value für den SQL-Filter und alle vier Codec-Paare — XCDR2 und XCDR1, Little-Endian und Big-Endian — aus demselben Emitter unter vier Layout-Schlüsseln.

Es ist standardmäßig aus: Es bringt zerodds-dcps, zerodds-types und zerodds-wire in die [dependencies] des Nutzers, also die ganze DCPS-Laufzeit, und diese Crate wird auch von Nutzern verwendet, die den Codec wollen und gar kein DDS im Abhängigkeitsgraphen.

Wo XCDR1 einen Typ nicht rahmen kann, werden die vier XCDR1-Methoden weggelassen; es gelten die ablehnenden Standardimplementierungen des Traits, und ein Kommentar in der erzeugten Datei nennt den Typ. Sie werden nicht an den XCDR2-Codec delegiert: Das legte Oktette der Version 2 unter einen Encapsulation-Header CDR_LE/CDR_BE, und kein Peer könnte das von einem Sample unterscheiden, das er lesen soll.

Config

Methode von Config was sie setzt
include_dir(dir) ein Verzeichnis, in dem der Präprozessor nach #include sucht
define(name, value) ein Präprozessormakro, wie es -D NAME[=VALUE] setzen würde
out_dir(dir) wohin die erzeugten Dateien kommen (Standard: $OUT_DIR)
default_extensibility(ext) was ein nicht annotiertes Aggregat ist: Final, Appendable oder Mutable (Standard: Appendable, XTypes 1.3 §7.3.1.2.1.8)
typeobject(bool) das Modul type_objects_* mit den rohen Bytes der TypeObjects (Standard: an)
header_comment(text) der Kopfkommentar in der erzeugten Datei
type_identifier_constants(bool) eine Konstante zerodds_types::TypeIdentifier je Typ (Standard: aus)
emit_cargo_directives(bool) ob compile() cargo:rerun-if-changed ausgibt (Standard: an)
dds_type_impls(bool) impl zerodds_dcps::DdsType je Typ (Standard: aus)
dialect(Dialect) die Antworten eines Peers auf alle Wire-Achsen auf einmal nachbilden (Standard: Dialect::default(), die Spezifikation)
axis(AxisFlag, value) eine Antwort des Dialekts überschreiben; mehrere Aufrufe gelten in der angegebenen Reihenfolge
rust_type(idl_path, rust_type) ein Typedef, einen Struct-Member oder einen Union-Zweig als Rust-Typ halten, der zerodds_wire::WireRepr implementiert (unten)
rust_type_with(idl_path, rust_type, adapter) dasselbe über einen Adapter-Wert, der zerodds_wire::WireReprWith implementiert
strip_enum_prefix(bool) den Namen jeder Enumeration von den Rust-Namen ihrer Enumeratoren abschneiden (unten); Standard aus
rust_naming(RustNaming) das Namensschema: RustNaming::Idl (Standard, die IDL-Namen) oder RustNaming::Rust (RFC 430) (unten)

compile_bundle(idls, name) setzt mehrere Eingabedateien zu einem erzeugten Modul zusammen, wenn sie Deklarationen teilen. compile(idls) erzeugt eine Datei je Eingabe.

Dialekte und Achsen-Flags

Config::dialect und Config::axis entsprechen zerodds-idlc generate --dialect/--<axis> und wireprobe-zerodds --dialect/--<axis>, gelesen aus derselben Tabelle in zerodds-ast-layout und in derselben Reihenfolge angewandt: erst der Dialekt, dann jede Überschreibung einer Achse. docs/wire-axis-flags.md enthält die Antwort jedes Dialekts auf jede Achse und die Werte, die axis annimmt.

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .dialect(zerodds_ast_layout::Dialect::Cyclone)
        .axis(zerodds_ast_layout::AxisFlag::LengthCodes, "compact")
        .compile(&["idl/Robot.idl"])
}

Der Standard — kein Aufruf von dialect, keiner von axis — ist Dialect::default(), die Lesart der Spezifikation Klausel für Klausel. Ein unbekannter Achsenwert führt nicht zu einem Panic im Build: compile() und compile_bundle() geben Err(Error::Axis { flag, value, detail }) zurück und nennen den fehlerhaften Aufruf .axis(...).

Externe Speicherung

Erzeugtes Rust speichert @external T-Member in Box<T> und @optional @external T-Member in Option<Box<T>>. Dadurch wird ein optionaler Selbstverweis endlich, ohne seine Darstellung auf der Leitung zu ändern.

Ein Rust-Typ für einen IDL-Typ

Ein IDL-typedef string UtcTimestamp; ist im erzeugten Rust ein String, und ein Text, der kein Zeitstempel ist, ebenso. rust_type nennt einen Rust-Typ, der für ein Typedef, einen Struct-Member oder einen Union-Zweig steht, und der erzeugte Code hält dann diesen Typ (GitHub #33):

// build.rs
fn main() -> Result<(), zerodds_build::Error> {
    zerodds_build::Config::new()
        .rust_type("app::UtcTimestamp", "crate::time::UtcTimestamp")
        .rust_type("app::Track.id", "core::num::NonZeroU32")
        .rust_type_with("app::Track.source", "std::net::Ipv4Addr", "zerodds_wire::DisplayFromStr")
        .dds_type_impls(true)
        .compile(&["idl/app.idl"])
}
  • Der Pfad ist der qualifizierte IDL-Name: ein Typedef (app::UtcTimestamp), ein Struct-Member (app::Track.id) oder ein Union-Zweig (app::Choice.stamp). Die Abbildung eines Members geht der eines Typedefs vor, das sein Typ ist.
  • Der Rust-Typ implementiert zerodds_wire::WireRepr (zerodds-wire); dessen Idl ist die Rust-Schreibweise des IDL-Typs: str für einen string, u32 für einen unsigned long. zerodds-wire bringt die Implementierungen für core::num::NonZero*, String und Cow<'_, str> mit; ein Typ aus einer anderen Crate geht über einen Adapter (rust_type_with), zerodds_wire::DisplayFromStr für einen Typ mit Display + FromStr auf einem string. Der IDL-Typ ist ein string oder ein primitiver Typ außer wchar und long double.
  • Der erzeugte Typ hält den Rust-Typ überall, wo die Deklaration verwendet wird: als Member, als Element einer Sequenz, eines Arrays oder einer Map, als Union-Zweig, in Option für @optional, in Box für @external. Ein Typedef ist ein Alias dafür.
  • Kodieren schreibt den IDL-Wert über to_wire; Dekodieren liest ihn — einen string aus dem Sample geliehen, nicht kopiert — und wandelt über from_wire. Einen Wert, den der Rust-Typ ablehnt, weist das Sample mit diesem Grund zurück.
  • Die Oktette, das TypeObject, der TypeIdentifier, die Zuweisbarkeit und der Key-Hash bleiben die der IDL. Ein C- oder C++-Gegenüber, aus derselben IDL gebaut, liest dieselben Samples.
  • Ein Pfad, der kein Typedef, keinen Struct-Member und keinen Union-Zweig der übersetzten Einheiten nennt, eine Deklaration eines anderen IDL-Typs und ein Rust-Typ, der kein Typpfad ist, lassen den Build mit Error::RustType scheitern. Ein Rust-Typ, dessen Idl nicht der IDL-Typ ist, übersetzt nicht: Die erzeugte Datei hält jede Abbildung als zerodds_wire::repr::idl_type_is::<T, Idl>() fest.
  • Die erzeugten Typen leiten Debug, Clone und PartialEq ab; der Rust-Typ implementiert sie also. Ein Typ mit einem Member, dessen Rust-Typ den IDL-Default ablehnt (ein NonZeroU32 die Null), bekommt kein impl Default, und ein Sample, dem ein solcher Member fehlt — von einem älteren @appendable-Writer, ein Sample nur mit dem Key —, wird zurückgewiesen.

Das Beispiel rust-type zeigt eine Datum-Zeit-Gruppe, DDHHMMZMONYY, für einen IDL-string und einen NonZeroU32 für einen Key vom Typ uint32.

Rust-Namen

Das erzeugte Rust übernimmt als Standard die Namen der IDL, wie die OMG-Mappings für Java und C# (IDL4 to Java 1.0 und IDL4 to C# 1.0, §7.1.1); ein verabschiedetes IDL4-zu-Rust-Mapping gibt es nicht. Zwei Einstellungen ändern die Rust-Namen und nichts sonst: Das TypeObject, die Member-IDs, die registrierten Typnamen, ein Inhaltsfilter und die Pfade von rust_type lesen die IDL-Namen, und die Oktette auf der Leitung bleiben gleich.

zerodds_build::Config::new()
    .rust_naming(zerodds_build::RustNaming::Rust)
    .strip_enum_prefix(true)
    .compile(&["idl/sensor.idl"])?;

rust_naming(RustNaming::Rust) schreibt die Namen nach den Rust-API-Richtlinien (RFC 430):

IDLRust
Modul Sensor_Datapub mod sensor_data
Struct, Union, Enum, Bitset, Bitmask, Typedef, Exception reading_kind, HTTPReadingReadingKind, HttpReading
Member sensorIdFeld sensor_id
Enumerator READING_KIND_rawVariante ReadingKindRaw; Raw mit strip_enum_prefix(true)
Union-Zweig filtered_valueVariante FilteredValue
Konstante maxSamples, Bit flagReadyMAX_SAMPLES, FLAG_READY
Interface robot_arm, Operation moveTo, Parameter targetXTrait RobotArm, Methode move_to, Parameter target_x; RobotArmClient, RobotArmDispatcher, RobotArmError
die DDS-RPC-Typen robot_arm_moveTo_In, robot_arm_CallRobotArmMoveToIn, RobotArmCall; registriert unter den DDS-RPC-Namen
  • Ein Name wird an jedem _ in Wörter geteilt, außerdem dort, wo auf einen Kleinbuchstaben ein Großbuchstabe folgt, und vor dem letzten Buchstaben einer Folge von Großbuchstaben, auf den ein Kleinbuchstabe folgt. Ein Akronym ist ein Wort.
  • strip_enum_prefix(true) schneidet den Namen der Enumeration von ihren Enumeratoren ab, wie prost-build es als Standard tut: MY_ENUM_A von MyEnum ist A. Der Name wird ohne Rücksicht auf Groß- und Kleinschreibung und Unterstriche verglichen; abgeschnitten wird nur, wo ein gültiger Bezeichner bleibt (MY_ENUM_1 bleibt).
  • @rust_mapping(apply_naming_convention = RUST_NAMING_CONVENTION) oder IDL_NAMING_CONVENTION an einem Modul oder an einem Typ, einer Konstante, einer Exception oder einem Interface setzt das Schema für das, was diese Deklaration umschließt, über die Wahl des Builds. Ein Interface und seine Basis stehen unter einem Schema.
  • Zwei Deklarationen eines Scopes, die denselben Rust-Namen ergeben (my_field und myField), brechen den Build ab; die Meldung nennt beide.
  • Unter RustNaming::Rust braucht das Modul, das die erzeugte Datei einbindet, kein #[allow(non_snake_case)].

Ein Topic-Typ, in Rust definiert

Der andere Weg aus GitHub #33: Der Typ wird in Rust definiert, und seine IDL entsteht daraus, für C, C++ und andere Hersteller. derive(DdsType) aus zerodds-codec (Crate zerodds-derive) schreibt die Beschreibung des Typs, seinen Codec und seine DdsType-Implementierung:

use zerodds_codec::{DdsType, WireRepr};

#[derive(WireRepr)]
#[wire(idl = "string")] // liest über TryFrom<&str>, schreibt über Display
struct Dtg(DateTimeGroup);

#[derive(DdsType)]
#[dds(name = "app::Track", extensibility = "appendable")]
struct Track {
    #[dds(key)]
    id: NonZeroU32,    // unsigned long
    at: Dtg,           // string
    #[dds(bound = 64)]
    label: String,     // string<64>
    note: Option<String>, // @optional string
}

println!("{}", Track::idl()?); // die IDL, aus der ein C- oder C++-Gegenüber entsteht
  • Member-Typen: bool, die Ganzzahlen (u8 ist octet), f32, f64, char, String, core::num::NonZero*, ein WireRepr-Typ, Vec<T> (sequence), [T; N] (Array), Option<T> (@optional), ein abgeleitetes Struct, ein enum ohne Felder, std::time::Duration (DDS::Duration_t) und std::time::SystemTime (DDS::Time_t).
  • Attribute, nach den IDL-Annotationen: am Struct name, extensibility (Vorgabe appendable), autoid, nested, codec = "manual"; an einem Feld key, id, hashid, bound, name, optional, with (ein Adapter für einen Typ aus einer anderen Crate); an einem Enum name und bit_bound, an einer Variante name und value.
  • Die Beschreibung wird zu IDL, und diese IDL durchläuft das IDL-Frontend, den TypeObject-Aufbau und den Layoutplaner, die eine dieser Crate übergebene .idl-Datei durchläuft. Der abgeleitete Typ und der Typ, den diese Crate aus der gleichwertigen IDL erzeugt, haben dasselbe TypeObject, denselben TypeIdentifier und dieselben Oktette unter XCDR1 und XCDR2 in beiden Bytereihenfolgen; ein aus Track::idl() erzeugtes C-Gegenüber liest sie.
  • Einen Wert, den der Rust-Typ beim Dekodieren ablehnt, weist das Sample mit seinem Grund zurück. Der Key-Hash wird über den IDL-Wert berechnet.
  • Ein von Hand geschriebener Codec (DdsSerialize, DdsDeserialize, siehe zerodds-wire) wird beim Übersetzen gegen die Beschreibung geprüft.
  • Ein Enum, dessen Varianten Daten tragen, ist eine IDL-union. discriminator = "i16" nennt den Rust-Typ des Diskriminators (eine Ganzzahl, bool, char oder ein abgeleitetes Enum ohne Felder; ohne Angabe i32, also long). An einer Variante: case = 1 oder case = [2, 3], oder kein case für eins über dem höchsten Label davor; default; no_member an einer Variante V(D), die einen Diskriminator hält, den kein Fall nimmt; id, hashid, name, bound. Eine Variante V(T) hält den Zweig; ein Fall mit mehreren Labels und der default:-Fall sind V(D, T) und gehen mit dem Diskriminator hinaus, mit dem sie gelesen wurden. key am Enum macht den Diskriminator zum Key der Union (switch (@key D), DDS-XTypes 1.3 §7.2.2.4.4.4.8): als Topic-Typ hat die Union einen Key, und ihr Key-Holder ist der Diskriminator; als key-Feld einer Struct gehört nur ihr Diskriminator zu deren Key. Ein Inhaltsfilter nennt einen Zweig über den IDL-Namen seines Members und den Diskriminator als #discriminator (reading.#discriminator = 3 AND reading.kelvin > 290); ein Ausdruck, der einen Zweig nennt, den der Diskriminator nicht wählt, ist falsch (DDS-XTypes 1.4 Beta 1 §7.6.7.1).
  • Ein generischer Typ ist je Instanziierung ein eigener IDL-Typ. Sein Name ist eine Vorlage, in der {T} für den IDL-Typ des Arguments steht: Pair<T> ist Pair_{T}, sofern name nichts anderes sagt, und Pair<u32> ist Pair_unsigned_long, Pair<app::Point> Pair_app_Point. Jede Instanziierung hat ihr eigenes TypeObject und ihren eigenen TypeIdentifier.
  • Ein Feld darf aus dem empfangenen Sample leihen: &'a str, &'a [u8], Cow<'a, str>, Cow<'a, [u8]>. zerodds_codec::decode über &'de [u8] leiht sie aus den Bytes. Ein Typ mit geliehenem Feld hat keine DdsType-Implementierung: Ein DataReader liefert einen eigenständigen Wert, bis es den Loaned Take gibt.

Das Beispiel rust-derive definiert die Datum-Zeit-Gruppe, eine Union, ein generisches Paar und den Track in Rust, vergleicht ihre Oktette mit dem IDL-Weg und liest den Track über eine geliehene Sicht und in einem C-Gegenüber.

Noch nicht abgedeckt

Nur das Rust-Backend ist angebunden. Die Kompositionspipeline (zerodds-idl-compose) ist sprachunabhängig, und zerodds-lang-rules trägt die Regeln für jedes Ziel, das die CLI kennt; eine Crate nach Art von zerodds-build für eine andere Sprache riefe dasselbe compose() und den passenden Regelsatz auf.

Für einen nicht unterstützten Member gibt die Generierung einen Fehler zurück, statt ihn wegzulassen.