Quick Start

Quick Start

This guide takes you from a fresh machine to a running generated SERP service in about 15 minutes.

---

Prerequisites

• macOS or Linux (Ubuntu 20.04+ / Debian 11+)
• CMake ≥ 3.16
• C++17 compiler (clang++ or g++)
• serpgen — installed as part of the serp-dev package

---

Step 1: Install SERP Tooling

Install serp-dev using the platform instructions in Installation. It provides the SERP headers, CMake package, serpgen, test engine, and runtime debug adapters.

Verify the install:

serpgen --version

---

Step 2: Create a Workspace from Template

serpgen ships with project templates. The calculator_console template creates a minimal two-service workspace — a Calculator service and a console client — wired up and ready to build.

serpgen template calculator_console myapp
cd myapp

The generated workspace layout:

myapp/
├── specs/
│   └── serp.sidl          # SerpIDL specification (edit this)
├── src/
│   └── components/        # Your implementation code lives here
│       └── calculator/
│           └── CalculatorImpl.cpp
├── gen/                   # Generated — do not edit by hand
├── CMakeLists.txt
└── build/

---

Step 3: Validate the Specs

Before generating, check that the spec parses cleanly:

serpgen validate -w specs/serp.sidl

A clean spec prints no errors. Fix any reported issues before proceeding.

---

Step 4: Generate Code

serpgen generate-workspace -w specs/serp.sidl

This writes (or overwrites) everything under gen/:

• gen/interfaces/ — pure virtual ICalculator.h and similar
• gen/base/ — CalculatorBase.h/.cpp (dispatch, serialization wiring)
• gen/services/ — Calculator.h/.cpp (default stub, generated once)
• gen/mains/ — main_monolith.cpp and per-process entry points
• gen/adapters/ — transport glue

---

Step 5: Build

Configure and build the monolith target:

cmake -S . -B build/monolith -DCMAKE_BUILD_TYPE=Debug
cmake --build build/monolith --parallel

The monolith target runs all services in a single process using the inprocess transport — the fastest path for development.

---

Step 6: Run

./build/monolith/myapp_monolith

You should see the console client connect to the Calculator service and execute the demo calls defined in the template.

---

Step 7: Implement Business Logic

Open the implementation stub for the service you want to fill in:

src/components/calculator/CalculatorImpl.cpp

The stub contains empty method handlers that match the interface defined in specs/serp.sidl. For example:

// In CalculatorImpl.cpp — generated stub, ready to fill in
void CalculatorImpl::add(int32_t a, int32_t b, AddCallback callback)
{
    // TODO: implement
    callback(a + b);
}

Replace the // TODO body with real logic. The method signature and callback type are generated from the spec and must not be changed by hand — change the spec instead, then regenerate.

---

The Edit → Regenerate → Rebuild Cycle

After changing specs/serp.sidl (adding methods, updating types, etc.):

# 1. Validate
serpgen validate -w specs/serp.sidl

# 2. Regenerate
serpgen generate-workspace -w specs/serp.sidl

# 3. Rebuild
cmake --build build/monolith --parallel

# 4. Run
./build/monolith/myapp_monolith

Important: Files in gen/ are always regenerated and any manual edits there will be lost. Files in src/ are never touched by serpgen — your implementation code survives every regeneration.

---

Next Steps

• Read Core Concepts for the mental model behind services, transports, and code generation.
• Read SerpIDL Overview to learn how to write and extend interface specs.
• Check out serp-demo for a more complete example workspace.