Part 1: Wrapping a C Library -- build calc_module, a core module that wraps a C library (libcalc). Covers external library configuration, CMake integration, building, inspecting with lm, testing with logoscore, and packaging with nix-bundle-lgx.
Part 2: Building a QML UI App -- build calc_ui, a QML-only ui_qml module that calls calc_module through the logos.callModule() bridge. No compilation needed. Scaffold: nix flake init -t ...#ui-qml
Part 3: Building a C++ UI Module (Process-Isolated) — build calc_ui_cpp, a ui_qml module with a C++ backend that runs in a separate ui-host process. Define the remote interface in a .rep file; the C++ backend inherits from the generated SimpleSource; QML accesses it via a typed replica using logos.module() and QtRemoteObjects.watch(). Scaffold: nix flake init -t ...#ui-qml-backend

Example Modules

Working module source code used by the tutorials:

Directory	Module	Type	Tutorial
`logos-calc-module/`	`calc_module`	`core` (wraps libcalc)	Part 1
`logos-calc-ui/`	`calc_ui`	`ui_qml` (QML-only)	Part 2
`logos-calc-ui-cpp/`	`calc_ui_cpp`	`ui_qml` (C++ backend + QML view)	Part 3

Running Tutorial Tests

The tests/ directory contains automated tutorial verification tests. Each test replays a tutorial from scratch — scaffolding, writing files, building, inspecting, and optionally verifying in Logos Basecamp.

Prerequisites

Nix with flakes enabled
yq (YAML processor) and nodejs — provided via nix-shell -p yq-go nodejs
For basecamp UI tests: a built LogosBasecamp binary and logos-qt-mcp package

Quick Start

# Run a single tutorial test (scaffold + files + build + inspect phases)
nix-shell -p yq-go nodejs --run "./tests/run-tutorial-test.sh tests/tutorial-wrapping-c-library.test.yaml"

# Run with a specific working directory (must exist)
mkdir -p /tmp/tutorial-test
nix-shell -p yq-go nodejs --run "./tests/run-tutorial-test.sh tests/tutorial-wrapping-c-library.test.yaml --workdir /tmp/tutorial-test"

# Run specific phases only
nix-shell -p yq-go nodejs --run "./tests/run-tutorial-test.sh tests/tutorial-qml-ui-app.test.yaml --phase scaffold,files,build"

# Verbose output
nix-shell -p yq-go nodejs --run "./tests/run-tutorial-test.sh tests/tutorial-wrapping-c-library.test.yaml --verbose"

Running with Basecamp UI Verification

To test that a tutorial's module works in Logos Basecamp, provide the basecamp binary and qt-mcp framework:

# First, build basecamp and qt-mcp from the logos-basecamp repo
cd /path/to/logos-basecamp
nix build -o result-basecamp
nix build '.#logos-qt-mcp' -o result-mcp

# Then run the tutorial test with basecamp phase
cd /path/to/logos-tutorial
mkdir -p /tmp/tutorial-test
nix-shell -p yq-go nodejs --run "./tests/run-tutorial-test.sh tests/tutorial-wrapping-c-library.test.yaml \
  --workdir /tmp/tutorial-test \
  --basecamp-bin /path/to/logos-basecamp/result-basecamp/bin/LogosBasecamp \
  --qt-mcp /path/to/logos-basecamp/result-mcp \
  --verbose"

Available Test Specs

Test File	Tutorial	Phases
`tests/tutorial-wrapping-c-library.test.yaml`	Part 1: Wrapping a C Library	scaffold, files, build, inspect, logoscore, basecamp
`tests/tutorial-qml-ui-app.test.yaml`	Part 2: QML UI App	scaffold, files, build, inspect, basecamp
`tests/tutorial-cpp-ui-app.test.yaml`	Part 3: C++ UI Module	scaffold, files, build, inspect, basecamp

Options

Flag	Description
`--workdir <path>`	Working directory (must exist; default: creates temp dir)
`--phase <phases>`	Comma-separated phases to run (default: all)
`--basecamp-bin <path>`	Path to LogosBasecamp binary
`--qt-mcp <path>`	Path to logos-qt-mcp package
`--verbose`	Show detailed output

Notes

The logoscore phase requires the logoscore CLI to be on PATH (provided by the workspace scripts/ directory)
The basecamp phase runs in offscreen mode (QT_QPA_PLATFORM=offscreen) — no display required
Tests use a temporary directory by default; pass --workdir to preserve build artifacts for debugging
UI tutorial tests (tutorial-qml-ui-app, tutorial-cpp-ui-app) automatically install their core module dependencies before launching basecamp