Crate vpp_plugin_api_gen 

Generate Rust code for VPP API files

A small Rust-based code generator that produces Rust bindings and helper scaffolding for VPP .api files for implementing VPP plugins. This crate can be run from a build script (see Builder) and emits both Rust source and a JSON representation of the parsed API.

Design rationale (why a Rust crate, not an extension to vppapigen.py)

• Insulation against upstream changes: integrating with vppapigen.py via code outside of the vpp repository like this would need to make the assumption that the vppapigen.py internal API doesn’t change in non-backwards-compatible ways which would be unreasonable to assume. Implementing the parser standalone avoids that issue, although it does now mean that any extensions to the API grammer used by plugins or their imports would need to be implemented here.
• Dependency control: shipping the generator as a crate avoids introducing an extra Python dependencies into build systems that cannot be expressed via crate dependencies.
• Robustness against environment: performing a cargo build when set into an unrelated Python venv could lead to spurious failures if the venv doesn’t have all of the Python dependencies needed by vppapigen.py. Implementing in Rust avoids that.

Parsing strategy: why PEG (Parsing Expression Grammar) over CFG

The implementation chooses a PEG-style parser (implemented in parser.rs) rather than a traditional context-free grammar (CFG) parser generator for several practical reasons:

• Determinism and simplicity: PEGs are deterministic and describe a single unambiguous parse for any input (given the grammar and choice ordering). For the .api format — which is relatively small, regular and unambiguous — a PEG results in simpler grammars and parsing code without needing extra disambiguation rules.
• Ergonomics in Rust: mature PEG libraries and small hand-written PEG parsers are straightforward to implement and embed in a Rust crate. CFG tools (LR, LALR) are typically geared toward generating parser tables and a runtime which is less ergonomic to integrate into a small generator crate and tends to complicate error reporting and tooling.
• Better error locality: PEGs (and hand-written recursive-descent parsers) make it easier to attach localized error messages and recover cleanly for diagnostics or partial parsing.

Trade-offs and caveats:

• PEG grammars do not support left-recursive rules naturally. For the .api grammar this is not a practical limitation because the syntax is not left-recursive and is well-suited to a PEG style.
• CFG-based parser generators can handle certain ambiguous grammars more naturally and can produce more compact parser tables for very large and complex grammars. Here, the space of constructs is small and well-bounded, so the simplicity and determinism of PEG were preferred.

Structs

Builder

Generate Rust code for the VPP handling of APIs of from a .api file

Enums

Error

Errors that can occur during API file parsing and code generation