diff --git a/outputs/logos-calc-aggregator-module/flake.nix b/outputs/logos-calc-aggregator-module/flake.nix index dc37a98..c0507d9 100644 --- a/outputs/logos-calc-aggregator-module/flake.nix +++ b/outputs/logos-calc-aggregator-module/flake.nix @@ -2,7 +2,7 @@ description = "Aggregator core module - composes calc_module and showcases LogosModuleContext"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # The module this one depends on. Placeholder path — locked to your # real checkout in the build step via `--override-input`. diff --git a/outputs/logos-calc-module/flake.nix b/outputs/logos-calc-module/flake.nix index 37b716a..d889497 100644 --- a/outputs/logos-calc-module/flake.nix +++ b/outputs/logos-calc-module/flake.nix @@ -2,7 +2,7 @@ description = "Calculator module - wraps libcalc C library for Logos"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; }; outputs = inputs@{ logos-module-builder, ... }: diff --git a/outputs/logos-calc-ui-cpp/flake.nix b/outputs/logos-calc-ui-cpp/flake.nix index 4f892a4..61af2b9 100644 --- a/outputs/logos-calc-ui-cpp/flake.nix +++ b/outputs/logos-calc-ui-cpp/flake.nix @@ -2,7 +2,7 @@ description = "Calculator C++ UI plugin for Logos - QML view with process-isolated backend for calc_module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # Points at your local calc_module checkout. This is a placeholder — # you lock it to your actual path in the next step with diff --git a/outputs/logos-calc-ui/flake.nix b/outputs/logos-calc-ui/flake.nix index 1a484e9..cf8e8de 100644 --- a/outputs/logos-calc-ui/flake.nix +++ b/outputs/logos-calc-ui/flake.nix @@ -2,7 +2,7 @@ description = "Calculator QML UI Plugin for Logos - frontend for calc_module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # Points at your local calc_module checkout. This is a placeholder — # you lock it to your actual path in the next step with diff --git a/outputs/logos-calc-via-interface-module/flake.nix b/outputs/logos-calc-via-interface-module/flake.nix index cd77f53..4fa5720 100644 --- a/outputs/logos-calc-via-interface-module/flake.nix +++ b/outputs/logos-calc-via-interface-module/flake.nix @@ -2,7 +2,7 @@ description = "Core module that binds a calculator interface at runtime"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; }; outputs = inputs@{ logos-module-builder, ... }: diff --git a/outputs/tutorial-composing-modules.md b/outputs/tutorial-composing-modules.md index 2a38454..2084b3b 100644 --- a/outputs/tutorial-composing-modules.md +++ b/outputs/tutorial-composing-modules.md @@ -37,7 +37,7 @@ Create a new directory and initialise it from the minimal module template: ### 1.1 Create the project from the template ```bash -nix flake init -t github:logos-co/logos-module-builder/0.2.0 +nix flake init -t github:logos-co/logos-module-builder ``` This scaffolds a `flake.nix`, `metadata.json`, `CMakeLists.txt`, and a `src/` directory pre-wired for `logos-module-builder`. As in Part 1 we use the newer **pure-C++ (`interface: universal`) pattern**, so we replace the template's example `src/` files with a single plain `*_impl.h` / `*_impl.cpp` class. @@ -130,7 +130,7 @@ Declare `calc_module` as a flake input. The input attribute name **must match** description = "Aggregator core module - composes calc_module and showcases LogosModuleContext"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # The module this one depends on. Placeholder path — locked to your # real checkout in the build step via `--override-input`. @@ -455,7 +455,7 @@ Use `lm` to confirm the dependency and the public API made it into the binary. ### 5.1 Build `lm` ```bash -nix build 'github:logos-co/logos-module/0.2.0#lm' --out-link ./lm +nix build 'github:logos-co/logos-module#lm' --out-link ./lm ``` ### 5.2 View metadata — note the dependency @@ -498,11 +498,11 @@ Now the payoff: run `calc_aggregator` **and** its `calc_module` dependency under Build `logoscore` and the package manager, then install **both** modules into a `modules/` directory `logoscore` can scan. The aggregator comes from this project; `calc_module` from your Part 1 checkout: ```bash -nix build 'github:logos-co/logos-logoscore-cli/0.2.0' --out-link ./logos +nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos ``` ```bash -nix build 'github:logos-co/logos-package-manager/0.2.0#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm ``` ```bash diff --git a/outputs/tutorial-cpp-ui-app.md b/outputs/tutorial-cpp-ui-app.md index 96bba1f..6eabced 100644 --- a/outputs/tutorial-cpp-ui-app.md +++ b/outputs/tutorial-cpp-ui-app.md @@ -86,7 +86,7 @@ Create a new directory and initialise it from the C++ backend UI template: `mkdir logos-calc-ui-cpp && cd logos-calc-ui-cpp` ```bash -nix flake init -t github:logos-co/logos-module-builder/0.2.0#ui-qml-backend +nix flake init -t github:logos-co/logos-module-builder#ui-qml-backend ``` This scaffolds the **universal** UI backend template: a `metadata.json` with `"interface": "universal"`, an example `.rep` (`src/ui_example.rep`), and a single `*Backend` class (`src/ui_example_backend.h` / `.cpp`) — no hand-written interface or plugin files. We'll replace the `ui_example` files with our calculator's `.rep` + backend. @@ -698,7 +698,7 @@ The template already wires everything up. Update the description and point `calc description = "Calculator C++ UI plugin for Logos - QML view with process-isolated backend for calc_module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # Points at your local calc_module checkout. This is a placeholder — # you lock it to your actual path in the next step with @@ -794,38 +794,37 @@ Every surface the `.rep` declares is now proven end to end from one click: --- -## Step 10: Live reloading QML with `DEV_QML_PATH` +## Step 10: Hot-reloading QML with `nix build .#ui-dev` -For QML iteration, point `DEV_QML_PATH` at the directory that contains your view entry's **basename** (from `metadata.json` `"view"`). This tutorial sets `"view": "qml/Main.qml"`, so the directory must contain `Main.qml` (here: `src/qml/`): +For QML iteration, build the dev launcher once. After that, QML edits need no rebuild at all: ```bash -DEV_QML_PATH=$PWD/src/qml nix run . +nix build .#ui-dev +./result/bin/run-logos-standalone-ui ``` -When `DEV_QML_PATH` is set, `logos-standalone-app` loads QML from your source tree at runtime instead of the installed copy — so edits to `Main.qml` (and any QML under that tree) are picked up on the next relaunch without you having to re-sync files. +Run from the repo root and the launcher finds your QML source automatically, then watches it. Edit a `.qml` file, save, and the view re-renders in about 200 ms. It reports what it picked up on startup: -**Important — what this does *not* skip.** `nix run` always re-evaluates the flake and rehashes the source tree before launching. By default `src = ./.` includes every tracked file, including `*.qml` — so: +``` +run-logos-standalone-ui: hot-reloading QML from /path/to/logos-calc-ui-cpp/src/qml + (export DEV_QML_PATH to override, or LOGOS_QML_HOT_RELOAD=0 to disable) +``` -- **Any source change, including QML edits, rebuilds the plugin** before the app starts. `DEV_QML_PATH` only kicks in *after* the build is done; it doesn't shortcut the rebuild itself. -- **C++ / `.rep` / `metadata.json` / CMake changes** rebuild as normal. -- The flake-evaluation overhead on each `nix run` is fixed and unavoidable while invoking through nix. +`ui-dev` is the same wrapper `nix run .` uses — dependency modules bundled and loaded identically — exposed as a package so it lands in `./result/bin`. It is a development target and is never bundled into `.lgx` packages. -For the absolute fastest loop (no nix involvement after the first build), do the build once and run the resulting binary directly: +**What reloads, and what doesn't.** -```bash -# Build once — populates result/ in the nix store -nix build . - -# Subsequent runs: invoke the bundled standalone wrapper directly, -# skipping nix entirely. DEV_QML_PATH still redirects QML loading. -DEV_QML_PATH=$PWD/src/qml ./result/bin/run-logos-standalone-ui -``` +- **Any `.qml`/`.js` under your view directory**, including files and folders created after launching. +- **The backend keeps running.** A module's C++ backend lives in a separate `ui-host` process, so its state and connections survive a reload. +- **QML-side state resets** — scroll position, text fields, current tab. +- **A syntax error is recoverable.** It's logged with a line number and the view blanks; the next save that compiles restores it. +- **C++, `.rep`, `metadata.json` and CMake changes still need a rebuild.** Re-run `nix build .#ui-dev` and relaunch. -(Adjust the binary name to whatever `ls result/bin/` shows on your build.) +**Why not `nix run .`?** It re-evaluates the flake and rehashes the source tree on every invocation. Since `src = ./.` covers every tracked file including `*.qml`, even a one-character QML edit rebuilds the plugin before the app starts. Building `ui-dev` once avoids that entirely. -> **Naming:** Only `DEV_QML_PATH` is honored by `logos-standalone-app`. See `repos/logos-standalone-app/README.md`. +> **Custom layouts:** the launcher looks for the `view` entry from `metadata.json` under `src//`, then `/`. If your tree differs, set `DEV_QML_PATH` to the directory holding the entry file and it takes precedence. -> This does not work with `logos-basecamp` — Basecamp loads QML plugins from its own install tree, so source edits are not picked up until you rebuild and reinstall the `.lgx`. +> This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so source edits are not reflected until you rebuild and reinstall the `.lgx` package. --- diff --git a/outputs/tutorial-interface-dependencies.md b/outputs/tutorial-interface-dependencies.md index 6c2f0ac..1786c6f 100644 --- a/outputs/tutorial-interface-dependencies.md +++ b/outputs/tutorial-interface-dependencies.md @@ -37,7 +37,7 @@ Create a new directory and initialise it from the minimal module template: ### 1.1 Create the project from the template ```bash -nix flake init -t github:logos-co/logos-module-builder/0.2.0 +nix flake init -t github:logos-co/logos-module-builder ``` This scaffolds a `flake.nix`, `metadata.json`, `CMakeLists.txt`, and a `src/` directory pre-wired for `logos-module-builder`. As in Part 1 we use the **pure-C++ (`interface: universal`) pattern**, so we replace the template's example `src/` files with our own plain `*_impl.h` / `*_impl.cpp`. @@ -188,7 +188,7 @@ Because there is no concrete dependency, the only input is the builder itself. ( description = "Core module that binds a calculator interface at runtime"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; }; outputs = inputs@{ logos-module-builder, ... }: @@ -384,7 +384,7 @@ Use `lm` to confirm the public API made it into the binary — and, tellingly, t ### 6.1 Build `lm` ```bash -nix build 'github:logos-co/logos-module/0.2.0#lm' --out-link ./lm +nix build 'github:logos-co/logos-module#lm' --out-link ./lm ``` ### 6.2 View metadata — note the empty dependency list @@ -426,11 +426,11 @@ Now the payoff: run `calc_via_interface` and bind its `calculator` interface to Build `logoscore` and the package manager, then install **both** modules into a `modules/` directory. `calc_via_interface` comes from this project; `calc_module` from your Part 1 checkout — it is the *provider* we bind to, even though this module never declared it: ```bash -nix build 'github:logos-co/logos-logoscore-cli/0.2.0' --out-link ./logos +nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos ``` ```bash -nix build 'github:logos-co/logos-package-manager/0.2.0#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm ``` ```bash @@ -575,7 +575,7 @@ and declare the matching input in `flake.nix` (the input attribute name must equ ```nix inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; calc_interfaces.url = "github:your-org/logos-calc-interfaces"; }; ``` diff --git a/outputs/tutorial-qml-ui-app.md b/outputs/tutorial-qml-ui-app.md index 315ea35..a909237 100644 --- a/outputs/tutorial-qml-ui-app.md +++ b/outputs/tutorial-qml-ui-app.md @@ -47,7 +47,7 @@ Create a new directory and initialise it from the QML module template: `mkdir logos-calc-ui && cd logos-calc-ui` ```bash -nix flake init -t github:logos-co/logos-module-builder/0.2.0#ui-qml +nix flake init -t github:logos-co/logos-module-builder#ui-qml ``` > **Note:** The generated `flake.nix` uses an unpinned `logos-module-builder` URL. Replace it with the pinned version shown in [Step 4](#step-4-update-flakenix) to ensure reproducible builds. @@ -330,7 +330,7 @@ The template already has everything wired up. Update the description and add `ca description = "Calculator QML UI Plugin for Logos - frontend for calc_module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # Points at your local calc_module checkout. This is a placeholder — # you lock it to your actual path in the next step with @@ -574,7 +574,7 @@ nix build '.#lgx-portable' --out-link result-lgx-portable Build the basecamp desktop shell: ```bash -nix build 'github:logos-co/logos-basecamp/0.2.0' -o basecamp-result +nix build 'github:logos-co/logos-basecamp' -o basecamp-result ``` Basecamp manages its own per-user data directory and preinstalls its bundled modules (`main_ui`, `package_manager`, …) from the build. It does **not** accept `--modules-dir` / `--ui-plugins-dir` flags; instead you point it at a data directory with `--user-dir` (or the `LOGOS_USER_DIR` env var), and it reads installed core modules from `/modules` and UI plugins from `/plugins` — exactly the directories `lgpm` writes to. @@ -586,7 +586,7 @@ For this tutorial we use an explicit data directory, `basecamp-data`, so the ins `lgpm` installs `.lgx` packages into a modules/plugins directory: ```bash -nix build 'github:logos-co/logos-package-manager/0.2.0#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm ``` ### 8.4 Create the data directory @@ -645,7 +645,7 @@ The sidebar labels each UI plugin by its `name` from `metadata.json`, which is w The dev build above depends on nix store paths at runtime. For a self-contained portable build that works without nix: ```bash -nix build 'github:logos-co/logos-basecamp/0.2.0#bin-bundle-dir' -o basecamp-portable +nix build 'github:logos-co/logos-basecamp#bin-bundle-dir' -o basecamp-portable ``` ```bash @@ -692,38 +692,37 @@ Instead of using `lgpm` on the command line, you can install modules through the A `calc_ui` tab appears in the sidebar (UI plugins are labelled by their `name` from `metadata.json`). Clicking it loads your `Main.qml`. -### 8.10 Live reloading with `logos-standalone-app` +### 8.10 Hot-reloading QML with `nix build .#ui-dev` -For QML iteration, set `DEV_QML_PATH` to the directory that contains your view entry file (the basename from `metadata.json` `view` must exist under that directory). For this tutorial's layout (`view`: `Main.qml` at repo root): +For QML iteration, build the dev launcher once. After that, QML edits need no rebuild at all: ```bash -DEV_QML_PATH=$PWD nix run . +nix build .#ui-dev +./result/bin/run-logos-standalone-ui ``` -When `DEV_QML_PATH` is set, `logos-standalone-app` loads QML from your source tree at runtime instead of the installed copy — so edits in `Main.qml` are picked up on the next relaunch without you having to manually re-sync files. +Run from the repo root and the launcher finds your QML source automatically, then watches it. Edit a `.qml` file, save, and the view re-renders in about 200 ms. It reports what it picked up on startup: -**Important — what this does *not* skip.** `nix run` always re-evaluates the flake and rehashes the source tree before launching. By default `src = ./.` includes every tracked file, including `*.qml` — so: +``` +run-logos-standalone-ui: hot-reloading QML from /path/to/logos-calc-ui + (export DEV_QML_PATH to override, or LOGOS_QML_HOT_RELOAD=0 to disable) +``` -- **Any source change, including QML edits, rebuilds the plugin** before the app starts. `DEV_QML_PATH` only kicks in *after* the build is done; it doesn't shortcut the rebuild itself. -- **C++ / `.rep` / `metadata.json` / CMake changes** rebuild as normal. -- The flake-evaluation overhead on each `nix run` is fixed and unavoidable while invoking through nix. +`ui-dev` is the same wrapper `nix run .` uses — dependency modules bundled and loaded identically — exposed as a package so it lands in `./result/bin`. It is a development target and is never bundled into `.lgx` packages. -For the absolute fastest loop (no nix involvement after the first build), do the build once and run the resulting binary directly: +**What reloads, and what doesn't.** -```bash -# Build once — populates result/ in the nix store -nix build . - -# Subsequent runs: invoke the bundled standalone wrapper directly, -# skipping nix entirely. DEV_QML_PATH still redirects QML loading. -DEV_QML_PATH=$PWD ./result/bin/run-logos-standalone-ui -``` +- **Any `.qml`/`.js` under your view directory**, including files and folders created after launching. +- **The backend keeps running.** A module's C++ backend lives in a separate `ui-host` process, so its state and connections survive a reload. +- **QML-side state resets** — scroll position, text fields, current tab. +- **A syntax error is recoverable.** It's logged with a line number and the view blanks; the next save that compiles restores it. +- **C++, `.rep`, `metadata.json` and CMake changes still need a rebuild.** Re-run `nix build .#ui-dev` and relaunch. -(Adjust the binary name to whatever `ls result/bin/` shows on your build.) +**Why not `nix run .`?** It re-evaluates the flake and rehashes the source tree on every invocation. Since `src = ./.` covers every tracked file including `*.qml`, even a one-character QML edit rebuilds the plugin before the app starts. Building `ui-dev` once avoids that entirely. -> **Naming:** Only `DEV_QML_PATH` is honored. See `repos/logos-standalone-app/README.md`. +> **Custom layouts:** the launcher looks for the `view` entry from `metadata.json` under `src//`, then `/`. If your tree differs, set `DEV_QML_PATH` to the directory holding the entry file and it takes precedence. -> This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so changes to your source files are not reflected until you rebuild and reinstall the `.lgx` package. +> This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so source edits are not reflected until you rebuild and reinstall the `.lgx` package. ### 8.11 Testing without any runtime diff --git a/outputs/tutorial-wrapping-c-library.md b/outputs/tutorial-wrapping-c-library.md index 9c99e5a..4f3f40c 100644 --- a/outputs/tutorial-wrapping-c-library.md +++ b/outputs/tutorial-wrapping-c-library.md @@ -40,10 +40,10 @@ For a module that wraps an external C library: `mkdir logos-calc-module && cd logos-calc-module` ```bash -nix flake init -t github:logos-co/logos-module-builder/0.2.0#with-external-lib +nix flake init -t github:logos-co/logos-module-builder#with-external-lib # Or for a plain module (no external library): -# nix flake init -t github:logos-co/logos-module-builder/0.2.0 +# nix flake init -t github:logos-co/logos-module-builder ``` This generates skeleton files (`flake.nix`, `metadata.json`, `CMakeLists.txt`, and a `src/` directory) pre-configured for the logos-module-builder. You then customize them for your specific library. @@ -327,7 +327,7 @@ Change `description`. Add flake inputs here if your module depends on other modu description = "Calculator module - wraps libcalc C library for Logos"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; }; outputs = inputs@{ logos-module-builder, ... }: @@ -579,7 +579,7 @@ Use the `lm` CLI tool (from `logos-module`) to inspect the compiled module binar The `lm` CLI inspects compiled module binaries. Build it from the `logos-module` repo: ```bash -nix build 'github:logos-co/logos-module/0.2.0#lm' --out-link ./lm +nix build 'github:logos-co/logos-module#lm' --out-link ./lm ``` ### 5.2 View metadata @@ -739,7 +739,7 @@ Interface screen. ### 6.1 Build logoscore ```bash -nix build 'github:logos-co/logos-logoscore-cli/0.2.0' --out-link ./logos +nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos ``` ### 6.2 Set up the modules directory @@ -751,7 +751,7 @@ nix build '.#lgx' ``` ```bash -nix build 'github:logos-co/logos-package-manager/0.2.0#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm ``` ```bash @@ -897,7 +897,7 @@ Add a `tests` block to the `mkLogosModule` call. `mockCLibs` lists the external description = "Calculator module - wraps libcalc C library for Logos"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; }; outputs = inputs@{ logos-module-builder, ... }: @@ -1098,7 +1098,7 @@ nix build '.#lgx-portable' --out-link result-lgx-portable To install a portable package on another machine: ```bash -nix build 'github:logos-co/logos-package-manager/0.2.0#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm ./pm/bin/lgpm --modules-dir ./modules install --file result-lgx-portable/*.lgx ``` @@ -1217,7 +1217,7 @@ Instead of pre-building the library and placing it in `lib/`, you can have Nix f description = "Module wrapping libfoo from GitHub"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder/0.2.0"; + logos-module-builder.url = "github:logos-co/logos-module-builder"; # Fetch the library source (non-flake) libfoo-src = { diff --git a/tests/tutorial-cpp-ui-app.test.yaml b/tests/tutorial-cpp-ui-app.test.yaml index 4f4c153..6ee7192 100644 --- a/tests/tutorial-cpp-ui-app.test.yaml +++ b/tests/tutorial-cpp-ui-app.test.yaml @@ -859,42 +859,40 @@ sections: - **READWRITE PROP** — `Memory: 0` → `Memory: 8` proves the *write* direction: the Store button assigned `backend.memory = 8` in QML, which pushed to the backend source and synced back to the label. Properties aren't read-only mirrors; QML can drive them too. - **Event-fed PROP** — `Version event: 1.0.0` is the event path: clicking *Announce version* called `calc_module.libVersionNotify()`, which emitted `versionReady("1.0.0")`; the backend's `modules().calc_module.onVersionReady(...)` subscription — armed in `onContextReady()` — caught it and wrote the `versionEvent` PROP, which Qt Remote Objects synced into the view. The label was `(none yet)` until the event fired, so seeing the version proves the typed subscription delivered. - # ── Step 10: Live reloading (prose only) ────────────────────────────────────── - - title: "Live reloading QML with `DEV_QML_PATH`" + # ── Step 10: Hot reload (prose only) ───────────────────────────────────────── + - title: "Hot-reloading QML with `nix build .#ui-dev`" step: true text: | - For QML iteration, point `DEV_QML_PATH` at the directory that contains your view entry's **basename** (from `metadata.json` `"view"`). This tutorial sets `"view": "qml/Main.qml"`, so the directory must contain `Main.qml` (here: `src/qml/`): + For QML iteration, build the dev launcher once. After that, QML edits need no rebuild at all: ```bash - DEV_QML_PATH=$PWD/src/qml nix run . + nix build .#ui-dev + ./result/bin/run-logos-standalone-ui ``` - When `DEV_QML_PATH` is set, `logos-standalone-app` loads QML from your source tree at runtime instead of the installed copy — so edits to `Main.qml` (and any QML under that tree) are picked up on the next relaunch without you having to re-sync files. + Run from the repo root and the launcher finds your QML source automatically, then watches it. Edit a `.qml` file, save, and the view re-renders in about 200 ms. It reports what it picked up on startup: - **Important — what this does *not* skip.** `nix run` always re-evaluates the flake and rehashes the source tree before launching. By default `src = ./.` includes every tracked file, including `*.qml` — so: + ``` + run-logos-standalone-ui: hot-reloading QML from /path/to/logos-calc-ui-cpp/src/qml + (export DEV_QML_PATH to override, or LOGOS_QML_HOT_RELOAD=0 to disable) + ``` - - **Any source change, including QML edits, rebuilds the plugin** before the app starts. `DEV_QML_PATH` only kicks in *after* the build is done; it doesn't shortcut the rebuild itself. - - **C++ / `.rep` / `metadata.json` / CMake changes** rebuild as normal. - - The flake-evaluation overhead on each `nix run` is fixed and unavoidable while invoking through nix. + `ui-dev` is the same wrapper `nix run .` uses — dependency modules bundled and loaded identically — exposed as a package so it lands in `./result/bin`. It is a development target and is never bundled into `.lgx` packages. - For the absolute fastest loop (no nix involvement after the first build), do the build once and run the resulting binary directly: + **What reloads, and what doesn't.** - ```bash - # Build once — populates result/ in the nix store - nix build . - - # Subsequent runs: invoke the bundled standalone wrapper directly, - # skipping nix entirely. DEV_QML_PATH still redirects QML loading. - DEV_QML_PATH=$PWD/src/qml ./result/bin/run-logos-standalone-ui - ``` + - **Any `.qml`/`.js` under your view directory**, including files and folders created after launching. + - **The backend keeps running.** A module's C++ backend lives in a separate `ui-host` process, so its state and connections survive a reload. + - **QML-side state resets** — scroll position, text fields, current tab. + - **A syntax error is recoverable.** It's logged with a line number and the view blanks; the next save that compiles restores it. + - **C++, `.rep`, `metadata.json` and CMake changes still need a rebuild.** Re-run `nix build .#ui-dev` and relaunch. - (Adjust the binary name to whatever `ls result/bin/` shows on your build.) + **Why not `nix run .`?** It re-evaluates the flake and rehashes the source tree on every invocation. Since `src = ./.` covers every tracked file including `*.qml`, even a one-character QML edit rebuilds the plugin before the app starts. Building `ui-dev` once avoids that entirely. - > **Naming:** Only `DEV_QML_PATH` is honored by `logos-standalone-app`. See `repos/logos-standalone-app/README.md`. + > **Custom layouts:** the launcher looks for the `view` entry from `metadata.json` under `src//`, then `/`. If your tree differs, set `DEV_QML_PATH` to the directory holding the entry file and it takes precedence. - > This does not work with `logos-basecamp` — Basecamp loads QML plugins from its own install tree, so source edits are not picked up until you rebuild and reinstall the `.lgx`. + > This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so source edits are not reflected until you rebuild and reinstall the `.lgx` package. - # ── Step 11: How the Pieces Connect (prose only) ────────────────────────────── - title: "How the Pieces Connect" step: true text: | diff --git a/tests/tutorial-qml-ui-app.test.yaml b/tests/tutorial-qml-ui-app.test.yaml index 301b436..11066d2 100644 --- a/tests/tutorial-qml-ui-app.test.yaml +++ b/tests/tutorial-qml-ui-app.test.yaml @@ -785,38 +785,37 @@ sections: A `calc_ui` tab appears in the sidebar (UI plugins are labelled by their `name` from `metadata.json`). Clicking it loads your `Main.qml`. - - title: "Live reloading with `logos-standalone-app`" + - title: "Hot-reloading QML with `nix build .#ui-dev`" text: | - For QML iteration, set `DEV_QML_PATH` to the directory that contains your view entry file (the basename from `metadata.json` `view` must exist under that directory). For this tutorial's layout (`view`: `Main.qml` at repo root): + For QML iteration, build the dev launcher once. After that, QML edits need no rebuild at all: ```bash - DEV_QML_PATH=$PWD nix run . + nix build .#ui-dev + ./result/bin/run-logos-standalone-ui ``` - When `DEV_QML_PATH` is set, `logos-standalone-app` loads QML from your source tree at runtime instead of the installed copy — so edits in `Main.qml` are picked up on the next relaunch without you having to manually re-sync files. + Run from the repo root and the launcher finds your QML source automatically, then watches it. Edit a `.qml` file, save, and the view re-renders in about 200 ms. It reports what it picked up on startup: - **Important — what this does *not* skip.** `nix run` always re-evaluates the flake and rehashes the source tree before launching. By default `src = ./.` includes every tracked file, including `*.qml` — so: + ``` + run-logos-standalone-ui: hot-reloading QML from /path/to/logos-calc-ui + (export DEV_QML_PATH to override, or LOGOS_QML_HOT_RELOAD=0 to disable) + ``` - - **Any source change, including QML edits, rebuilds the plugin** before the app starts. `DEV_QML_PATH` only kicks in *after* the build is done; it doesn't shortcut the rebuild itself. - - **C++ / `.rep` / `metadata.json` / CMake changes** rebuild as normal. - - The flake-evaluation overhead on each `nix run` is fixed and unavoidable while invoking through nix. + `ui-dev` is the same wrapper `nix run .` uses — dependency modules bundled and loaded identically — exposed as a package so it lands in `./result/bin`. It is a development target and is never bundled into `.lgx` packages. - For the absolute fastest loop (no nix involvement after the first build), do the build once and run the resulting binary directly: + **What reloads, and what doesn't.** - ```bash - # Build once — populates result/ in the nix store - nix build . - - # Subsequent runs: invoke the bundled standalone wrapper directly, - # skipping nix entirely. DEV_QML_PATH still redirects QML loading. - DEV_QML_PATH=$PWD ./result/bin/run-logos-standalone-ui - ``` + - **Any `.qml`/`.js` under your view directory**, including files and folders created after launching. + - **The backend keeps running.** A module's C++ backend lives in a separate `ui-host` process, so its state and connections survive a reload. + - **QML-side state resets** — scroll position, text fields, current tab. + - **A syntax error is recoverable.** It's logged with a line number and the view blanks; the next save that compiles restores it. + - **C++, `.rep`, `metadata.json` and CMake changes still need a rebuild.** Re-run `nix build .#ui-dev` and relaunch. - (Adjust the binary name to whatever `ls result/bin/` shows on your build.) + **Why not `nix run .`?** It re-evaluates the flake and rehashes the source tree on every invocation. Since `src = ./.` covers every tracked file including `*.qml`, even a one-character QML edit rebuilds the plugin before the app starts. Building `ui-dev` once avoids that entirely. - > **Naming:** Only `DEV_QML_PATH` is honored. See `repos/logos-standalone-app/README.md`. + > **Custom layouts:** the launcher looks for the `view` entry from `metadata.json` under `src//`, then `/`. If your tree differs, set `DEV_QML_PATH` to the directory holding the entry file and it takes precedence. - > This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so changes to your source files are not reflected until you rebuild and reinstall the `.lgx` package. + > This does not work with `logos-basecamp`. Basecamp loads QML plugins from its own data directory, so source edits are not reflected until you rebuild and reinstall the `.lgx` package. - title: "Testing without any runtime" text: |