mirror of
https://github.com/logos-co/logos-tutorial.git
synced 2026-08-30 04:11:10 +00:00
Dario LipicarandClaude Opus 5
efaa390484
* test(doctests): `lm` publishes the LIDL contract vocabulary, not Qt names
A universal module's `getMethods()` comes from the cdylib backend's
`lidlInterfaceJson()` (logos-plugin-qt's glue forwards
`logos_module_get_methods` verbatim), and that now answers in the LIDL
contract spelling. `lm methods`, `lm events` and `logoscore module-info`
print those strings straight through, so every listing in Part 1 changed:
qlonglong add(qlonglong a, qlonglong b) -> int add(int a, int b)
QString libVersion() -> tstr libVersion()
void versionReady(QString version) -> void versionReady(tstr version)
Six `expect_contains` in tutorial-wrapping-c-library.test.yaml were pinned
to the Qt spellings and now fail.
HOW THIS WAS ALMOST MISSED, because the trap will recur. The hand-pinned
`outputs/tutorial-wrapping-c-library.md` already showed `int add(int a, int b)`
and `add(int,int)` — a stale snapshot from an earlier era that happened to
read as "already LIDL, nothing to do". CI runs the ASSERTIONS in
`tests/*.test.yaml`; it never diffs the outputs tree. Clearing a file by
reading `outputs/` proves nothing.
Every replacement string is derived mechanically rather than by hand: the
tutorial's own `src/calc_module_impl.h` + `metadata.json` were run through
`logos-cpp-generator --from-header --backend cdylib`, the emitted
`lidlInterfaceJson()` was parsed back into JSON, and that JSON was rendered
through logos-module's own printer (`cmd/main.cpp`) and logoscore's
(`src/client/output.cpp`). The displayed blocks in BOTH trees now compare
byte-identical to that render.
Two accuracy fixes fall out of doing that, both pre-existing drift in the
blocks being rewritten:
* the derived identity methods `name()` / `version()` DO appear in every
listing (nothing filters `derived` on the read side) and were missing
from the shown output;
* the `module-info` block said `libVersion() -> QString` and
`versionReady(version: QString)`.
The C++-type table gains a column. "On the wire (Qt)" conflated two
different questions; it is now "LIDL contract type" — what the module
publishes, what Step 5 prints, what a Rust or Nim binding sees — and "A Qt
consumer sees", which is only the C++/Qt caller's spelling.
Also here, same cause:
* tutorial-composing-modules and tutorial-interface-dependencies had the
same "shows up as QString ... the wire types the generated glue exposes"
prose. Their assertions are name-only, so they did not fail — but they
described the listing wrongly. `LogosMap` publishes as `{tstr: any}`,
verified by generating calc_aggregator's glue.
* logos-developer-guide.md's `lm methods --json` example was a
handwritten-Qt listing (`initLogos(LogosAPI*)`) presented as the general
case. It now shows both publishers and says which is which: a universal
module publishes its contract, a handwritten Qt plugin publishes what its
QMetaObject says.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(guide): the plugin path needs the module's contract, not just its plugin
`logos-cpp-generator <plugin> [--module-only]` is documented here as a way to
generate a module's consumer wrapper, and the examples pass only the plugin.
That is now a trap for any module built with `interface: "universal"` or
`"cdylib"`: its published `getMethods()` answers in the LIDL contract
vocabulary — the same change d963871 pinned in the `lm` listings — while the
wrapper emitter reads Qt type names and falls back to QVariant / LogosMap for
anything else. The wrapper would compile and have lost every type.
The generator now takes the METHODS from the `.lidl` contract named by
`--events-from` (the flag keeps its name; the file always was the whole
contract), and REFUSES a LIDL-spelled listing when no contract was given rather
than emitting the untyped wrapper. Nix builds already pass the flag —
buildHeaders.nix finds `<module>/share/logos/<name>.lidl` — so only hand-run
invocations, which is what this section documents, had to change.
Both examples gain the flag, a second example shows the handcrafted-Qt case
that legitimately omits it, and the synopsis in the CLI reference lists it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>