Update artifacts for tutorial-v4. Regenerate outputs/ against the 0.2.0
release tags: every {release} reference (logos-basecamp, logos-logoscore-cli,
logos-module-builder, logos-package-manager, logos-module) now resolves to
0.2.0 in both the generated .md tutorials and the example module flake.nix
files.
- Add the missing {release} placeholder to the advanced flake.nix examples in
tutorial-wrapping-c-library and tutorial-interface-dependencies so they pin
consistently.
- run.sh: clean now also removes the .logoscore persistence dirs; --release
examples updated from tutorial-vN to 0.2.0 (repos carry semver tags;
logos-tutorial carries the tutorial-vN tag).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Part 3's .rep previously declared only slots. Broaden it to cover the whole
Qt Remote Objects contract a universal UI backend can author, so the tutorial
teaches the breadth of .rep, not just call-and-return:
- SLOT(void announceVersion()) — a void / fire-and-forget slot
- PROP(QString versionEvent READONLY) — fed by a typed calc_module event
subscription armed in onContextReady()
- PROP(int computeCount READONLY) — a slot-driven counter (int PROP)
- PROP(int memory READWRITE) — a register the QML view writes back
- SIGNAL(computed(QString op, int result)) — a backend -> view push
The backend gains onContextReady() (event subscription) and a record() helper
(bumps computeCount, emits computed); the QML view gains a Connections block,
Computations / Last-op labels, and a Memory register with Store/Clear buttons
that assign backend.memory. Step 9's UI test drives each surface — the slot
return value, the int PROP (Computations: 1), the signal payload (add = 8),
and the READWRITE round-trip (Memory: 0 -> 8) — and the closing .rep pattern
table now marks every row exercised except Model.
Regenerated outputs/ (md + calc_ui_cpp sources + screenshots). Verified end to
end via the doctest chain (Part 1->2->3): 69/69 steps, UI test 14/14.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Adds the metadata flag row + §1.6 explaining single vs multi, the per-language
thread-safety contract (Rust &self + Send + Sync / C++ self-synchronize), and the
"how it works" model: the module owns concurrency behind the ordinary callMethod
(pending sentinel + completion event) with NO provider/host ABI change, so an old
daemon/app loads + forwards a multi module unmodified. Protocol 0.2 (additive
minor). Notes the event-ordering caveat and the pre-0.2-caller caveat.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* tutorial(cpp-ui): Qt-typed dependency calls via LogosUiPluginContext
Sync Part 3 (calc_ui_cpp) to the new UI authoring model: the backend derives
LogosUiPluginContext (not the std-typed LogosModuleContext), and its
modules().calc_module wrappers are now Qt-typed (api-style qt). libVersion()
returns modules().calc_module.libVersion() directly — the QString::fromStdString
conversion is gone since the wrapper now returns QString, matching the .rep slot.
Depends on logos-co/logos-qt-sdk#3, logos-co/logos-plugin-qt#14, and
logos-co/logos-module-builder#124. Part of a 4-repo change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* tutorial(cpp-ui): don't pin logos-module-builder in calc-ui-cpp flake
The generated example flake hard-pinned logos-module-builder to a specific
commit; every other tutorial output (and the generated .md) tracks the branch
via `github:logos-co/logos-module-builder` — only release builds pin (the
spec's `{release}` placeholder). Drop the stray rev to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* tutorial(cpp-ui): fix the doctest spec backend for Qt-typed modules()
The doctest CI executes the spec's `file:` blocks, not the committed outputs/
tree — and the spec's backend still used the std-typed model: it derived
LogosModuleContext and wrapped `modules().calc_module.libVersion()` in
QString::fromStdString(...). That compiled only while module-builder was pinned
to a stale pre-flip commit (ui_qml api-style=std → libVersion() returned
std::string). Now that the flake tracks module-builder master (api-style=qt,
libVersion() returns QString), QString::fromStdString(QString) fails to compile.
Bring the spec in line with the generated outputs (already fixed): derive
LogosUiPluginContext, include logos_ui_plugin_context.h, and return
modules().calc_module.libVersion() directly. Prose/diagram updated to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the new `.#generate` output (runs every code generator and emits a
ready-to-build module source tree) to the build-outputs section of the
developer guide.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* tutorial(cpp-ui): rewrite Part 3 to the universal authoring model
calc_ui_cpp now uses interface: universal — you write only the .rep and a
CalcUiCppBackend deriving CalcUiCppSimpleSource + LogosModuleContext, calling
modules().calc_module.* (typed SDK). The *Plugin/*Interface classes,
initLogos, and setBackend wiring are generated; the hand-written interface +
plugin steps are gone. CMake uses REP_FILE + the backend sources + INCLUDE_DIRS.
Regenerated outputs/tutorial-cpp-ui-app.md and outputs/logos-calc-ui-cpp/.
Verified end to end: the full Part 1->2->3 chain runs 69/69 against the
universal templates (logos-module-builder feat/universal-templates), including
the live UI drive (Add -> 8) and the integration-test build.
Depends on the logos-module-builder universal-templates change so that the
#ui-qml-backend scaffold is the universal form.
* tutorial(cpp-ui): derive module NAME from metadata.json in CMake
Match the templates: read the name via file(READ metadata.json) +
string(JSON ... name) and pass NAME ${MODULE_NAME} to logos_module(), so the
module name has a single source of truth. Same string(JSON) pattern the
converted templates use (build-verified there).
* doctest: make the bad-bind step outcome-agnostic
Asserting status:error relied on the inner call to a missing module
blocking long enough to time out the outer RPC. With faster failure
detection the plain-int typed wrapper returns the type's default and the
outer call reports ok — both surfaces are legitimate, and which one wins
is a platform/timing race (consistently the fast path on Linux since the
transport extraction, still the slow path on macOS). Assert on the
stable part and teach the real contract: bad binds fail at call time;
methods that need caller-visible errors should return result.
* doctest(qml-ui): gate the Modules click on a wait_for
Right after the calculator round-trip the shell is still settling; on a
busy CI runner the Modules entry can take longer than the click action's
retry budget to materialize (flipped red on both platforms in one run,
green the previous hour, identical pins). Same pattern the spec already
uses for the post-launch wait.
* doctest(qml-ui): open Settings before clicking Modules
The Modules entry lives in the Settings left rail; clicking it cold
relied on incidental tree state (passed or failed depending on whether
the entry happened to be materialized). Mirror the basecamp doctests'
proven sequence: click Settings, wait for the view, then click Modules.
* tutorial: demonstrate the CallError out-param on bound interface calls
Generated typed wrappers now take an optional trailing
logos::CallError* — sumVia checks it and returns -1 when the inner call
fails (err.code == "object_unavailable" for a missing module), so the
bad-bind lesson no longer depends on which way the failure-timing race
falls. The doctest assert stays tolerant of the slow-transport
outer-timeout surface.
basecamp moved its modules view: the old top-level "Modules" sidebar entry
was renamed to "Package Manager", and the UI Modules / Core Modules tabs now
live under Settings → Modules. The Part 2 UI doc-test still clicked a
top-level "Modules", which no longer exists, so the step failed with:
click("Modules"): No element found with text 'Modules'
Click "Settings" first (and wait for the Settings view to render), then the
now-nested "Modules" sub-tab — mirroring logos-basecamp's own
basecamp-modules doc-test. Prose and the generated outputs/ markdown updated
to "Settings → Modules → Core Modules".
Caught by the logos-workspace nightly doc-test run against the bumped
logos-basecamp commit.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: replace logoscore inline (-c) mode with daemon/client workflow
logos-logoscore-cli's inline mode (`logoscore -m <dir> -l <mod> -c
"mod.method(args)" --quit-on-finish`) has been removed. Update the developer
guide and the wrapping-a-C-library tutorial to use the daemon + client
workflow instead:
logoscore -D -m ./modules -l my_module & # start a daemon, pre-load module
logoscore call my_module doSomething hello # call (positional args; @file ok)
logoscore stop # stop when done
- §5.1 "Inline Mode (Legacy)" → "One-shot execution" (daemon + `call`), with a
note that inline mode was removed and a daemon-startup flags table.
- CLI quick-reference: drop the inline one-liner; show daemon pre-load instead.
- Troubleshooting "quick check": load-module + call + stop.
- tutorial-wrapping-c-library spec + its rendered output: "inline (legacy)
mode" → "the full daemon/client workflow".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: address review — fix §6.1 anchor, daemon readiness waits, document --config-dir
- Fix the "Running with logoscore" link anchor: #51 → #61 (the section is 6.1;
the old anchor 404s). In both the wrapping-c-library spec and its output.
- Daemon examples background `-D` then call immediately, which can race daemon
startup. Wait for readiness (`until logoscore status; do sleep 0.2; done`) in
the §6.1 one-shot example and the troubleshooting quick-check; background the
previously-foreground openmetrics `-D` snippet too.
- Document `--config-dir` (and `--persistence-path`) in the daemon startup flags
table, since the openmetrics example uses `--config-dir`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: daemon starts clean — drop -l, load modules via load-module
Follow-up to dropping inline mode: logoscore's daemon now starts clean (the
-l/--load-modules autoload flag is removed). Update the §6.1 one-shot example
and CLI quick-reference to start a clean daemon and load modules with
`load-module`; drop the -l row from the daemon startup flags table.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: document LIDL-based dependency consumption + dependency_overrides
Tutorial-sync for "concrete dependencies via LIDL":
- Developer guide §9.2: explain that each module publishes a cheap LIDL
interface contract (packages.<sys>.lidl) and that consuming a dependency
generates modules().<dep> from that LIDL WITHOUT building the dependency's
plugin — only the standalone-app run (#run) bundles/builds deps. Notes the
cross-language pipeline (Rust -> LIDL -> C++) and the transitional fallback
for deps that don't yet expose a `lidl` output.
- Document the new `dependency_overrides` metadata field (§9.2 + field table).
- Composing Modules tutorial: correct the prose that said the builder "fetches
calc_module's headers" — it now reads calc_module's published LIDL contract
and does not build calc_module's plugin at the aggregator build step.
Depends on logos-cpp-sdk#77, logos-plugin-qt#9, logos-module-builder#110 (the
described behavior ships with those).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* address review: regenerate composing tutorial md; reconcile §8.2/§9.2
- Regenerate outputs/tutorial-composing-modules.md so the committed markdown
matches the updated YAML prose (it had stale "fetch headers" / "exported
interface" wording). Verified identical to `doctest generate`.
- Developer guide §9.2: add a note tying the LIDL-contract dependency wrapper
generation to §8.2 — it's the same logos-cpp-generator driven by the dep's
LIDL/.h contract (like interface_dependencies) rather than inspecting a
compiled plugin (the manual/standalone path), so the two sections no longer
read as conflicting mechanisms.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: dependency interfaces tutorial (executable)
Add tests/tutorial-interface-dependencies.test.yaml — an executable
logos-doctest tutorial that builds calc_via_interface: a module declaring a
`calculator` interface and binding it to calc_module at runtime. Covers typed
sync/async/event calls, the no-validation rule, and the cross-repo interface
form. Registered in run.sh and CI (run + generate). Documents
interface_dependencies + bind_<interface> in the developer guide.
Depends on logos-cpp-sdk#74, logos-module-builder#108, logos-plugin-qt#8 —
the published flakes must carry these before the tutorial runs green in CI
(same release gating as the Composing Modules tutorial).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* address review: self-valid interface header + accurate CI step
- Interface calculator.h includes logos_module_context.h so the logos_events
token is defined (valid C++ standalone); prose updated accordingly.
- CI step name/comment now reflect the third tutorial leaf
(tutorial-interface-dependencies), not just the UI chain + Composing Modules.
(Copilot review, PR #64.)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* rerun
* rerun
* fix(tutorial): correct the no-validation negative test
Binding to a module that isn't loaded does NOT return a silent default — the
inner remote call fails and propagates, so `logoscore call ... sumVia
no_such_module` exits non-zero with RPC_FAILED. The step asserted "result":0
and let the non-zero exit fail the doctest step. Reframe it accurately: a bad
bind surfaces as an ordinary RPC failure (not a crash); absorb the exit with
`|| true`, capture stderr, and assert `"status":"error"`. Fix the prose and the
recap row to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add "Composing Modules" tutorial: calc_aggregator core module
New executable tutorial (tests/tutorial-composing-modules.test.yaml) that
builds calc_aggregator, a core (universal) module depending on calc_module,
showcasing every LogosModuleContext capability end-to-end via logoscore:
- modulePath / instanceId / instancePersistencePath getters
- durable per-instance persistence (a run counter that survives a restart),
wired up in onContextReady()
- typed sync dependency calls (computeReport composes five calc_module calls
into one map)
- typed async dependency call (fibonacciAsync with a callback)
- typed event subscription (onVersionReady on calc_module's versionReady)
Driven entirely from the logoscore daemon (no UI), mirroring Part 1's flow.
Also:
- README: list the tutorial and the calc_aggregator example module
- run.sh: build the module into outputs/ via --workdir (reusing the chain's
calc_module, no rebuild) and clean its calc-data/ persistence dir
- ci.yml: run the new spec and verify its markdown generation
- outputs/: rendered tutorial + cleaned module source
The typed event subscriber requires logos-cpp-sdk PR #72 (LIDL parser: accept
reserved words as identifiers in name positions) so calc_module's versionReady
event sidecar round-trips; the doctest's event step stays red against published
deps until that lands and the module builder bumps its SDK pin.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* rerun
* Address review: warn about SDK dependency, make CI non-blocking
- prerequisites + event step: explicit toolchain note that the typed event
subscriber needs logos-cpp-sdk#72 (calc_module's `version` event param
collides with a reserved word), with a workaround (pin a fixed
logos-module-builder, or skip the event step — everything else works on
the released toolchain).
- ci.yml: split the Composing Modules spec out of the blocking UI-chain run
into its own `continue-on-error: true` step so it doesn't block merges
until #72 lands; a comment says to fold it back in once the dep ships.
- regenerate outputs/tutorial-composing-modules.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Re-enable Composing Modules as a blocking CI tutorial
logos-cpp-sdk#72 (LIDL parser: reserved words usable as identifiers) is merged
and logos-module-builder has bumped its SDK pin, so calc_module's versionReady
event sidecar now round-trips and the typed onVersionReady subscriber builds on
the published toolchain.
- ci.yml: fold the spec back into the blocking UI-chain run (and the published
two-column report); drop the temporary continue-on-error step.
- spec: remove the now-obsolete toolchain prerequisite note and the event-step
heads-up.
- regenerate outputs/tutorial-composing-modules.md.
Verified end-to-end against the published toolchain: 77/77 doctest steps pass,
including the build and the full event round-trip.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Document + verify event introspection in the tutorials
Mirror the per-method documentation coverage for events. The
wrapping-c-library calc_module already emits a versionReady event; give
it a /// doc comment and assert the whole event pipeline end-to-end.
- wrapping-c-library: document the versionReady event; add a 'List
events' step asserting 'lm events' shows the signature + both
description lines; assert logoscore module-info's Events section.
- qml-ui-app: rename the basecamp ui_test driver call openMethods ->
openInterface and assert the event's description renders on the
Interface screen (basecamp-interface-docs.png).
- Regenerate both tutorial markdowns.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* rerun
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* demonstrate and validate method doc comments (wrapping-c-library)
Add /// doc comments to the calc module's methods and assert they surface
via `lm methods` (human + --json) and `logoscore module-info`. Corrects the
stale lm output (provider-path introspection lists only impl methods, not
eventResponse/initLogos). Regenerated the tutorial markdown.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* showcase multi-line doc comments in the calc module
factorial uses two /// lines and libVersion uses a /** ... */ block; both
join into a single-line description. Assertions and rendered output updated
to match the joined text.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* preserve multi-line doc comments in the calc module tutorial
factorial/libVersion/libVersionNotify now keep their line breaks in lm and
logoscore module-info output; assertions and rendered markdown updated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* use consistent introspection terminology in the tutorial
Refer to "the module's method introspection" throughout instead of mixing the
internal getMethods()/getPluginMethods names. Addresses review feedback on #60.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* verify method docs on basecamp's Methods screen (Part 2 doctest)
Extends the Part 2 basecamp ui_test to open calc_module's Methods screen
(via CoreModulesView.openMethods) and assert each method's description
renders — including factorial's multi-line doc comment. Closes the GUI
surface of the per-method documentation feature in the automated doctest.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* rerun
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
support --output option ; generate both tutorials and example code from test specs
delete old code files
add to readme instructions about run.sh
update run.sh to avoid logs and hardcoded paths
