# Tutorial: Dependency Interfaces — Bind a Module by Contract
This tutorial builds `calc_via_interface`, a **core module that depends on an *interface*, not a concrete module**. Instead of naming `calc_module` (from [Part 1](tutorial-wrapping-c-library.md)) as a dependency and getting a fixed `modules().calc_module` wrapper, it declares a small **`calculator` interface** — a list of methods and one event — and **binds that interface to a module name chosen at runtime**. Any module whose API is a *superset* of the interface can satisfy it; `calc_module` is one such provider. You drive the whole thing from `logoscore` on the command line.
**What you'll build:** A `calc_via_interface` core module that:
- declares a **`calculator` interface** in its own language (a pure-C++ header with a `logos_events:` block) — `interfaces/calculator.h`
- lists it under `metadata.json`'s `interface_dependencies` — and names **no concrete module** in `dependencies`
- **binds** the interface to a runtime-chosen module with `modules().bind_calculator("calc_module")`, then calls it through the usual type-safe wrappers — **synchronously** (`add`, `multiply`, `libVersion`), **asynchronously** (`fibonacciAsync` + callback), and via a typed **event** subscription (`onVersionReady`)
- proves the **no-validation** contract: binding to a module that does not satisfy the interface fails as an ordinary remote-call error — no crash
No Qt, no `LogosAPI`, no plugin boilerplate — one plain C++ class, plus a one-file interface contract.
**What you'll learn:**
- The difference between a concrete dependency (`dependencies`) and a dependency interface (`interface_dependencies`)
- How to declare an interface in pure C++ (methods + a `logos_events:` block) — or equivalently in `.lidl`
- How the generator turns an interface into a **bound** wrapper whose target module is a constructor argument, exposed as `modules().bind_<interface>(moduleName)`
- How to call a bound interface **synchronously** and **asynchronously**, and how to subscribe to its events — all type-safely
- Why binding is decoupled from loading, and what the "superset" / no-validation rule means in practice
- How to share one interface across repos via a flake input (the same wiring `dependencies` use)
## Prerequisites
- Completed [Part 1](tutorial-wrapping-c-library.md) — you have a working `calc_module` whose shared library is built (`libcalc.so`/`.dylib` in `logos-calc-module/lib/`). This tutorial only needs `calc_module` as a *runtime* provider; it is never named at build time.
- Nix with flakes enabled
- Basic familiarity with C++
---
## Step 1: Scaffold the Module Project
Create a new directory and initialise it from the minimal module template:
`mkdir logos-calc-via-interface-module && cd logos-calc-via-interface-module`
This scaffolds a `flake.nix`, `metadata.json`, `CMakeLists.txt`, and a `src/` directory pre-wired for `logos-module-builder`. As in Part 1 we use the **pure-C++ (`interface: universal`) pattern**, so we replace the template's example `src/` files with our own plain `*_impl.h` / `*_impl.cpp`.
### 1.2 Remove the template's example sources
Delete the example Qt plugin the template ships — this tutorial supplies its own pure-C++ `src/` files:
An **interface** is a method/event contract decoupled from any concrete module. You write it in the *same language as your module* — for a universal module that's a plain C++ header. It looks like an impl class, but you only declare signatures: the generator reads them to build a typed client.
Put it in an `interfaces/` directory:
### 2.1 `interfaces/calculator.h` — the contract
The `calculator` interface names four methods and one event. It is deliberately a **subset** of what `calc_module` exposes (which also has `factorial`, `libVersionNotify`, …) — that is the *superset rule*: a provider may expose more than the interface requires.
```cpp
#pragma once
// A DEPENDENCY INTERFACE: a method/event contract that names no
// module. Any module whose API is a superset of this can satisfy
// it; the consumer binds it to a concrete module name at runtime.
//
// Written in the module's own language (pure C++). The generator
// reads the public methods + the `logos_events:` block and emits a
// BOUND wrapper class `Calculator` whose target module name is a
// runtime constructor argument — not baked in.
//
// Types are std (int64_t / std::string) because the consuming
// module is `interface: "universal"`; the bound wrapper inherits
// that api-style.
#include<cstdint>
#include<string>
// Defines the `logos_events` token (expands to `public`) so this
// header is valid C++ on its own, not only as generator input.
#include<logos_module_context.h>
classICalculator{
public:
int64_tadd(int64_ta,int64_tb);
int64_tmultiply(int64_ta,int64_tb);
int64_tfibonacci(int64_tn);
std::stringlibVersion();
logos_events:
// Emitted by the provider; the consumer subscribes through the
- The class name (`ICalculator`) and method signatures are all the generator needs — no `LogosAPI`, no Qt, no reference to any concrete module. The one include (`logos_module_context.h`) just defines the `logos_events` token so the header is valid C++ on its own.
-`logos_events:` (like Qt's `signals:`) marks event declarations. The generator turns each into a typed `on<Event>(callback)` subscriber on the bound wrapper.
- You could write the exact same contract as a `.lidl` file instead — `interfaces/calculator.lidl` with `method add(a: int, b: int) -> int` … `event versionReady(version: tstr)`. The `.h` form is shown here because it matches a universal module's own language.
---
## Step 3: Configure the Module
Three config files declare the module, point it at the interface, and tell CMake how to build it. The key contrast with [Composing Modules](tutorial-composing-modules.md): there is **no concrete module** in `dependencies`.
### 3.1 `metadata.json` — declare the interface dependency
`interface_dependencies` lists the contracts this module binds at runtime. Each entry gives the interface `name` and the `file` that defines it (and, for a `.h` file, the `impl_class` whose signatures define the contract). `dependencies` stays **empty** — we never name `calc_module` at build time.
```json
{
"name":"calc_via_interface",
"version":"1.0.0",
"type":"core",
"category":"general",
"description":"Binds a calculator interface to a module chosen at runtime",
| `interface` | `"universal"` — pure C++ impl, the builder generates the Qt plugin glue |
| `dependencies` | `[]` — **no concrete module** is named at build time |
| `interface_dependencies` | `[{ name, file, impl_class }]` — the builder generates the bound wrapper `Calculator` + the `modules().bind_calculator(...)` factory |
For a `.h` interface the `impl_class` field is required (the class whose signatures define the contract). For a `.lidl` interface, omit it. To pull an interface from **another repo**, add an `"input"` field naming a flake input — covered in the final step.
### 3.2 `CMakeLists.txt` — list your sources
You list only your plain C++ files. The generated interface wrapper and plugin glue are compiled automatically.
`NAME` must match `name` in `metadata.json` (`calc_via_interface`). No module dependency to wire here — the interface file is local to this repo.
### 3.3 `flake.nix` — no module inputs needed
Because there is no concrete dependency, the only input is the builder itself. (Contrast with Composing Modules, which had to add a `calc_module.url` input.)
```nix
{
description="Core module that binds a calculator interface at runtime";
`flakeInputs = inputs` hands the builder everything it needs. It reads `interface_dependencies` from `metadata.json`, resolves the local `interfaces/calculator.h`, and runs `logos-cpp-generator` to emit the bound `Calculator` wrapper into `generated_code/`.
---
## Step 4: Write the Module Class
The module is one plain C++ class inheriting `LogosModuleContext` — that base gives it `modules()`, through which the generated `bind_calculator(name)` factory is reachable. Each method takes the **provider module name** as its first argument, so we can bind to different modules at runtime from `logoscore`.
### 4.1 `src/calc_via_interface_impl.h` — the class
Every `public` method becomes callable over IPC. They fall into three groups: synchronous binds, an asynchronous bind, and an event subscription.
```cpp
#pragma once
#include<cstdint>
#include<string>
#include<logos_module_context.h>// LogosModuleContext base → modules()
// Binds the `calculator` interface (interfaces/calculator.h) to a
// module name chosen at runtime and calls it through the generated,
// type-safe bound wrapper. It names no concrete module of its own —
The provider name is a plain `std::string` parameter — that is the whole "bind at runtime" idea. The same handle code works for any module that satisfies `calculator`.
### 4.2 `src/calc_via_interface_impl.cpp` — the implementation
The `.cpp` includes the generated `logos_sdk.h` (which defines `LogosModules` and the `bind_calculator` factory), so the bind/call sites live here rather than in the header the generator parses.
```cpp
#include"calc_via_interface_impl.h"
// Generated at build time by logos-cpp-generator. Because
// metadata.json lists `interface_dependencies`, LogosModules gains a
// `bind_calculator(moduleName)` factory returning the bound
// `Calculator` wrapper. Included only in the .cpp so the impl header
// the generator parses stays free of generated types.
Everything flows through `modules().bind_calculator(provider)` — the factory the builder generated from `interface_dependencies`. There is no `modules().calc_module`, because `calc_module` is never a build-time dependency. The bound `Calculator` exposes the same typed sync/async/event API the name-baked wrappers do; the only difference is the target module is chosen when you bind.
---
## Step 5: Build the Module
### 5.1 Add a `.gitignore` and init the repo
Nix flakes require a git repository, and only tracked files are visible — so `interfaces/calculator.h` must be committed for the generator to find it. Exclude build artifacts first:
```text
# Nix build output
result
result-*
# CMake build directory
build/
```
Initialise the repo and stage the files (including `interfaces/`):
```bash
git init && git add -A
```
### 5.2 Build
For a universal module with an interface dependency, this is where `logos-cpp-generator` runs over both `src/calc_via_interface_impl.h` (plugin glue) and `interfaces/calculator.h` (the bound `Calculator` wrapper + `bind_calculator` factory), emitting everything under `generated_code/`:
```bash
nix build
```
### 5.3 Check the output
```bash
ls -la result/lib/
```
You should see your plugin (extension depends on platform):
```
calc_via_interface_plugin.so # Linux
calc_via_interface_plugin.dylib # macOS
```
---
## Step 6: Inspect the Module
Use `lm` to confirm the public API made it into the binary — and, tellingly, that there is **no module dependency**.
Every `public` method is here, published in the **LIDL contract** vocabulary rather than in C++ or Qt names: `int64_t` shows up as `int` and `std::string` as `tstr`. `lm` is reporting what the module says about itself, and what a module publishes is its contract.
Now the payoff: run `calc_via_interface` and bind its `calculator` interface to the real `calc_module` from Part 1. We use the `logoscore`**daemon** (`-D`) so module processes stay alive between `call` commands — needed for the async reply and the event subscription to survive from one call to the next. (Same daemon flow as [Part 1](tutorial-wrapping-c-library.md#step-6-test-with-logoscore) and [Composing Modules](tutorial-composing-modules.md#run-it-with-logoscore).)
### 7.1 Build the runtime and package both modules
Build `logoscore` and the package manager, then install **both** modules into a `modules/` directory. `calc_via_interface` comes from this project; `calc_module` from your Part 1 checkout — it is the *provider* we bind to, even though this module never declared it:
### 7.3 Install calc_module (the runtime provider)
Make sure `calc_module`'s shared library is built (from [Part 1](tutorial-wrapping-c-library.md#15-build-the-shared-library)), then package and install it:
`modules/` now holds `calc_via_interface/` and `calc_module/`. Neither knows about the other at build time — they meet only at runtime, through the interface.
### 7.4 Start the daemon and load both modules
```bash
./logos/bin/logoscore -D -m ./modules &
```
```bash
sleep 4
```
Load the provider and the consumer. The consumer declares no dependency, so we load `calc_module` explicitly:
`sumVia(calc_module, 3, 5) = 8`, `productVia(calc_module, 3, 5) = 15`, and `versionVia(calc_module) = "1.0.0"` — all through `modules().bind_calculator("calc_module")`, with `calc_module` chosen at call time.
### 7.6 Bind and call asynchronously
`startFibVia` fires `calculator.fibonacci(n)` asynchronously against the bound module and returns `"queued"`. The reply arrives on the daemon's event loop; `lastFib()` reads it. With `n = 20`, `fib(20) = 6765`:
The bound wrapper's generated `fibonacciAsync(..., callback)` delivered `6765` to the callback after `startFibVia` had already returned — the typed **async** path, over a runtime-bound interface.
### 7.7 Subscribe to a bound interface event
`watchVersion` subscribes to the interface's `versionReady` event on the bound module. `calc_module.libVersionNotify()` makes `calc_module` emit it, and `lastVersion()` reads what the typed callback captured:
`watchVersion` registered the callback via the generated `onVersionReady(...)`; the event fired in between; `lastVersion()` returned `1.0.0` — a typed event subscription on a runtime-bound interface.
### 7.8 Bind to a non-satisfying module (the no-validation rule)
Binding does **not** validate that the target satisfies the interface — there is no build-time coupling to check against. A bad bind isn't caught at bind time; it surfaces when you **call** through it — no crash, and the daemon keeps serving. `sumVia` checks the wrapper's `logos::CallError` out-parameter (see its implementation above) and returns `-1` when the inner call fails; on a transport that fails slowly the outer call may instead time out (`RPC_FAILED` / `"status":"error"`). Either way `calc_module` keeps answering (we keep going with `|| true` so the tour continues):
The bound `no_such_module` couldn't be resolved, so the inner `add` call failed — exactly like any other call to an absent module. No crash, no conformance check. Because `sumVia` passes a `logos::CallError*`, it *sees* the failure (`err.code == "object_unavailable"`) and maps it to its own error convention; a call without the out-parameter would get the type's default value plus a warning in the module log. Swapping providers is just changing the string: `sumVia calc_module 3 5` returns `8`; `sumVia no_such_module 3 5` fails. **Any** module that really exposes `add`/`multiply`/`fibonacci`/`libVersion`/`versionReady` satisfies `calculator` and slots in unchanged.
```bash
./logos/bin/logoscore stop
```
That completes the tour: a single interface, bound at runtime to a concrete module, driven type-safely for sync calls, async calls, and events — with no build-time dependency on the provider.
---
## Step 8: Share an Interface Across Repos
So far `interfaces/calculator.h` lived in this repo. To let *several* modules depend on the **same** contract, move it to its own repo (or a provider repo that publishes the interface it implements) and pull it in as a flake input — exactly how concrete `dependencies` are wired.
Add an `"input"` field to the `interface_dependencies` entry, naming a flake input, with `file` relative to that input's root:
The builder resolves `calc_interfaces` to a store path, hands the generator the resolved file, and emits the same bound `Calculator` wrapper — only the *source* of the contract moved. Nothing in `src/` changes. (In a workspace, run `ws sync-graph` after editing flake inputs.)
That's the full picture. An interface is a contract you can keep local or share across repos; a module binds it to whatever provider it's given at runtime; and the generated, type-safe wrappers make the bound calls feel exactly like calling a concrete dependency — minus the coupling.
The interface coupled `calc_via_interface` to a *contract*, never to `calc_module`. Any module exposing that contract can be bound in its place — at runtime, by name.
**Next:** see [Composing Modules](tutorial-composing-modules.md) for the concrete-dependency counterpart (`modules().calc_module`), or give this module a UI with [Part 2 (QML-only)](tutorial-qml-ui-app.md) / [Part 3 (C++ backend)](tutorial-cpp-ui-app.md).
