Skip to content

Architecture

This document describes the end-to-end flow from IDL source to generated code, and the main components in this repository. The diagram file is available at docs/architecture/architecture.excalidraw if you prefer a visual map.

Pipeline overview

Kroki

What each stage means

  • source: raw IDL text.
  • ast: tree-sitter-idl parse tree with full syntactic detail.
  • typed_ast: AST with typed nodes mapped to Rust enums/structs.
  • hir: high-level, flattened structures suited for generation.
  • generator: codegen backends that emit C/C++/Rust (or other targets).

Core crates and responsibilities

  • tree-sitter-idl: grammar and queries for parsing and editor tooling.
  • xidl-parser: parsing + typed AST + HIR transformations.
  • xidl-derive: derive helpers used by typed AST.
  • xidlc: compiler CLI, driver, and code generation orchestration.
  • xidl-jsonrpc: JSON-RPC transport types used by the JSON-RPC target.
  • xidl-xcdr: CDR and related runtime support for generated code.
  • xidl-typeobject: IDL typeobject implementation.

xidl compiler flow

The compiler driver coordinates the parse, transform, and generation steps. For example, a Rust JSON-RPC target flows like this:

Kroki

Design notes

  • typed_ast uses derived helpers for most nodes, and manual impls where needed.
  • HIR favors fewer, flatter types to simplify generation.
  • Generators should depend on HIR, not on tree-sitter or typed_ast.