ContextQMD
Back to Spacetimedb

C++ Quickstart

docs/docs/00100-intro/00200-quickstarts/00700-cpp.md

2.8.33.8 KB
Original Source

import { InstallCardLink } from "@site/src/components/InstallCardLink"; import { StepByStep, Step, StepText, StepCode } from "@site/src/components/Steps";

Get a SpacetimeDB C++ app running in under 5 minutes.

Prerequisites

  • SpacetimeDB CLI installed
  • Emscripten SDK 4.0.21+ installed
  • CMake 3.20+ and a make/ninja backend
  • C++20 toolchain (host) — build targets WASM via Emscripten

After installing the SDK, run the appropriate emsdk_env script (PowerShell or Bash) so emcc and the CMake toolchain file are available on PATH.

<InstallCardLink />
<StepByStep> <Step title="Install Emscripten"> <StepText> Use the official SDK (see [Emscripten downloads](https://emscripten.org/docs/getting_started/downloads.html)) and activate the environment so `emcc` and the CMake toolchain file are on PATH. We recommend Emscripten 4.0.21+. </StepText> <StepCode> ```bash # From your emsdk directory (after downloading/cloning) # Windows PowerShell ./emsdk install 4.0.21 ./emsdk activate 4.0.21 ./emsdk_env.ps1

macOS/Linux

./emsdk install 4.0.21 ./emsdk activate 4.0.21 source ./emsdk_env.sh

    </StepCode>
  </Step>

  <Step title="Create your project">
    <StepText>
      Use the CLI-managed workflow with `spacetime build`, which wraps CMake + `emcc` for you, starts the local server, builds/publishes your module, and generates client bindings.
    </StepText>
    <StepCode>
```bash
spacetime dev --template basic-cpp

</StepCode>
<StepText>
  Need manual control? You can still drive CMake+emcc directly (see `spacetimedb/CMakeLists.txt`), but the recommended path is `spacetime build`/`spacetime dev`.
</StepText>
</Step> <Step title="Explore the project structure"> <StepText> Server code lives in the `spacetimedb` folder; the template uses CMake and the SpacetimeDB C++ SDK. </StepText> <StepCode> ``` my-spacetime-app/ ├── spacetimedb/ # Your C++ module │ ├── CMakeLists.txt │ └── src/ │ └── lib.cpp # Server-side logic ├── Cargo.toml └── src/ └── main.rs # Rust client application ``` </StepCode> </Step> <Step title="Understand tables and reducers"> <StepText> The template includes a `Person` table and two reducers: `add` to insert, `say_hello` to iterate and log. </StepText> <StepCode> ```cpp #include "spacetimedb.h" using namespace SpacetimeDB;

struct Person { std::string name; }; SPACETIMEDB_STRUCT(Person, name) SPACETIMEDB_TABLE(Person, person, Public)

SPACETIMEDB_REDUCER(add, ReducerContext ctx, std::string name) { ctx.db[person].insert(Person{name}); return Ok(); }

SPACETIMEDB_REDUCER(say_hello, ReducerContext ctx) { for (const auto& person : ctx.db[person]) { LOG_INFO("Hello, " + person.name + "!"); } LOG_INFO("Hello, World!"); return Ok(); }

    </StepCode>
  </Step>

  <Step title="Test with the CLI">
    <StepText>
      Open a new terminal and navigate to your project directory. Then call reducers and inspect data right from the CLI.
    </StepText>
    <StepCode>
```bash
cd my-spacetime-app

# Insert a person
spacetime call add Alice

# Query the person table
spacetime sql "SELECT * FROM person"

# Call say_hello to greet everyone
spacetime call say_hello

# View the module logs
spacetime logs

</StepCode>
</Step> </StepByStep>

Notes

  • To use a local SDK clone instead of the fetched archive, set SPACETIMEDB_CPP_SDK_DIR before running spacetime dev/spacetime build.
  • The template builds to WebAssembly with exceptions disabled (-fno-exceptions).
  • If emcc is not found, re-run the appropriate emsdk_env script to populate environment variables.