zerodds-build
A
build.rshelper for ZeroDDS IDL: one Rust module per.idl, with#includedependency tracking so cargo re-runs when a header changes.
- Source: crates/zerodds-build
- API docs: docs.rs/zerodds-build
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), whoseIdlis the IDL type's Rust spelling:strfor astring,u32for anunsigned long.zerodds-wirecarries the impls forcore::num::NonZero*,StringandCow<'_, str>; a type from another crate goes through an adapter (rust_type_with),zerodds_wire::DisplayFromStrfor aDisplay + FromStrtype on astring. The IDL type is astringor a primitive other thanwcharandlong double. - The generated type holds the Rust type wherever the declaration is used: a member, a sequence, array or map element, a union branch,
Optionfor@optional,Boxfor@external. A typedef is an alias of it. - Encode writes the IDL value through
to_wire; decode reads it — astringlent out of the sample, not copied — and converts throughfrom_wire. A value the Rust type refuses rejects the sample with that reason. - The octets, the
TypeObject, theTypeIdentifier, 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 whoseIdlis not the IDL type fails to compile: the generated file states every mapping aszerodds_wire::repr::idl_type_is::<T, Idl>(). - The generated types derive
Debug,CloneandPartialEq, so the Rust type implements them. A type with a member whose Rust type refuses the IDL default (aNonZeroU32for the default zero) gets noimpl Default, and a sample that leaves such a member out — an older@appendablewriter, 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):
| IDL | Rust |
|---|---|
module Sensor_Data | pub mod sensor_data |
struct, union, enum, bit set, bit mask, typedef, exception reading_kind, HTTPReading | ReadingKind, HttpReading |
member sensorId | field sensor_id |
enumerator READING_KIND_raw | variant ReadingKindRaw; Raw with strip_enum_prefix(true) |
union branch filtered_value | variant FilteredValue |
constant maxSamples, bit flagReady | MAX_SAMPLES, FLAG_READY |
interface robot_arm, operation moveTo, parameter targetX | trait RobotArm, method move_to, parameter target_x; RobotArmClient, RobotArmDispatcher, RobotArmError |
the DDS-RPC types robot_arm_moveTo_In, robot_arm_Call | RobotArmMoveToIn, 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, asprost-builddoes by default:MY_ENUM_AofMyEnumisA. The name matches without regard to case and underscores; it is cut only where a valid identifier is left (MY_ENUM_1stays).@rust_mapping(apply_naming_convention = RUST_NAMING_CONVENTION)orIDL_NAMING_CONVENTIONon 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_fieldandmyField) fail the build and name both. - Under
RustNaming::Rustthe 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 (u8isoctet),f32,f64,char,String,core::num::NonZero*, aWireReprtype,Vec<T>(sequence),[T; N](array),Option<T>(@optional), a derived struct, a field-lessenum,std::time::Duration(DDS::Duration_t) andstd::time::SystemTime(DDS::Time_t). - Attributes, after the IDL annotations: on the struct
name,extensibility(defaultappendable),autoid,nested,codec = "manual"; on a fieldkey,id,hashid,bound,name,optional,with(an adapter for a type from another crate); on an enumnameandbit_bound, on a variantnameandvalue. - The description becomes IDL, and that IDL goes through the IDL front end, the
TypeObjectbuilder and the layout planner a.idlfile given to this crate goes through. The derived type and the type this crate generates from the equivalent IDL have the sameTypeObject, the sameTypeIdentifierand the same octets under XCDR1 and XCDR2 in both byte orders; a C peer generated fromTrack::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, seezerodds-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,charor a derived field-less enum;i32,long, when not given). On a variant:case = 1orcase = [2, 3], or nocasefor one past the highest label before it;default;no_memberon a variantV(D)that holds a discriminator no case takes;id,hashid,name,bound. A variantV(T)holds the branch member; a case with several labels and thedefault:case areV(D, T)and go out again under the discriminator they were read with.keyon 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 akeyfield 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>isPair_{T}unlessnamesays otherwise, andPair<u32>isPair_unsigned_long,Pair<app::Point>Pair_app_Point. Each instantiation has its ownTypeObjectandTypeIdentifier. - A field may borrow from the received sample:
&'a str,&'a [u8],Cow<'a, str>,Cow<'a, [u8]>.zerodds_codec::decodeover&'de [u8]lends them out of the bytes. A type with a borrowed field has noDdsTypeimpl: aDataReadertakes 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.rsfür ZeroDDS-IDL: ein Rust-Modul je.idl, mit Verfolgung der#include-Abhängigkeiten, damit cargo neu baut, wenn sich ein Header ändert.
- Quelle: crates/zerodds-build
- API-Docs: docs.rs/zerodds-build
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); dessenIdlist die Rust-Schreibweise des IDL-Typs:strfür einenstring,u32für einenunsigned long.zerodds-wirebringt die Implementierungen fürcore::num::NonZero*,StringundCow<'_, str>mit; ein Typ aus einer anderen Crate geht über einen Adapter (rust_type_with),zerodds_wire::DisplayFromStrfür einen Typ mitDisplay + FromStrauf einemstring. Der IDL-Typ ist einstringoder ein primitiver Typ außerwcharundlong 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
Optionfür@optional, inBoxfür@external. Ein Typedef ist ein Alias dafür. - Kodieren schreibt den IDL-Wert über
to_wire; Dekodieren liest ihn — einenstringaus dem Sample geliehen, nicht kopiert — und wandelt überfrom_wire. Einen Wert, den der Rust-Typ ablehnt, weist das Sample mit diesem Grund zurück. - Die Oktette, das
TypeObject, derTypeIdentifier, 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::RustTypescheitern. Ein Rust-Typ, dessenIdlnicht der IDL-Typ ist, übersetzt nicht: Die erzeugte Datei hält jede Abbildung alszerodds_wire::repr::idl_type_is::<T, Idl>()fest. - Die erzeugten Typen leiten
Debug,CloneundPartialEqab; der Rust-Typ implementiert sie also. Ein Typ mit einem Member, dessen Rust-Typ den IDL-Default ablehnt (einNonZeroU32die Null), bekommt keinimpl 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):
| IDL | Rust |
|---|---|
Modul Sensor_Data | pub mod sensor_data |
Struct, Union, Enum, Bitset, Bitmask, Typedef, Exception reading_kind, HTTPReading | ReadingKind, HttpReading |
Member sensorId | Feld sensor_id |
Enumerator READING_KIND_raw | Variante ReadingKindRaw; Raw mit strip_enum_prefix(true) |
Union-Zweig filtered_value | Variante FilteredValue |
Konstante maxSamples, Bit flagReady | MAX_SAMPLES, FLAG_READY |
Interface robot_arm, Operation moveTo, Parameter targetX | Trait RobotArm, Methode move_to, Parameter target_x; RobotArmClient, RobotArmDispatcher, RobotArmError |
die DDS-RPC-Typen robot_arm_moveTo_In, robot_arm_Call | RobotArmMoveToIn, 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, wieprost-buildes als Standard tut:MY_ENUM_AvonMyEnumistA. Der Name wird ohne Rücksicht auf Groß- und Kleinschreibung und Unterstriche verglichen; abgeschnitten wird nur, wo ein gültiger Bezeichner bleibt (MY_ENUM_1bleibt).@rust_mapping(apply_naming_convention = RUST_NAMING_CONVENTION)oderIDL_NAMING_CONVENTIONan 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_fieldundmyField), brechen den Build ab; die Meldung nennt beide. - Unter
RustNaming::Rustbraucht 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 (u8istoctet),f32,f64,char,String,core::num::NonZero*, einWireRepr-Typ,Vec<T>(sequence),[T; N](Array),Option<T>(@optional), ein abgeleitetes Struct, einenumohne Felder,std::time::Duration(DDS::Duration_t) undstd::time::SystemTime(DDS::Time_t). - Attribute, nach den IDL-Annotationen: am Struct
name,extensibility(Vorgabeappendable),autoid,nested,codec = "manual"; an einem Feldkey,id,hashid,bound,name,optional,with(ein Adapter für einen Typ aus einer anderen Crate); an einem Enumnameundbit_bound, an einer Variantenameundvalue. - 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 dasselbeTypeObject, denselbenTypeIdentifierund dieselben Oktette unter XCDR1 und XCDR2 in beiden Bytereihenfolgen; ein ausTrack::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, siehezerodds-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,charoder ein abgeleitetes Enum ohne Felder; ohne Angabei32, alsolong). An einer Variante:case = 1odercase = [2, 3], oder keincasefür eins über dem höchsten Label davor;default;no_memberan einer VarianteV(D), die einen Diskriminator hält, den kein Fall nimmt;id,hashid,name,bound. Eine VarianteV(T)hält den Zweig; ein Fall mit mehreren Labels und derdefault:-Fall sindV(D, T)und gehen mit dem Diskriminator hinaus, mit dem sie gelesen wurden.keyam 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; alskey-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>istPair_{T}, sofernnamenichts anderes sagt, undPair<u32>istPair_unsigned_long,Pair<app::Point>Pair_app_Point. Jede Instanziierung hat ihr eigenesTypeObjectund ihren eigenenTypeIdentifier. - 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 keineDdsType-Implementierung: EinDataReaderliefert 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.