Skip to content

Getting Started

This tutorial path builds TopoExec, runs one pure C++ embedded graph, then uses the CLI to validate, inspect, run, and debug a YAML graph.

1. Build and test

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j
ctest --test-dir build --output-on-failure

The required agent gate is:

./scripts/agent_check.sh

2. Run the pure C++ builder example

./build/topoexec_app_cpp_builder_minimal

Expected stable lines:

builder_sink=hello:built
builder_order=source,transform,sink
builder_committed=2

This app links only the runtime target and constructs the graph through topoexec/runtime/graph_builder.hpp.

3. Validate a YAML graph

./build/topoexec graph validate examples/minimal.yaml

Expected output:

ok

4. Inspect the compiled plan

./build/topoexec graph plan examples/minimal.yaml --format json

Use plan output to review region order, edge kinds, trigger policies, and CompositeLoop ownership before runtime execution.

5. Run the graph

./build/topoexec graph run examples/minimal.yaml --steps 1

Expected stable lines:

order: source,transform,sink
runtime_publication_committed: 2

6. Debug with metrics and trace

./build/topoexec graph metrics examples/minimal.yaml --steps 1 --format json
./build/topoexec graph trace examples/minimal.yaml --steps 1 --format json
./build/topoexec graph explain examples/minimal.yaml

The metrics view answers "what happened," the trace view answers "when and in what order," and explain/lint output maps compiler/runtime semantics back to the graph authoring model.

7. Install and consume from CMake

For the external-adoption path, install into a temporary prefix and build the runtime-only downstream smoke:

cmake --install build --prefix /tmp/topoexec-install
cmake -S tests/cmake/runtime_smoke -B /tmp/topoexec-runtime-smoke \
  -DCMAKE_PREFIX_PATH=/tmp/topoexec-install
cmake --build /tmp/topoexec-runtime-smoke -j
/tmp/topoexec-runtime-smoke/topoexec_runtime_smoke

Applications should link the runtime target unless they need YAML or CLI tools:

find_package(topoexec CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE topoexec::runtime)

8. Next pages