Skip to content

feat: update tutorials for ui modules ot use qml hot reloading correctly as per latest changes #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Khushboo-dev-cpp wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

feat: update tutorials for ui modules ot use qml hot reloading correctly as per latest changes #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion outputs/logos-calc-aggregator-module/flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion outputs/logos-calc-module/flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, ... }:
Expand Down
2 changes: 1 addition & 1 deletion outputs/logos-calc-ui-cpp/flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion outputs/logos-calc-ui/flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion outputs/logos-calc-via-interface-module/flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, ... }:
Expand Down
10 changes: 5 additions & 5 deletions outputs/tutorial-composing-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
43 changes: 21 additions & 22 deletions outputs/tutorial-cpp-ui-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/<viewDir>/`, then `<viewDir>/`. 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.

---

Expand Down
12 changes: 6 additions & 6 deletions outputs/tutorial-interface-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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, ... }:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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";
};
```
Expand Down
49 changes: 24 additions & 25 deletions outputs/tutorial-qml-ui-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 `<dir>/modules` and UI plugins from `<dir>/plugins` — exactly the directories `lgpm` writes to.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/<viewDir>/`, then `<viewDir>/`. 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

Expand Down
Loading
Loading