Generator Overview

Generator Overview

What serpgen Covers So You Don't Have To

serpgen turns architecture specs into deterministic infrastructure, so humans and AI do not hand-write the fragile glue around a distributed C++ system.

The generator takes responsibility for everything that can be derived from specs: transport adapters, proxy/stub classes, process entry points, CMake wiring, service registration, and lifecycle configs. This leaves only business logic — the high-variability, spec-resistant part — for humans and AI to implement. AI sessions operate exclusively in this space, in bounded impl files, with clear interface contracts to work from. See AI-Driven Development.

In ordinary AI coding, the model may need to infer where IPC ends, where lifecycle begins, and which files are safe to edit. In SERP, those boundaries are generated and enforced. serpgen is what makes the architecture executable.

---

serpgen reads SerpIDL specs, builds an intermediate representation (IR), validates it, and drives a set of plugins to produce C++ source files, CMake build files, and deployment supervisor configurations.

Pipeline

Spec Files → Contract Loaders → SerpIR (Intermediate Representation) → IR Validator → Code Generators → C++ Output

1. Contract Loaders — IDL parser plugins read *.sidl.yaml and .sidl files and populate the IR.
2. SerpIR — a unified in-memory model of all interfaces, services, and deployments across the workspace.
3. IR Validator — checks type references, version consistency, and structural rules before any code is written.
4. Code Generators — IPC backend plugins, lifecycle plugins, and the core C++ generator write output to gen/.

CLI Reference

Validate specs (no generation)

serpgen validate -w specs/serp.sidl

Runs the full load and validation pass without writing any files. Use in CI and before committing spec changes. Exits non-zero on any error.

Generate all code for all deployments

serpgen generate-workspace -w specs/serp.sidl

Regenerates the entire gen/ directory: interfaces, base classes, deployment main.cpp files, CMakeLists.txt files, and lifecycle configs. Safe to run at any time — everything under gen/ is disposable.

Dump IR as JSON

serpgen dump-ir -w specs/serp.sidl -o ir.json

Writes the resolved intermediate representation to ir.json. Use this to inspect what serpgen sees after loading and cross-referencing all specs — helpful for debugging unexpected output or understanding type resolution.

Create a new project from template

serpgen template calculator_console myproject

Scaffolds a new project named myproject from the calculator_console template. The resulting project has a complete specs/ layout, a starter service, and a working CMakeLists.txt.

Generate deployments only

serpgen generate-deployments -w specs/serp.sidl -d multiprocess_dbus

Regenerates only the specified deployment (process main.cpp files, CMakeLists.txt, and lifecycle configs) without touching interface or service generated code. Useful when you have changed only the deployment spec.

What serpgen Generates

Interface and Service Code

For each service defined in a service spec:

gen/components/<Component>/src/services/<Service>/
  I<Service>.hpp               # Typed interface — abstract, defines all methods/props/notifications
  impl/
    <Service>Base.hpp          # Generated base class — wires handlers, injects dependencies
    <Service>Base.cpp
    <Service>.hpp              # Default implementation stub (generated once)
    <Service>.cpp

The stub files (<Service>.hpp/.cpp) are generated once if they do not exist. After that, serpgen does not overwrite them. The Base files are always regenerated.

Deployment Code

For each process in a deployment:

gen/deployments/<deployment>/<process>/
  main.cpp                     # Process entry point: instantiates services, inits transport, calls app.run()
  CMakeLists.txt               # Build target for this process executable
gen/deployments/<deployment>/lifecycle/
  <process>.service            # systemd unit file (if launcher: systemd)
  <process>.rc                 # Android Init config (if launcher: android_init)

Plugin System

serpgen uses a plugin registry. All IDL parsers, IPC backends, and lifecycle generators are plugins — including the built-in ones.

Built-in Plugins

Category	Plugin name	Description
IDL parser	serp_idl_sidl	SerpIDL (.sidl.yaml / .sidl) — default
IDL parser	serp_idl_fidl	FIDL (Franca IDL) — legacy projects
IPC backend	serp_ipc_inprocess	Direct shared_ptr dispatch (monolith)
IPC backend	serp_ipc_dbus	DBus transport via sdbus-c++
IPC backend	serp_ipc_grpc	gRPC transport
IPC backend	serp_ipc_posix	POSIX Unix Domain Sockets (no external deps)
Lifecycle	serp_lifecycle_systemd	systemd .service unit files
Lifecycle	serp_lifecycle_initd	Traditional init.d scripts
Lifecycle	serp_lifecycle_android_init	Android .rc init files
HMI	serp_hmi_qt_binding	Qt property binding generation
AAOS integration	serp_aaos	Android Automotive VHAL — VehicleHardwareAdapter, SerpVehicleService, VINTF manifest, and NDK build config

Custom Plugins

Custom plugins register themselves with the serpgen plugin registry:

registry.register_ipc(name, generator_func);
registry.register_lifecycle(name, generator_func);
registry.register_idl(name, loader_func);

Related Pages

• SerpIDL Overview — spec file types and directory layout
• Workspace Root — the -w entry point for all commands
• Generated Code Layout — full directory structure of gen/
• CMake Integration — using generated CMakeLists.txt files