mirror of
https://github.com/logos-co/logos-tutorial.git
synced 2026-08-31 04:41:08 +00:00
61 lines
3.8 KiB
Markdown
61 lines
3.8 KiB
Markdown
# 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](logos-developer-guide.md)
|
|
|
|
## 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](tutorial-wrapping-c-library.md) -- 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](tutorial-qml-ui-app.md) -- 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)](tutorial-cpp-ui-app.md) — 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](tutorial-dev-boost.md) — 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](docs/spec.md) for the full format reference.
|
|
|
|
```bash
|
|
# 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 |
|