diff options
| author | Christian Kolset <christian.kolset@gmail.com> | 2026-08-01 19:06:36 -0600 |
|---|---|---|
| committer | Christian Kolset <christian.kolset@gmail.com> | 2026-08-01 19:06:36 -0600 |
| commit | 0aa59c13af65beeae104662593b21ba4d8a37789 (patch) | |
| tree | 17a1e6bd92a3a236bef0bca2e11ca7a875ba6caa /docs | |
| parent | bfbdd0c19910f464e779fa64cc0ec8590f8e37c1 (diff) | |
Rename LabDAQ → LabUI and overhaul plugin system
Branding:
- Rename app, window title, file extension (.labdaq → .labui), user data
dirs (~/.labui/), spec file (labdaq.spec → labui.spec), and APP_NAME
throughout all source, docs, and config files
Plugin system:
- Plugins no longer bundled in the PyInstaller build — installed at
runtime by users via Settings → Plugins → Install Plugin (zip)
- PluginManager now takes user_dir + extra_scan_dirs; user plugins live
in ~/.labui/plugins/, dev scan additionally covers project plugins/
- install_from_zip / uninstall / is_user_installed added to PluginManager
- vendor/ dir inside plugin zips: prepended to sys.path at load time so
plugins can ship their own deps without requiring pip on end-user machine
- source_url field in manifest.json: shown as Download button in the
missing-plugins dialog when a profile requires an absent plugin
- Frozen-app pip install now targets ~/.labui/plugin_packages/ using a
real system Python (sys.executable is the exe in frozen builds)
Profile loading:
- Profile now stores plugins_manifest snapshot (id, name, version,
source_url) alongside plugins_enabled
- On load, missing or dep-broken plugins trigger MissingPluginsDialog
before the rest of the profile is applied; user can install from zip
or download via source_url in-dialog, or cancel the load
- Plugin reconciliation only enables installed plugins — missing ones
are not written to enabled.json
UI:
- Version label added to status bar (bottom-right, muted colour)
- Settings → Plugins tab: Install Plugin… button, per-plugin Remove
button for user-installed plugins, live list refresh after install/remove
Docs:
- New docs/building.md covers the full release pipeline
- docs/plugin-development.md updated for new install flow, vendoring,
source_url, profile behaviour, and distribution instructions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/building.md | 113 | ||||
| -rw-r--r-- | docs/plugin-development.md | 10 |
2 files changed, 118 insertions, 5 deletions
diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 0000000..e20bcd3 --- /dev/null +++ b/docs/building.md @@ -0,0 +1,113 @@ +# Building LabUI from Source + +Produces a standalone `dist/LabUI/` directory (onedir, not onefile — required for tufup's per-file update patching). + +## Prerequisites + +Python 3.10+ and the dev requirements: + +```bash +pip install -r requirements.txt +pip install -r requirements-dev.txt +``` + +`requirements-dev.txt` adds PyInstaller and tufup on top of the runtime deps. + +## First-time setup — TUF repository + +Skip this if the `scripts/release/keystore/` directory already exists (i.e. someone else on the team has already initialised the repo and shared the keystore out-of-band). + +```bash +python scripts/release/repo_init.py +``` + +This generates: + +- `scripts/release/keystore/` — private + public keys for the TUF root/targets/snapshot/timestamp roles. **Back this up somewhere private outside the repo. Losing the root key means existing installs can never receive trusted updates.** +- `scripts/release/repository/` — initial signed TUF metadata, including `root.json`. + +After init, build once more so the freshly-generated `root.json` gets bundled into the app (the `.spec` file only includes it if it already exists): + +```bash +pyinstaller labui.spec +``` + +## Building a release + +### 1. Bump the version + +Edit `core/version.py`: + +```python +__version__ = "1.2.3" +``` + +This single value is read by the auto-updater at runtime (`core/updater.py`) and by the release script when signing the new target. + +### 2. Build the executable + +```bash +pyinstaller labui.spec +``` + +Output: `dist/LabUI/LabUI` (Linux/macOS) or `dist/LabUI/LabUI.exe` (Windows). + +The build bundles: +- `ui/style_dark.qss` and `ui/style_light.qss` +- `scripts/release/repository/metadata/root.json` (if present — enables trusted updates on fresh installs) + +Plugins are **not bundled**. They are installed at runtime by the user via **Settings → Plugins → Install Plugin…**. Installed plugins and their enabled state live in `~/.labui/plugins/`. Plugin pip dependencies (for machines without Python) land in `~/.labui/plugin_packages/`, which is added to `sys.path` at startup. + +### 3. Sign the release target + +```bash +python scripts/release/repo_release.py +``` + +Creates and signs `scripts/release/repository/targets/labui-<version>.tar.gz` and updates the TUF metadata files in `scripts/release/repository/metadata/`. + +### 4. Publish to GitHub + +Upload every file from `scripts/release/repository/metadata/` and `scripts/release/repository/targets/` to the GitHub Release tagged **`updates`** (fixed tag — not a version tag), replacing any same-named files already there. + +The app's updater always points at `.../releases/download/updates/`, so the tag must stay constant across versions. + +Optionally create a separate human-facing release with a changelog under a version tag (e.g. `v1.2.3`). + +### 5. Verify + +Launch a previous installed version → Settings → Check for Updates → confirm it finds and applies the new version. + +## Re-signing expired metadata + +TUF metadata expires even with no new release (`root`: 365 days, others: 90 days). If metadata goes stale before the next release, clients reject it. Re-sign: + +```bash +python -m tufup sign snapshot scripts/release/keystore +python -m tufup sign timestamp scripts/release/keystore +``` + +Run from the repo root. Re-upload the resulting files to the `updates` release. + +## What's bundled vs. external + +| Item | Bundled in exe? | Notes | +|------|----------------|-------| +| Python runtime | Yes | PyInstaller includes it | +| PyQt6 / pyqtgraph / numpy | Yes | | +| QSS theme files | Yes | copied from `ui/` | +| Plugins | No | installed by users into `~/.labui/plugins/` at runtime | +| Plugin pip deps | No | installed into `~/.labui/plugin_packages/` or vendored inside plugin zip | +| `root.json` | Yes (if present) | TUF trust bootstrap | +| `nidaqmx` | No | optional; NI runtime must be installed separately | +| `opencv-python` | No | optional; only needed if a plugin requires it (vendor it in the plugin zip) | + +## Troubleshooting + +**`ModuleNotFoundError` at launch** — a hidden import PyInstaller missed. Add it to `hiddenimports` in `labui.spec` and rebuild. + +**Plugin not loading in built app** — plugins are not bundled; the user must install them via Settings → Plugins. If the plugin loads but fails silently, check that its `vendor/` folder contains all required packages, or that the user has pip-installed them (they land in `~/.labui/plugin_packages/`). + +**Plugin dependency not importable after pip install** — the user may need to restart the app so `~/.labui/plugin_packages/` is injected into `sys.path` (this happens in `main.py` at startup). + +**`root.json` not bundled** — run `repo_init.py` first (see First-time setup), then rebuild. diff --git a/docs/plugin-development.md b/docs/plugin-development.md index b0c3a63..8722376 100644 --- a/docs/plugin-development.md +++ b/docs/plugin-development.md @@ -1,4 +1,4 @@ -# LabDAQ Plugin Development Guide +# LabUI Plugin Development Guide Plugins live under `plugins/` as self-contained directories. The app discovers them automatically; the user enables or disables them in **Settings → Plugins**. A disabled plugin leaves zero trace in the UI. @@ -287,7 +287,7 @@ The widget is created once when the plugin loads. Apply changes immediately (no ### 5.5 Profile persistence -`.labdaq` profiles save the **enabled plugin list** automatically — loading a profile enables/disables plugins to match the saved state. Per-plugin configuration state is also saved if you implement these two methods. +`.labui` profiles save the **enabled plugin list** automatically — loading a profile enables/disables plugins to match the saved state. Per-plugin configuration state is also saved if you implement these two methods. ```python def get_save_state(self) -> dict: @@ -436,7 +436,7 @@ This plugin adds a sine-wave virtual channel and a toolbar button to toggle a di "name": "Sine Demo", "version": "1.0.0", "description": "Virtual sine-wave channel for testing.", - "author": "LabDAQ", + "author": "LabUI", "entry_point": "plugin.SineDemoPlugin" } ``` @@ -537,10 +537,10 @@ Import Qt widgets inside methods or inside `on_load`. This avoids import errors Stop background threads (`_running = False; _thread.join()`), disconnect signals, close windows. The app calls `on_unload()` both on user disable and on application close. **Filter `__init__` params must be JSON-serialisable.** -They are written into `.labdaq` profiles via `to_dict()` and reconstructed via `filter_from_dict()`. Stick to `int`, `float`, `str`, `bool`. +They are written into `.labui` profiles via `to_dict()` and reconstructed via `filter_from_dict()`. Stick to `int`, `float`, `str`, `bool`. **Profiles enable and disable plugins.** -Loading a `.labdaq` profile reconciles plugin state: plugins not in the profile's enabled list are disabled, plugins in the list are enabled. `apply_save_state` is called after the plugin is loaded. `plugins/enabled.json` is updated to match. +Loading a `.labui` profile reconciles plugin state: plugins not in the profile's enabled list are disabled, plugins in the list are enabled. `apply_save_state` is called after the plugin is loaded. `plugins/enabled.json` is updated to match. **Enabled state persists across restarts.** `plugins/enabled.json` is written every time a toggle changes. Delete it to reset all plugins to disabled. |
