Spec First Workflow

Spec-First Workflow

The recommended development cycle in SERP puts the interface contract first. Everything else — generated code, implementations, tests — follows from the spec.

Define Interface (SerpIDL) → Validate → Generate → Implement → Test → Repeat

---

Step-by-Step

1. Write or update the interface contract

File: specs/interfaces/IMyService.sidl.yaml

Define methods, attributes, broadcasts, and types. The interface is the contract between the service and its callers — keep it stable, because changes ripple to all callers.

2. Validate

serpgen validate -w specs/serp.sidl

Catches IDL errors, unknown types, and circular dependencies before any code is touched. Also available in VS Code: Ctrl+Option+V.

3. Generate

serpgen generate-workspace -w specs/serp.sidl

Updates the gen/ directory: interfaces, base classes, process mains, and adapters. It never overwrites files in src/. Safe to run at any time.

4. Implement

Edit src/components/<Group>/<Service>/<Service>Impl.cpp.

Your handler is called by the generated base class. If the handler signature does not match the interface, you get a compile error — the generator enforces the contract at build time.

5. Build

cmake --build build/

Or use the VS Code shortcut: Ctrl+Option+B.

6. Test

• Component tests: serp::TestRunner + GTest — mock dependencies, drive lifecycle, assert results
• Integration: run the full deployment and exercise the system end-to-end

7. Repeat

Add a method to the interface → validate → generate → the compiler shows you exactly what to implement.
Remove a method → generate → the compiler tells you what to clean up.

---

Key Disciplines

Rule	Reason
Specs are the source of truth	When in doubt, update the spec first
Treat gen/ as build output	Never edit generated files — your changes will be overwritten
Keep src/ clean	Only business logic; no transport or IPC code belongs here
Commit specs/ and src/	gen/ can be gitignored and regenerated on checkout

---

Multiprocess Development Flow

1. Start with a monolith deployment (inprocess, single binary) — easiest to debug, no transport overhead
2. Once the logic is working, switch to multiprocess by changing the deployment spec — no service code changes required
3. Use the Runtime Inspector (Dev gRPC/DBus profile) for live method testing while the system is running

---

Regeneration Is Safe

serpgen tracks which files are user-owned. Running generate again will not touch anything under src/. The only file that is always overwritten is the generated main.cpp — do not put custom code there.