From 13575547c911fd8b76804c5c4e86da3fd8216271 Mon Sep 17 00:00:00 2001 From: Dario Gabriel Lipicar Date: Mon, 18 May 2026 16:06:28 -0300 Subject: [PATCH] feat: pin tutorial references to tutorial-v2 - Pin all logos-co repo refs in the 4 guides to /tutorial-v2 - Fix broken cross-doc anchors (#61-running-with-logoscore, #42-building-lgx-packages) - Sync logos-calc-ui-cpp example with Part 3: add status PROP to calc_ui_cpp.rep and status binding/display to Main.qml Co-Authored-By: Claude Opus 4.7 (1M context) --- logos-calc-ui-cpp/src/calc_ui_cpp.rep | 2 + logos-calc-ui-cpp/src/qml/Main.qml | 9 ++++ logos-developer-guide.md | 66 +++++++++++++-------------- tutorial-cpp-ui-app.md | 6 +-- tutorial-qml-ui-app.md | 18 ++++---- tutorial-wrapping-c-library.md | 20 ++++---- 6 files changed, 66 insertions(+), 55 deletions(-) diff --git a/logos-calc-ui-cpp/src/calc_ui_cpp.rep b/logos-calc-ui-cpp/src/calc_ui_cpp.rep index 3d2677f..d65537f 100644 --- a/logos-calc-ui-cpp/src/calc_ui_cpp.rep +++ b/logos-calc-ui-cpp/src/calc_ui_cpp.rep @@ -1,5 +1,7 @@ class CalcUiCpp { + PROP(QString status READWRITE) + SLOT(int add(int a, int b)) SLOT(int multiply(int a, int b)) SLOT(int factorial(int n)) diff --git a/logos-calc-ui-cpp/src/qml/Main.qml b/logos-calc-ui-cpp/src/qml/Main.qml index ef2e7c4..646fa11 100644 --- a/logos-calc-ui-cpp/src/qml/Main.qml +++ b/logos-calc-ui-cpp/src/qml/Main.qml @@ -11,6 +11,9 @@ Item { // Typed replica of the backend running in ui-host (generated from calc_ui_cpp.rep). readonly property var backend: logos.module("calc_ui_cpp") + // "status" PROP from calc_ui_cpp.rep — auto-synced from the backend via Qt Remote Objects. + readonly property string status: backend ? backend.status : "" + // logos.watch() delivers the result of a replica slot call via callbacks. // No QtRemoteObjects import needed — the bridge handles it. function callCalc(method, args) { @@ -109,6 +112,12 @@ Item { } } + Text { + text: "Backend status: " + root.status + color: "#8b949e" + font.pixelSize: 13 + } + Item { Layout.fillHeight: true } } } diff --git a/logos-developer-guide.md b/logos-developer-guide.md index d1a976a..b96f128 100644 --- a/logos-developer-guide.md +++ b/logos-developer-guide.md @@ -136,16 +136,16 @@ The fastest way to create a new module is using the **logos-module-builder** tem mkdir logos-my-module && cd logos-my-module # Scaffold a minimal core module (no external dependencies) -nix flake init -t github:logos-co/logos-module-builder +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2 # Or scaffold a module that wraps an external C/C++ library -nix flake init -t github:logos-co/logos-module-builder#with-external-lib +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#with-external-lib # For ui_qml modules with C++ backend (process-isolated) -nix flake init -t github:logos-co/logos-module-builder#ui-qml-backend +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml-backend # For ui_qml modules (QML-only, no C++) -nix flake init -t github:logos-co/logos-module-builder#ui-qml +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml ``` > **Note:** The generated `flake.nix` uses an unpinned `logos-module-builder` URL. For reproducible builds, pin it to a specific commit — see the `flake.nix` examples in [Section 3.2](#32-building-lgx-packages) and the [tutorials](tutorial-wrapping-c-library.md#23-flakenix--nix-build-config). @@ -304,7 +304,7 @@ The **`lm`** tool (from `logos-module`) lets you inspect compiled module binarie #### Building lm ```bash -nix build 'github:logos-co/logos-module#lm' --out-link ./lm +nix build 'github:logos-co/logos-module/tutorial-v2#lm' --out-link ./lm ``` #### Viewing Metadata @@ -367,7 +367,7 @@ The **logos-module-viewer** is a graphical tool for inspecting loaded modules. ```bash # Build the viewer -nix build 'github:logos-co/logos-module-viewer#app' --out-link ./logos-viewer +nix build 'github:logos-co/logos-module-viewer/tutorial-v2#app' --out-link ./logos-viewer # Run it with your module ./logos-viewer/bin/logos-module-viewer -m ./result/lib/my_module_plugin.so @@ -504,7 +504,7 @@ This works because `logos-module-builder` includes `nix-bundle-lgx` as its own d ```nix { inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; }; outputs = inputs@{ logos-module-builder, ... }: @@ -522,13 +522,13 @@ You can also create `.lgx` packages using the `nix bundle` command directly. Thi ```bash # Dev variant -nix bundle --bundler github:logos-co/nix-bundle-lgx .#lib +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2 .#lib # Portable variant -nix bundle --bundler github:logos-co/nix-bundle-lgx#portable .#lib +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#portable .#lib # Dual variant (both dev and portable in one .lgx file) -nix bundle --bundler github:logos-co/nix-bundle-lgx#dual .#lib +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#dual .#lib ``` This produces a `my_module-.lgx` file in the current directory. @@ -563,7 +563,7 @@ The **`lgpm`** CLI (Logos Package Manager) installs, searches, and manages modul #### Building lgpm ```bash -nix build 'github:logos-co/logos-package-manager#cli' --out-link ./package-manager +nix build 'github:logos-co/logos-package-manager/tutorial-v2#cli' --out-link ./package-manager ``` #### Commands @@ -616,7 +616,7 @@ To download packages from the online catalog and then install them locally, use ```bash # Build lgpd -nix build 'github:logos-co/logos-package-downloader#cli' --out-link ./downloader +nix build 'github:logos-co/logos-package-downloader/tutorial-v2#cli' --out-link ./downloader # Search for packages ./downloader/bin/lgpd search waku @@ -649,7 +649,7 @@ The **`logoscore`** CLI (from `logos-liblogos`) is a headless runtime that can l #### Building logoscore ```bash -nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos +nix build 'github:logos-co/logos-logoscore-cli/tutorial-v2' --out-link ./logos ``` #### Daemon Mode @@ -751,21 +751,21 @@ logos-basecamp produces two binary variants: ```bash # Build the development version -nix build 'github:logos-co/logos-basecamp#app' --out-link ./logos-basecamp +nix build 'github:logos-co/logos-basecamp/tutorial-v2#app' --out-link ./logos-basecamp # Run the dev binary ./logos-basecamp/bin/logos-basecamp # Build the portable/distributed version -nix build 'github:logos-co/logos-basecamp#portable' --out-link ./logos-basecamp-portable +nix build 'github:logos-co/logos-basecamp/tutorial-v2#portable' --out-link ./logos-basecamp-portable # Or build platform-specific distributions: -nix build 'github:logos-co/logos-basecamp#bin-bundle-dir' # Flat directory bundle -nix build 'github:logos-co/logos-basecamp#bin-appimage' # Linux AppImage -nix build 'github:logos-co/logos-basecamp#bin-macos-app' # macOS .app bundle +nix build 'github:logos-co/logos-basecamp/tutorial-v2#bin-bundle-dir' # Flat directory bundle +nix build 'github:logos-co/logos-basecamp/tutorial-v2#bin-appimage' # Linux AppImage +nix build 'github:logos-co/logos-basecamp/tutorial-v2#bin-macos-app' # macOS .app bundle ``` -> **Note:** When installing modules into logos-basecamp, the LGX variant type must match the build type. Dev builds of basecamp expect **dev** LGX variants (e.g., `darwin-arm64-dev`), while portable builds expect **portable** variants (e.g., `darwin-arm64`). Use the `dual` bundler (see [3.2](#32-bundling-with-nix-bundle-lgx)) to produce packages that work with both. +> **Note:** When installing modules into logos-basecamp, the LGX variant type must match the build type. Dev builds of basecamp expect **dev** LGX variants (e.g., `darwin-arm64-dev`), while portable builds expect **portable** variants (e.g., `darwin-arm64`). Use the `dual` bundler (see [4.2](#42-building-lgx-packages)) to produce packages that work with both. ### 7.2 Module Types in logos-basecamp @@ -818,7 +818,7 @@ Text { text: backend.status } logos.watch(backend.add(1, 2), function(v) { ... }) ``` -- Scaffold: `nix flake init -t github:logos-co/logos-module-builder#ui-qml-backend` +- Scaffold: `nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml-backend` - See [Tutorial Part 3](tutorial-cpp-ui-app.md) for a complete walkthrough #### ui_qml QML-Only (In-Process) @@ -829,7 +829,7 @@ These have `"type": "ui_qml"` with `"view"` but no `"main"` — pure QML, no C++ - No `.rep` file needed - Call core modules via the `logos` bridge: `logos.callModule("module", "method", [args])` - Network access denied, filesystem restricted to module directory -- Scaffold: `nix flake init -t github:logos-co/logos-module-builder#ui-qml` +- Scaffold: `nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml` - See [Tutorial Part 2](tutorial-qml-ui-app.md) for a complete walkthrough --- @@ -883,7 +883,7 @@ The generator is bundled with `logos-cpp-sdk`. It is automatically available: - **In `nix develop`** -- the module dev shell includes the SDK on PATH - **Build it directly:** ```bash - nix build 'github:logos-co/logos-cpp-sdk#cpp-generator' --out-link ./cpp-gen + nix build 'github:logos-co/logos-cpp-sdk/tutorial-v2#cpp-generator' --out-link ./cpp-gen ./cpp-gen/bin/logos-cpp-generator --help ``` @@ -1100,9 +1100,9 @@ nix build .#lgx # Dev vari nix build .#lgx-portable # Portable variant # Alternative: nix bundle command -nix bundle --bundler github:logos-co/nix-bundle-lgx .#lib # Dev variant -nix bundle --bundler github:logos-co/nix-bundle-lgx#portable .#lib # Portable variant -nix bundle --bundler github:logos-co/nix-bundle-lgx#dual .#lib # Both variants +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2 .#lib # Dev variant +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#portable .#lib # Portable variant +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#dual .#lib # Both variants ``` --- @@ -1182,8 +1182,8 @@ When running a UI module with `nix run`, the standalone app automatically bundle ```nix inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; - calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; + calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; storage_module.url = "github:logos-co/logos-storage-module"; }; ``` @@ -1203,8 +1203,8 @@ When running a UI module with `nix run`, the standalone app automatically bundle { description = "My UI module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; - calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; + calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; }; outputs = inputs@{ logos-module-builder, ... }: logos-module-builder.lib.mkLogosQmlModule { @@ -1221,8 +1221,8 @@ When running a UI module with `nix run`, the standalone app automatically bundle { description = "My QML UI module"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; - calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; + calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; }; outputs = inputs@{ logos-module-builder, ... }: logos-module-builder.lib.mkLogosQmlModule { @@ -1253,7 +1253,7 @@ If a module installs but fails to load, the variant type may not match: - **Dev build** of logos-basecamp needs **dev** LGX variants (`darwin-arm64-dev`) - **Portable build** needs **portable** variants (`darwin-arm64`) -- Use `nix build .#lgx` and `nix build .#lgx-portable` to produce each variant separately, or `nix bundle --bundler github:logos-co/nix-bundle-lgx#dual .#lib` for a single package with both variants +- Use `nix build .#lgx` and `nix build .#lgx-portable` to produce each variant separately, or `nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#dual .#lib` for a single package with both variants ### Cross-platform builds @@ -1264,7 +1264,7 @@ Build on each target platform separately to create `.lgx` packages: nix build .#lgx-portable # Or using nix bundle for dual variant: -nix bundle --bundler github:logos-co/nix-bundle-lgx#dual .#lib +nix bundle --bundler github:logos-co/nix-bundle-lgx/tutorial-v2#dual .#lib # Then merge platform-specific .lgx files into one: ./lgx/bin/lgx merge my_module-linux.lgx my_module-macos.lgx -o my_module.lgx diff --git a/tutorial-cpp-ui-app.md b/tutorial-cpp-ui-app.md index e411dfb..32f12df 100644 --- a/tutorial-cpp-ui-app.md +++ b/tutorial-cpp-ui-app.md @@ -69,7 +69,7 @@ The `.rep` file declares the interface. At build time, Qt's `repc` compiler gene ```bash mkdir logos-calc-ui-cpp && cd logos-calc-ui-cpp -nix flake init -t github:logos-co/logos-module-builder#ui-qml-backend +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml-backend git init && git add -A ``` @@ -469,10 +469,10 @@ Feel free to report bugs, file feature requests, or contribute components / them description = "Calculator C++ UI plugin — QML view with process-isolated backend"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; # Option A: point to a remote repo (for CI or when calc_module is published) - calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; + calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; # Option B: point to your local checkout (for local development) # calc_module.url = "path:../logos-calc-module"; diff --git a/tutorial-qml-ui-app.md b/tutorial-qml-ui-app.md index a84a372..608900b 100644 --- a/tutorial-qml-ui-app.md +++ b/tutorial-qml-ui-app.md @@ -48,7 +48,7 @@ Use the QML module template from `logos-module-builder`: ```bash mkdir logos-calc-ui && cd logos-calc-ui -nix flake init -t github:logos-co/logos-module-builder#ui-qml +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#ui-qml git init && git add -A ``` @@ -106,7 +106,7 @@ echo "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAmElEQVR4nO3QMREAIBDAsFeEN3 The `view` field tells the host which QML file to load for the UI. The `dependencies` field tells the host to load `calc_module` before showing your UI. -> **Naming convention:** Each entry in `dependencies` must match the `name` field in that module's own `metadata.json`. When adding a dependency as a flake input, the **input attribute name** must also match the dependency name — e.g., `calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"`. The URL can point to any repo, but the attribute name is how the builder resolves dependencies. +> **Naming convention:** Each entry in `dependencies` must match the `name` field in that module's own `metadata.json`. When adding a dependency as a flake input, the **input attribute name** must also match the dependency name — e.g., `calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"`. The URL can point to any repo, but the attribute name is how the builder resolves dependencies. --- @@ -322,10 +322,10 @@ 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"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; # Option A: point to a remote repo (for CI or when calc_module is published) - calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; + calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; # Option B: point to your local checkout (for local development) # calc_module.url = "path:../logos-calc-module"; @@ -417,7 +417,7 @@ If you're iterating on both repos side by side, you can point the flake input di ```nix # From remote: -calc_module.url = "github:logos-co/logos-tutorial?dir=logos-calc-module"; +calc_module.url = "github:logos-co/logos-tutorial/tutorial-v2?dir=logos-calc-module"; # To local: calc_module.url = "path:../logos-calc-module"; ``` @@ -546,7 +546,7 @@ nix build '.#lgx' --out-link result-lgx nix build '.#lgx-portable' --out-link result-lgx-portable ``` -> For more bundling options (standalone bundler syntax, cross-platform packaging), see the [Developer Guide — Bundling with nix-bundle-lgx](logos-developer-guide.md#32-bundling-with-nix-bundle-lgx). +> For more bundling options (standalone bundler syntax, cross-platform packaging), see the [Developer Guide — Building LGX Packages](logos-developer-guide.md#42-building-lgx-packages). ### 7.2 Build and run logos-basecamp @@ -556,7 +556,7 @@ Build logos-basecamp, launch it once to preinstall its bundled modules, then ins ```bash # Build logos-basecamp -nix build 'github:logos-co/logos-basecamp' -o basecamp-result +nix build 'github:logos-co/logos-basecamp/tutorial-v2' -o basecamp-result # Launch once to preinstall bundled modules, then close it ./basecamp-result/bin/logos-basecamp @@ -586,7 +586,7 @@ BASECAMP_DIR="$HOME/.local/share/Logos/LogosBasecampDev" ```bash # Build lgpm CLI -nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager/tutorial-v2#cli' --out-link ./pm # Install core module ./pm/bin/lgpm --modules-dir "$BASECAMP_DIR/modules" \ @@ -606,7 +606,7 @@ The dev build above depends on nix store paths at runtime. For a self-contained ```bash # Build portable basecamp (bundles all Qt frameworks/libraries) -nix build 'github:logos-co/logos-basecamp#bin-bundle-dir' -o basecamp-portable +nix build 'github:logos-co/logos-basecamp/tutorial-v2#bin-bundle-dir' -o basecamp-portable # Launch once to preinstall bundled modules ./basecamp-portable/bin/logos-basecamp diff --git a/tutorial-wrapping-c-library.md b/tutorial-wrapping-c-library.md index d9f66c7..1960440 100644 --- a/tutorial-wrapping-c-library.md +++ b/tutorial-wrapping-c-library.md @@ -37,10 +37,10 @@ Before writing any C code, scaffold the Logos module project using the official ```bash # For a module that wraps an external C library: mkdir logos-calc-module && cd logos-calc-module -nix flake init -t github:logos-co/logos-module-builder#with-external-lib +nix flake init -t github:logos-co/logos-module-builder/tutorial-v2#with-external-lib # Or for a plain module (no external library): -# nix flake init -t github:logos-co/logos-module-builder +# nix flake init -t github:logos-co/logos-module-builder/tutorial-v2 ``` > **Note:** The generated `flake.nix` uses an unpinned `logos-module-builder` URL. Replace it with the pinned version shown in [Step 2.3](#23-flakenix--nix-build-config) to ensure reproducible builds. @@ -302,7 +302,7 @@ The `if/elseif/else` block above it is boilerplate — don't change it. description = "Calculator module - wraps libcalc C library for Logos"; inputs = { - logos-module-builder.url = "github:logos-co/logos-module-builder"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; }; outputs = inputs@{ logos-module-builder, ... }: @@ -573,7 +573,7 @@ Both library files are placed together so the plugin can find the C library at r The `lm` CLI tool (from `logos-module`) inspects compiled module binaries: ```bash -nix build 'github:logos-co/logos-module#lm' --out-link ./lm +nix build 'github:logos-co/logos-module/tutorial-v2#lm' --out-link ./lm ``` ### 4.2 View metadata @@ -681,7 +681,7 @@ For scripting and CI, use `--json`: ### 5.1 Build logoscore ```bash -nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos +nix build 'github:logos-co/logos-logoscore-cli/tutorial-v2' --out-link ./logos ``` ### 5.2 Set up the modules directory @@ -693,7 +693,7 @@ nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos nix build '.#lgx' # Install it into a modules directory using the Logos Package Manager -nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager/tutorial-v2#cli' --out-link ./pm mkdir -p modules ./pm/bin/lgpm --modules-dir ./modules install --file result/*.lgx ``` @@ -729,7 +729,7 @@ Start the daemon and call methods: ./logos/bin/logoscore stop ``` -> For inline (legacy) mode and other logoscore options, see the [Developer Guide -- Running with logoscore](logos-developer-guide.md#51-running-with-logoscore). +> For inline (legacy) mode and other logoscore options, see the [Developer Guide -- Running with logoscore](logos-developer-guide.md#61-running-with-logoscore). **What happens under the hood:** @@ -774,12 +774,12 @@ nix build '.#lgx' --out-link result-lgx nix build '.#lgx-portable' --out-link result-lgx-portable ``` -> For more bundling options (standalone bundler syntax, cross-platform packaging), see the [Developer Guide — Bundling with nix-bundle-lgx](logos-developer-guide.md#32-bundling-with-nix-bundle-lgx). +> For more bundling options (standalone bundler syntax, cross-platform packaging), see the [Developer Guide — Building LGX Packages](logos-developer-guide.md#42-building-lgx-packages). To install a portable package on another machine: ```bash -nix build 'github:logos-co/logos-package-manager#cli' --out-link ./pm +nix build 'github:logos-co/logos-package-manager/tutorial-v2#cli' --out-link ./pm ./pm/bin/lgpm --modules-dir ./modules install --file result-lgx-portable/*.lgx ``` @@ -894,7 +894,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"; + logos-module-builder.url = "github:logos-co/logos-module-builder/tutorial-v2"; # Fetch the library source (non-flake) libfoo-src = {