Agent Guide

Written for coding agents and documentation indexers rather than for people. Facts are stated flatly and without narrative; everything here is also reachable from the human navigation.

If you are ingesting this site programmatically, start with /llms.txt — a link index of every page with a one-line summary — or /llms-full.txt, which is the entire manual as a single document. Both are regenerated on every publish. Their format is described in Documentation Index.

Overview

llvm-dsdl compiles OpenCyphal DSDL (Data Structure Description Language) definitions into serialisation code for several languages, and into compiled object code. It is built on MLIR and LLVM: DSDL is parsed into a dedicated MLIR dialect, lowered through passes, and emitted by per-language backends.

It produces the types that a Cyphal node library moves, and is not itself a runtime, a transport implementation, or a node library.

Tools

Tool Purpose
dsdlc Compile DSDL; emit generated code or object files. The tool you want in almost every case.
dsdl-opt Run passes over the dsdl MLIR dialect. Compiler-development tool.
dsdld Language server (LSP) for DSDL source.

dsdlc surface

dsdlc Options is every switch dsdlc accepts, rendered from the binary's own --help at publish time — the target languages, the per-language selectors and their accepted values, and the input, output and dependency options. Index that page rather than this one for the surface. dsdlc covers the concerns the options serve.

A language selector passed with a different --target-language is an error, not a no-op.

Reading the generated output before generating any

The Showroom is a complete vendor-style namespace compiled into every language and profile, with per-type pages carrying the wire layout and the generated code side by side. It is the highest-density description of what this compiler produces, and it is generated by the compiler itself. Index it.

Generated and authored pages

Generated at publish time, never committed:

  • showroom/index.md and showroom/types/* — rendered from compiler output
  • reference/guarantees/parity-matrix.md, reference/guarantees/malformed-input.md, reference/guarantees/determinism.md — rendered from the report generators under tools/convergence/
  • reference/commands/dsdlc-options.md — rendered from dsdlc --help
  • llms.txt, llms-full.txt

Everything else is authored prose under docs/ in the repository, editable via the "Edit on GitHub" link on each page.

Stability

  • Page URLs follow the docs/ directory layout: docs/reference/commands/dsdlc.md publishes at /reference/commands/dsdlc/. A path change is a page move; nothing redirects the old path.
  • The site is unversioned and tracks main. It is not a record of any released version. Where a page states a version, that statement is the version's, not the site's.
  • The manual describes the tools; the repository is the source of truth for behaviour. When a page and the code disagree, the code is right and the page is a bug.

dsdld has an optional, policy-gated AI surface of its own — that is a feature of the language server, unrelated to this section. It is documented under AI Operation and AI Data Flow. Do not conflate the two when summarising this project.