hdds_gen CLI Reference

Global Options

idl-gen [OPTIONS] <COMMAND>

Options:
  -h, --help     Print help
  -V, --version  Print version (0.2.0)

Commands

gen - Generate Code

Generate type support code in a target language.

idl-gen gen [OPTIONS] <LANG> <INPUT>

Arguments:
  <LANG>   Target language: rust, cpp, c, python, micro, c-micro
  <INPUT>  Input IDL file path (or '-' for stdin)

Options:
  -I, --include <DIR>           Include directory for #include resolution (repeatable)
  -o, --out <FILE>              Output file (stdout if omitted)
  --out-dir <DIR>               Output directory (writes mod.rs for Rust)
  --namespace-cpp <NS>          Wrap C++ in namespace (e.g., "MyApp::Types")
  --example                     Generate full example project
  --build-system <SYS>          Build system: cargo, cmake, make
  --hdds-path <PATH>            Path to hdds crate (default: crates.io)

Examples:

# Basic generation
idl-gen gen rust types.idl -o types.rs
idl-gen gen cpp types.idl -o types.hpp

# With includes
idl-gen gen rust -I ./common -I /opt/idl types.idl -o types.rs

# C++ with namespace
idl-gen gen cpp types.idl --namespace-cpp "DDS::Types" -o types.hpp

# Full project with Cargo.toml
idl-gen gen rust types.idl --example --out-dir ./my_project

# Python module
idl-gen gen python types.idl --out-dir ./generated

# Embedded Rust (no_std)
idl-gen gen micro types.idl --example --out-dir ./embedded

parse - Validate and Inspect

Parse IDL files and optionally display the AST.

idl-gen parse [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input IDL file path (or '-' for stdin)

Options:
  -I, --include <DIR>  Include directories
  --pretty             Pretty-print the parsed AST
  --json               Output JSON diagnostics

Examples:

# Validate only
idl-gen parse types.idl

# Pretty-print AST
idl-gen parse types.idl --pretty

# JSON output for CI
idl-gen parse types.idl --json

check - Structural Validation

Validate IDL with comprehensive structural checks. Returns non-zero exit code on error.

idl-gen check [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input IDL file path (or '-' for stdin)

Options:
  -I, --include <DIR>  Include directories
  --json               Output JSON diagnostics

Validation Checks:

• Bitset @bit_bound constraints
• Non-overlapping bit fields
• Annotation placement rules
• @autoid and @id uniqueness
• Enum variant duplicates
• Type resolution and FQN validation

Examples:

# CI validation
idl-gen check types.idl --json || exit 1

# Validate with includes
idl-gen check -I ./common types.idl

fmt - Format IDL

Reformat IDL to canonical style.

idl-gen fmt [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input IDL file path (or '-' for stdin)

Options:
  -I, --include <DIR>  Include directories
  -o, --out <FILE>     Output file (stdout if omitted)

Examples:

# Format to stdout
idl-gen fmt types.idl

# Format in place
idl-gen fmt types.idl -o types.idl

# Check formatting (CI)
idl-gen fmt types.idl | diff - types.idl

Build System Options

When using --example, the generated project includes build configuration:

Language	Default Build System	Alternatives
rust	cargo	-
cpp	cmake	make
c	make	cmake
python	-	-
micro	cargo	-
c-micro	make	-

# Rust with Cargo (default)
idl-gen gen rust types.idl --example --out-dir ./project

# C++ with CMake (default)
idl-gen gen cpp types.idl --example --out-dir ./project

# C++ with Makefile
idl-gen gen cpp types.idl --example --build-system make --out-dir ./project

Exit Codes

Code	Meaning
0	Success
1	Parse error
2	Validation error
3	I/O error
4	Internal error

Environment Variables

Variable	Purpose
IDL_GEN_INCLUDE_PATH	Default include paths (colon-separated)

Piping and Stdin

All commands accept - for stdin:

# Pipe from another command
cat types.idl | idl-gen gen rust - -o types.rs

# Here-doc
idl-gen gen rust - -o types.rs << 'EOF'
struct Point {
    float x;
    float y;
};
EOF