logos-tutorial

Tutorial series and reference documentation for building Logos modules.

Start Here

New to Logos? Start with the developer guide -- it walks through creating, building, packaging, and running your first module:

• Logos Developer Guide

Next Tutorials

Step-by-step tutorials that build on each other. Each creates a working module you can run.

• 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

• logos-dev-boost: Scaffolding Modules with logos-dev-boost — use the logos-dev-boost CLI to auto-generate modules from C library directories. Wraps libcalc (source-only) and sqlcipher (pre-built .so), including integration tests that create encrypted databases. Covers --type module, --type full-app, and --lib-dir.

Executable Tutorials

Tutorials have YAML specs in tests/ that can be both executed (to verify they work) and used to generate the .md files. See docs/spec.md for the full format reference.

# Run a tutorial end-to-end, writing to a directory you can inspect afterwards
python3 tools/tutorial_runner.py run tests/tutorial-wrapping-c-library.test.yaml \
  --workdir /tmp/my-tutorial-test --verbose

# Run only specific phases (scaffold, files, build, inspect, logoscore)
python3 tools/tutorial_runner.py run tests/tutorial-wrapping-c-library.test.yaml \
  --phase scaffold,files,build --verbose

# Re-run a single phase against a previous build
python3 tools/tutorial_runner.py run tests/tutorial-wrapping-c-library.test.yaml \
  --workdir /tmp/my-tutorial-test --phase inspect --verbose

# Generate the .md tutorial from the YAML spec
python3 tools/tutorial_runner.py generate tests/tutorial-wrapping-c-library.test.yaml

# Pin all GitHub URLs to a specific release tag
python3 tools/tutorial_runner.py run tests/tutorial-wrapping-c-library.test.yaml --release tutorial-v2
python3 tools/tutorial_runner.py generate tests/tutorial-wrapping-c-library.test.yaml --release tutorial-v2

The --workdir flag lets you point the runner at a directory of your choice — all files, builds, and artifacts end up there so you can inspect or re-use them. Without it, a temp directory is created and deleted after the run (use --keep-workdir to preserve it).

The --release flag (or the release field in the YAML) pins all {release} placeholders in GitHub URLs to a git tag, so github:logos-co/repo{release}#output becomes github:logos-co/repo/tutorial-v2#output. Set it to "" or omit it for latest.

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