Workspace Root

Workspace Root

The serp.sidl file is the project entry point for serpgen. Every serpgen command takes a -w argument pointing at this file. It names the project, declares where specs live, and lists the deployments to generate.

Format

root:
  version:
    major: 1
    minor: 0
  name: MyProject
  namespace: com.mycompany.myproject

interface_dirs:
  - specs/interfaces
  - specs/common

service_dirs:
  - specs/services

deployments:
  - specs/deployments/monolith.sidl
  - specs/deployments/multiprocess_dbus.sidl

paths:
  src: src
  gen: gen
  scripts: scripts
  tests: tests
  build: build

Field Reference

root

Field	Description
root.name	Project name. Used in generated code namespaces and CMake target names.
root.namespace	C++ namespace prefix applied to all generated code (e.g. com.mycompany.myproject).
root.version.major	Breaking change version for the project as a whole.
root.version.minor	Backwards-compatible version increment.

interface_dirs

A list of directories that serpgen scans recursively for *.sidl.yaml / *.sidl.yml files. Both interface contracts and shared common type files go here.

interface_dirs:
  - specs/interfaces    # service interface contracts
  - specs/common        # shared enums and structs

service_dirs

A list of directories serpgen scans for service spec *.sidl files (not to be confused with interface files).

service_dirs:
  - specs/services

deployments

An explicit list of deployment spec files. Unlike interface_dirs and service_dirs, this is not a directory scan — each deployment file is listed individually so the set of generated deployments is explicit and predictable.

deployments:
  - specs/deployments/monolith.sidl
  - specs/deployments/multiprocess_dbus.sidl
  - specs/deployments/multiprocess_grpc.sidl

paths

Overrides for the directory layout serpgen uses for input and output. The defaults match the conventional project structure, so this section is optional unless you need a non-standard layout.

Key	Default	Description
src	src	User-owned source directory (never written by serpgen)
gen	gen	Generated code output directory
scripts	scripts	Build and run scripts
tests	tests	Test code
build	build	CMake build output

Common serpgen Commands

Validate all specs without generating any code:

serpgen validate -w specs/serp.sidl

Run this in CI or before committing spec changes. It catches type mismatches, missing references, and malformed YAML.

Generate code for all deployments:

serpgen generate-workspace -w specs/serp.sidl

Regenerates everything under gen/. Safe to run at any time — gen/ is disposable.

Dump the intermediate representation as JSON:

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

Useful for inspecting what serpgen sees after loading and resolving all specs. Helpful when debugging unexpected generation output.

Related Pages

• SerpIDL Overview — file types and directory conventions
• Interface Specs — interface contract format
• Service Specs — service declaration format
• Deployment Specs — process and transport config
• Generator Overview — full serpgen CLI reference