From 01df50c3ac32331f3c9f56d01df83cf4edfdba9f Mon Sep 17 00:00:00 2001
From: salman
Date: Wed, 28 Oct 2026 17:22:53 +0100
Subject: [PATCH] Clarify installation guides and retire obsolete CGI parity
references
Put Windows and Linux setup, upgrades, and troubleshooting in dedicated manual chapters linked directly from the README. Separate user installation from maintainer packaging instructions and refresh generated HTML/PDF manuals.
Remove stale checklist references and completed legacy gap descriptions while preserving relevant future workflow improvements and historical release notes.
---
README.md | 93 +--
TODO.md | 52 +-
docs/DESKTOP_DEPLOYMENT.md | 295 +++------
.../html/_sources/getting-started.rst.txt | 139 +---
docs/_build/html/_sources/index.rst.txt | 7 +-
.../html/_sources/install-linux.rst.txt | 135 ++++
.../html/_sources/install-windows.rst.txt | 193 ++++++
docs/_build/html/_sources/platforms.rst.txt | 31 +-
docs/_build/html/_sources/preferences.rst.txt | 10 +-
.../html/_sources/troubleshooting.rst.txt | 4 +
docs/_build/html/configuration-sharing.html | 2 +
docs/_build/html/constraints.html | 2 +
docs/_build/html/genindex.html | 2 +
docs/_build/html/getting-started.html | 133 ++--
docs/_build/html/glossary.html | 2 +
docs/_build/html/index.html | 24 +-
docs/_build/html/install-linux.html | 256 ++++++++
docs/_build/html/install-windows.html | 297 +++++++++
docs/_build/html/keyboard-shortcuts.html | 2 +
docs/_build/html/msr-editor.html | 2 +
docs/_build/html/objects.inv | Bin 758 -> 792 bytes
docs/_build/html/overview.html | 2 +
docs/_build/html/parameters-plots.html | 2 +
docs/_build/html/platforms.html | 32 +-
docs/_build/html/preferences.html | 11 +-
docs/_build/html/results-diagnostics.html | 2 +
docs/_build/html/runs-fitting.html | 6 +-
docs/_build/html/search.html | 2 +
docs/_build/html/searchindex.js | 2 +-
docs/_build/html/t0-background.html | 2 +
docs/_build/html/troubleshooting.html | 5 +
docs/_build/latex/muSRFlow.aux | 400 +++++++-----
docs/_build/latex/muSRFlow.fdb_latexmk | 20 +-
docs/_build/latex/muSRFlow.idx | 30 +-
docs/_build/latex/muSRFlow.ind | 30 +-
docs/_build/latex/muSRFlow.out | 156 +++--
docs/_build/latex/muSRFlow.pdf | Bin 154105 -> 175373 bytes
docs/_build/latex/muSRFlow.tex | 597 ++++++++++++++----
docs/_build/latex/muSRFlow.toc | 166 ++---
docs/source/getting-started.rst | 139 +---
docs/source/index.rst | 7 +-
docs/source/install-linux.rst | 135 ++++
docs/source/install-windows.rst | 193 ++++++
docs/source/platforms.rst | 31 +-
docs/source/preferences.rst | 10 +-
docs/source/troubleshooting.rst | 4 +
packaging/runtime/README.md | 39 +-
packaging/wsl2/README.md | 29 +-
48 files changed, 2562 insertions(+), 1171 deletions(-)
create mode 100644 docs/_build/html/_sources/install-linux.rst.txt
create mode 100644 docs/_build/html/_sources/install-windows.rst.txt
create mode 100644 docs/_build/html/install-linux.html
create mode 100644 docs/_build/html/install-windows.html
create mode 100644 docs/source/install-linux.rst
create mode 100644 docs/source/install-windows.rst
diff --git a/README.md b/README.md
index 2ed5883..5742a84 100644
--- a/README.md
+++ b/README.md
@@ -1,64 +1,65 @@
# muSRFlow
-muSRFlow is a desktop and web workflow for creating, editing, fitting,
-plotting, and inspecting musrfit MSR files. It wraps the `musrfit`,
-`musrview`, `msr2data`, and `dump_header` command-line tools, and provides
-interactive plotting of the fitted parameters across runs.
+muSRFlow makes fitting muSR spectra easier: create and edit MSR models, fit
+single runs or run series, inspect spectra, and plot fitted parameters.
+It is available as a desktop application and a web application.
+
+Current release candidate: **1.0.0-rc.5**.
+
+## Installation
+
+**Start with the guide for your platform.** Packaged desktop applications do
+not require Node.js or npm.
+
+| Platform | Instructions | ROOT and musrfit |
+| --- | --- | --- |
+| **Windows** | **[Install muSRFlow on Windows](docs/source/install-windows.rst)** | Included in the installer; WSL2 must be enabled first. |
+| **Linux** | **[Install muSRFlow on Linux](docs/source/install-linux.rst)** | Use a local installation or install the separate runtime. |
+| **Web** | Open your site's muSRFlow URL in a browser. | Runs on the server; no local installation. |
+
+**Already using Windows?** Read the [existing-installation update steps](docs/source/install-windows.rst#existing-installations).
+Older runtimes need the Boost-header update as well as the refreshed application.
+The Windows guide also covers WSL startup errors, `wsl.exe ENOENT`, and missing
+`libCore.so`. Native macOS packages and Flatpak packages are not available yet.
+
+Before your first desktop fit, choose a **Work directory** and **Data directory**
+in **File -> Preferences**. Keep your MSRs and results outside the application
+installation folder.
## User Manual
-The end-user manual is built with [Sphinx](https://www.sphinx-doc.org/) from
-`docs/source` (reStructuredText). The built HTML and PDF live under
-`docs/_build`. Rebuild it with:
+- [Getting started](docs/source/getting-started.rst)
+- [Manual contents and workflow chapters](docs/source/index.rst)
+- [PDF manual](docs/_build/latex/muSRFlow.pdf)
+- [HTML manual](docs/_build/html/index.html) (open locally in a browser)
+- [Troubleshooting](docs/source/troubleshooting.rst)
+
+## Development and Packaging
+
+These instructions are for working on the source code or producing installers.
+For installation on a user's computer, use the platform guides above.
+
+With Node.js and npm installed, run from the repository:
```bash
-cd docs
-make html # HTML in docs/_build/html
-make latexpdf # PDF at docs/_build/latex/muSRFlow.pdf
-```
-
-## Desktop Development
-
-Install [Node.js](https://nodejs.org/) and npm, then run:
-
-```bash
-npm install
+npm ci
npm start
```
-Dependencies only need to be installed once. Later sessions can be started with
-`npm start`.
+- [Build desktop packages and prepare releases](docs/DESKTOP_DEPLOYMENT.md)
+- [Build the ROOT + musrfit runtime](packaging/runtime/README.md)
+- [Windows WSL runtime packaging](packaging/wsl2/README.md)
+- [Roadmap and remaining work](TODO.md)
+- [Release notes](CHANGELOG.md)
-## Desktop Packages
-
-The desktop app is at version `1.0.0-rc.5` (release candidate). Linux RPM
-and AppImage release packages can be produced with:
+The manual uses Sphinx. Rebuild its HTML and PDF with:
```bash
-npm run dist:rpm
-npm run dist:appimage
+cd docs
+make html
+make latexpdf
```
-Each command also builds a matching standalone ROOT + musrfit runtime
-(`musrflow-runtime` rpm / AppImage); use `npm run dist:runtime` to build only
-the runtime artifacts. See [`docs/DESKTOP_DEPLOYMENT.md`](docs/DESKTOP_DEPLOYMENT.md)
-for build, runtime, and release requirements.
-
-### Windows installation
-
-The Windows x64 installer includes ROOT and musrfit in a WSL2 runtime.
-Install WSL first, then run `muSRFlow--x64.exe`; muSRFlow prepares
-its bundled runtime automatically on first launch. Node.js, npm, and a separate
-musrfit installation are not needed on the target PC.
-
-Follow the [step-by-step Windows installation guide](docs/DESKTOP_DEPLOYMENT.md#installing-on-windows)
-for WSL setup, folder preferences, and the first Plot/Fit check. Windows
-packaging instructions are in [packaging/wsl2/README.md](packaging/wsl2/README.md).
-
-The remaining work before 1.0 and the prioritized improvements are tracked in
-[`TODO.md`](TODO.md). Per-release notes are in
-[`CHANGELOG.md`](CHANGELOG.md).
-
## Web Deployment
The browser application consists of `index.html`, `quick-start.html`, `ZGUI.css`,
diff --git a/TODO.md b/TODO.md
index 44695d9..76c336f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,10 +1,11 @@
# muSRFlow Roadmap and TODO
-Last reviewed: 2026-09-23. Current version: `1.0.0-rc.5`.
+Current version: `1.0.0-rc.5`. Roadmap reviewed: 2026-09-23; documentation
+and obsolete checklist references cleaned up: 2026-10-28.
-The `1.0` target is a stable set of documented workflows, not complete parity
-with every historical CGI option. Work is grouped below by release gate and by
-the larger workflow features needed for routine analysis.
+The `1.0` target is a stable set of documented, regression-tested workflows.
+Work is grouped below by release gate and by the larger workflow features
+needed for routine analysis. Historical delivery details are in `CHANGELOG.md`.
## 1. Version 1.0 release path
@@ -62,8 +63,6 @@ history, manual run files, compound `ADDRUN`, and multiple fit ranges.
unexpectedly by the `musrfit -t` behavior.
(`runMSRFileLocal` omits `-t` when the MSR carries an explicit title;
`tests/electron-msr-title.test.js` covers the regression.)
-- [x] Audit `CGI_PARITY_CHECKLIST.md` against the current implementation and
- remove stale gap descriptions.
- [x] Implement the first scan-detection and built-in plot-template tasks from
section 2.
@@ -140,31 +139,19 @@ Deferred past `1.0` (explicitly documented as out of scope):
- opt-in web usage collection (config + outcomes as JSONL) to build a corpus
for training fitting models — design in
`docs/WEB_USAGE_COLLECTION.md`, not yet implemented.
-- Low priority: reorder the parameter catalogue so physical parameters (`Asy`,
- `Frq`, `Lam`, `Sgm`/`Sig`, ...) precede phase (`Phi`) and detector counts
- (`No`/`NBg`) in the dropdown and thus in generated FITPARAMETER blocks.
- Preferred approach: a global parameter-priority list applied inside
- `cfgConstraints()` when building `funSel`, leaving each `theoryBlk` signature
- text untouched. (Reordering the names inside `theoryBlk` would also work but
- changes emitted THEORY text; `No`/`NBg` already sort last because they are
- appended only in SingleHist mode.)
-The legacy CGI parity audit (formerly `CGI_PARITY_CHECKLIST.md`) is closed: the
-shared Electron/web codebase deliberately replaces the static CGI rather than
-mirroring it, and its intentional differences are documented under
-"Intentional Differences". Only the following optional legacy-CGI conveniences
-remain for evaluation after `1.0` (none block a supported workflow today):
-- header/log metadata extraction (`TITLE`/temperature/field/energy used as GUI
- defaults or result context, beyond the `_par.dat` scan metadata already used
- by the parameter plot);
-- legacy plotted-data ASCII/`gzip` spectrum dump alongside the ROOT/JSROOT
- plots;
-- the `LEM (PPC)`/`ROOT-PPC` legacy filename format;
-- the asymmetric positive-MINOS error field in the parameter table;
-- fixed Y PLOT limits as an editor-synchronized display option;
-- a full musrfit command/output viewer (floating console on the web, native
- child window in Electron);
-- a durable job manifest with retry/reopen for reproducibility.
+#### Optional workflow enhancements after 1.0
+
+These are product improvements to evaluate, not gaps against the old CGI.
+Header-based initial guesses, scan metadata, and the modeless Run log already
+exist; extend them only where a concrete analysis workflow needs more.
+
+- [ ] Export plotted spectra as ASCII, optionally compressed, alongside the
+ existing ROOT/JSROOT plots.
+- [ ] Evaluate support for archived LEM PPC/ROOT-PPC data if users need it.
+- [ ] Expose asymmetric positive MINOS errors in the parameter table.
+- [ ] Synchronize fixed Y plot limits between the editor and GUI.
+- [ ] Add a durable job manifest with retry/reopen for reproducibility.
### `1.0.0-rc.1`: hardening
@@ -472,8 +459,9 @@ plot, editor, synchronization, and result-collection behavior.
(delivered across `beta.3`/`beta.4`).
2. The `1.0.0-rc.1` hardening gates are complete (preload bridge, CGI
hardening, package and clean-web-deploy validation).
-3. Focus the remaining pre-`1.0` work on `beta.5` workflow completeness and then
- `1.0.0-rc.2` user validation.
+3. Validate the current release candidate with real analyses on Electron and
+ the web, including clean installation and upgrade checks on Linux and
+ Windows/WSLg. Resolve workflow regressions before the stable release.
4. The model-expression tree is deferred past 1.0 (see `beta.4`); the current
flat-component generation and the synchronization layer are the supported
`1.0` model and are protected by fixtures.
diff --git a/docs/DESKTOP_DEPLOYMENT.md b/docs/DESKTOP_DEPLOYMENT.md
index 1ca6ea0..30780e8 100644
--- a/docs/DESKTOP_DEPLOYMENT.md
+++ b/docs/DESKTOP_DEPLOYMENT.md
@@ -1,220 +1,106 @@
-# muSRFlow desktop deployment
+# Desktop Packaging and Releases
-The first public beta is version `0.9.0-beta.1`.
+This guide is for maintainers building installers and preparing releases.
+**Installing muSRFlow on a user's computer? Start here:**
-## Recommended Linux packages
+- [Windows installation, updates, and troubleshooting](source/install-windows.rst)
+- [Linux installation and runtime selection](source/install-linux.rst)
-For PSI/Linux desktops, build an **RPM** first. muSRFlow intentionally launches
-host-installed `musrfit`, `musrview`, `msr2data`, and `dump_header`, and it must
-read normal experiment-data mounts and user-selected work directories. An RPM
-therefore matches the application model better than a sandboxed Flatpak.
-
-An **AppImage** target is provided as a fallback for systems where RPM package
-requirements differ between distributions. Flatpak can be revisited later if
-we decide how host musrfit executables and data mounts should cross the sandbox.
+Application version comes from `package.json`; the current release candidate
+is `1.0.0-rc.5`. Target PCs do not need the developer tools described below.
## Build host
-A release build requires Node.js/npm and network access the first time
-`electron-builder` is downloaded. Application dependencies should be installed
-from the lock file first:
+Install Node.js/npm and the dependencies from the lock file:
```bash
npm ci
```
-Run the Electron-side tests and build an x86_64 RPM:
+Package builds run the Electron tests. The first build needs network access
+for Electron and electron-builder downloads. Runtime source builds need Docker
+or Podman; see the [runtime build guide](../packaging/runtime/README.md).
+
+## Linux packages
```bash
-npm run dist:rpm
+npm run dist:rpm # application RPM and runtime artifacts
+npm run dist:appimage # application AppImage and runtime artifacts
+npm run dist:linux # both application formats and runtime artifacts
```
-Build the portable AppImage instead:
+Each command packages the lean application and the matching separate runtime
+artifact(s), plus the runtime download bundle. Build the scientific runtime
+first with `packaging/runtime/build.sh` if `runtime/` is not ready.
-```bash
-npm run dist:appimage
-```
+| Artifact | Filename or directory |
+| --- | --- |
+| Application RPM | `dist/musrflow--x86_64.rpm` |
+| Application AppImage | `dist/muSRFlow--x86_64.AppImage` |
+| Runtime RPM | `dist/musrflow-runtime--x86_64.rpm` |
+| Runtime AppImage | `dist/musrflow-runtime--x86_64.AppImage` |
+| Offline runtime bundle | `dist/runtime-downloads/`, with `runtime-download.json`, archive, and checksum |
-Or build both:
-
-```bash
-npm run dist:linux
-```
-
-Artifacts are written to `dist/` and include the package version in their file
-name. Each of these commands also builds the matching standalone runtime
-artifact (`musrflow-runtime--x86_64.rpm` and/or
-`muSRFlow-runtime--x86_64.AppImage`) plus a checksummed download bundle
-under `dist/runtime-downloads/`. `npm run dist:runtime` builds only the runtime
-artifacts. `npm run dist:runtime:archive` builds just the plain download archive
-and its JSON descriptor without needing the RPM/AppImage packaging tools.
-
-## Target PC requirements
-
-The packaged Electron application includes Electron and its JavaScript
-runtime; target PCs do **not** need Node.js or npm.
-
-The musrfit toolchain is not bundled in the Linux app package. The target PC
-can either provide it system-wide:
-
-```text
-musrfit
-musrview
-msr2data
-dump_header
-```
-
-or install the standalone runtime that muSRFlow ships: the `musrflow-runtime`
-rpm, or the portable `muSRFlow-runtime` AppImage run with `--install`. Both
-place ROOT and musrfit in `/opt/musrflow/runtime`. muSRFlow looks in the
-configured **musrfit binaries** directory, a bundled runtime,
-`/opt/musrflow/runtime`, `/usr/local/bin`, and `/usr/bin`. The user
-must also have access to the experiment data tree configured under
-**File -> Preferences -> Data directory** and write access to the configured
-**Work directory**.
-
-After installing on a new PC, the minimum smoke test is:
-
-1. Start muSRFlow and check **Help -> About muSRFlow** for the expected version.
-2. Set Data and Work directories under **File -> Preferences**.
-3. Open one known run and confirm header-based frequency initialization.
-4. Run Plot, then Fit, and verify that `musrview`/`musrfit` start successfully.
-5. Open a parameter plot and refresh it after another fit.
-
-## Installing an RPM
-
-Use the native package manager where possible, for example:
-
-```bash
-sudo dnf install ./dist/muSRFlow-1.0.0-rc.1-x86_64.rpm
-```
-
-On RPM distributions with different package naming conventions, use the
-AppImage if the RPM dependency resolver rejects otherwise available Electron
-libraries.
-
-## Running the AppImage
-
-```bash
-chmod +x dist/muSRFlow-1.0.0-rc.1-x86_64.AppImage
-./dist/muSRFlow-1.0.0-rc.1-x86_64.AppImage
-```
-
-## Installing the standalone runtime
-
-On a machine without a system musrfit, install the ROOT + musrfit runtime that
-muSRFlow ships. Either install the rpm:
-
-```bash
-sudo dnf install ./dist/musrflow-runtime-1.0.0-rc.1-x86_64.rpm
-```
-
-or run the portable runtime AppImage, which copies the same tree into
-`/opt/musrflow/runtime`:
-
-```bash
-chmod +x dist/muSRFlow-runtime-1.0.0-rc.1-x86_64.AppImage
-./dist/muSRFlow-runtime-1.0.0-rc.1-x86_64.AppImage --install
-```
-
-Pass an optional directory to `--install` for a user-local prefix, and set
-`MUSRFLOW_RUNTIME_ROOT` to point muSRFlow at it. Without a runtime the app falls
-back to the host `musrfit` installation as before.
-
-The plain runtime download can also be checked with its SHA-256 sidecar and
-extracted into a fresh user-writable directory, without administrator access or
-FUSE. Set `MUSRFLOW_RUNTIME_ROOT` to the extracted `runtime/` directory. See the
-[runtime packaging guide](../packaging/runtime/README.md#download-archive) for
-the archive layout and descriptor format. On Linux, **File -> Preferences ->
-Install runtime...** installs a downloaded bundle after confirmation and selects
-its verified tools. **Check tools** tests the saved tool selection. In-app online
-downloads and missing-tool startup prompts will follow separately; no runtime
-is downloaded automatically.
-
-## Installing on Windows
-
-The Windows package is for **64-bit Intel/AMD PCs**. Windows 11 is recommended;
-Windows 10 needs build 19044 or newer for WSLg, which displays the `musrview`
-plot windows. See [Microsoft's WSL GUI requirements](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps).
-
-The installer includes ROOT and musrfit inside a private WSL2 distribution.
-You do not need Node.js, npm, Ubuntu, or a separate musrfit installation.
-
-1. **Install WSL.** Open PowerShell as Administrator and run:
-
- ```powershell
- wsl --install --no-distribution
- ```
-
- Restart Windows afterwards. If WSL is already installed, skip this step.
- `--no-distribution` leaves the Linux distribution installation to muSRFlow.
-
-2. **Update and check WSL.** In administrator PowerShell, run:
-
- ```powershell
- wsl --update
- wsl --version
- ```
-
- Follow any restart instructions. The version output should include WSL
- and WSLg. Microsoft's [WSL command reference](https://learn.microsoft.com/en-us/windows/wsl/basic-commands)
- describes these commands.
-
-3. **Install muSRFlow.** Copy `muSRFlow--x64.exe` from the release
- artifacts to the Windows PC and double-click it. For the current release
- candidate, the build output is `dist/muSRFlow-1.0.0-rc.5-x64.exe`.
- The runtime archive `muSRFlow-runtime-rootfs.tar.gz` is included in the
- installer; you do not need to extract or import it manually.
-
-4. **Launch muSRFlow** from the Start menu using your normal Windows account.
- The first launch imports the runtime as `muSRFlow-runtime`. Preparation
- can take several minutes; Fit and Plot wait for it to finish. After setup,
- check in PowerShell:
-
- ```powershell
- wsl --list --verbose
- ```
-
- The list should contain `muSRFlow-runtime` with **VERSION 2**. Either
- `Running` or `Stopped` is normal when idle. The imported runtime is stored
- under `%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime` for this Windows account.
-
-5. **Configure your folders.** Create writable folders, for example
- `C:\Users\\muSRFlow\work` and
- `C:\Users\\muSRFlow\data`. In **File -> Preferences**, select
- them as **Work directory** and **Data directory**. Leave **musrfit binaries**
- and **musrfit startup XML** on automatic detection, then save. Use normal
- Windows paths in Preferences; muSRFlow translates them for WSL.
-
-6. **Test Plot and Fit.** Select a known instrument, year, and run, then click
- **Plot**. If the data are missing locally, muSRFlow offers to download them
- from `musruser.psi.ch` when the server is reachable. Confirm that the
- spectrum window opens, then run **Fit** and check that the parameter table
- updates. Results are written to the selected Windows work directory.
-
-If runtime preparation fails, check that WSL is installed and updated, restart
-muSRFlow, and retry the action. If the runtime is ready but no spectrum window
-opens, check WSLg using `wsl --version` and inspect the application command log.
-The [WSL runtime guide](../packaging/wsl2/README.md) describes manual import for
-debugging. The Linux **Install runtime...** preference is not used on Windows.
-
-The setup flow is covered by automated tests with simulated WSL commands;
-installation and graphical plotting still need validation on a Windows PC.
+`npm run dist:runtime` builds only runtime artifacts.
+`npm run dist:runtime:archive` builds just the plain runtime download bundle
+without the RPM/AppImage packaging tools. The AppImage runtime builder needs
+the electron-builder AppImage cache; see the runtime guide for prerequisites.
## Building the Windows installer
-On the build host, install application dependencies with `npm ci`, prepare
-the Linux `runtime/` tree, then build its WSL root filesystem and the installer:
+Prepare the validated Linux `runtime/` tree, then run:
```bash
bash packaging/wsl2/build-wsl2.sh
npm run dist:win
```
-The rootfs builder requires Docker or Podman. `dist:win` packages the existing
-`packaging/wsl2/out/muSRFlow-runtime-rootfs.tar.gz`; it does not rebuild that
-archive. Output is `dist/muSRFlow--x64.exe`. See the
-[WSL packaging guide](../packaging/wsl2/README.md#packaging) for details.
+The rootfs builder uses Docker or Podman and includes the distribution libraries
+and Boost headers needed for plotting. It checks executable startup and ROOT
+plotting-header loading before exporting
+`packaging/wsl2/out/muSRFlow-runtime-rootfs.tar.gz`.
+
+`dist:win` packages the existing archive; it does not rebuild it. The result is
+`dist/muSRFlow--x64.exe`, including both the app and the WSL2 runtime.
+See [WSL packaging](../packaging/wsl2/README.md) for implementation details.
+
+**Existing Windows installations keep their imported runtime.** Link users to
+[the Windows update instructions](source/install-windows.rst#existing-installations)
+when distributing a runtime-related fix; reinstalling the app alone does not
+update that distribution.
+
+## Release validation
+
+1. Run `npm test` with the required scientific tools available. Record any
+ environment-dependent checks that could not be exercised.
+2. Install each package on its target OS. Check the version in **Help -> About**.
+3. Follow the platform installation guide, including runtime setup and separate
+ work/data directories.
+4. Exercise Plot, Fit, FFT, series/global fitting, parameter plotting, and MSR
+ editing with known data. Confirm parameter feedback and result files.
+5. Test upgrades of existing installations as well as a fresh installation.
+ Windows testing must include an interactive WSLg spectrum window.
+
+Linux-container tests have exercised the Windows runtime's tools, a real fit,
+and PNG generation. Those tests do not replace interactive Windows testing.
+
+## Installation links retained for older references
+
+### Installing on Windows
+
+The complete user guide is now [Windows installation](source/install-windows.rst).
+
+### Installing an RPM
+
+See [Linux application installation](source/install-linux.rst#install-the-application).
+
+### Running the AppImage
+
+See [Linux application installation](source/install-linux.rst#install-the-application).
+
+### Installing the standalone runtime
+
+See [Linux runtime setup](source/install-linux.rst#set-up-root-and-musrfit).
## Configuration link scheme
@@ -248,23 +134,18 @@ run controls, running the plot when `action=plot` is present.
Electron reports it through `app.getVersion()` and the About dialog.
`package-lock.json` should carry the same version.
-For the next release candidate or final release, keep `package.json`,
-`package-lock.json`, `tests/release-packaging.test.js`, and `CHANGELOG.md` in
-step. For example:
+For a version change, update `package.json`, `package-lock.json`,
+`tests/release-packaging.test.js`, and `CHANGELOG.md` together. Run the tests,
+rebuild the manuals and installers, and commit before tagging the release.
+Check the remaining release gates in [TODO.md](../TODO.md) before tagging 1.0.
-```bash
-npm version 1.0.0-rc.1 --no-git-tag-version
-npm test
-git commit -am "Prepare muSRFlow 1.0.0-rc.1"
-git tag v1.0.0-rc.1
-```
-
-For `1.0.0`, update the version only after the release candidate has been
-exercised on the actual target Linux installations.
+`npm run checksums` produces MD5/SHA-256 sidecars for top-level RPM and AppImage
+artifacts. It does not cover Windows installers. For a Windows release, generate
+and publish a SHA-256 checksum for the actual installer as well. Runtime download
+bundles include their own SHA-256 sidecar and descriptor.
## Application icon
-The repository currently does not contain a packaged application icon. The
-RPM/AppImage can be built and tested without one, but a final muSRFlow icon
-should be added before the 1.0 release and referenced from the electron-builder
-Linux configuration.
+Linux packages use `assets/musrflow-icon.png` through the electron-builder
+configuration in `package.json`. Windows packaging currently uses the default
+Electron icon; a Windows-specific icon remains a packaging improvement.
diff --git a/docs/_build/html/_sources/getting-started.rst.txt b/docs/_build/html/_sources/getting-started.rst.txt
index 2ed5526..7265b3c 100644
--- a/docs/_build/html/_sources/getting-started.rst.txt
+++ b/docs/_build/html/_sources/getting-started.rst.txt
@@ -1,138 +1,65 @@
Getting started
===============
-Prerequisites
--------------
+Choose your edition
+-------------------
-muSRFlow wraps external ``musrfit`` tools. How they are supplied depends on
-the edition:
+* **Windows desktop:** follow :doc:`install-windows`. ROOT and musrfit are
+ included in a WSL2 runtime. The guide covers first installation, existing
+ runtime updates, and Windows-specific errors.
+* **Linux desktop:** follow :doc:`install-linux`. Use an existing musrfit
+ installation or install the separate runtime through Preferences.
+* **Web:** open your site's muSRFlow URL, for example
+ ``http://musruser.psi.ch/muSRFlow/``. The server runs the tools; there is
+ nothing to install on your computer.
-* Linux desktop: use a local musrfit installation or install the separate
- ROOT + musrfit runtime. Select the tools through **File / Preferences**.
-* Windows desktop: the installer includes ROOT and musrfit in a WSL2 runtime.
- Install WSL first, following :ref:`windows-installation` below.
-* Web: the tools are installed on the server that hosts the CGI runner.
-
-Packaged desktop applications do not require Node.js or npm on the target
-PC. The browser edition needs no local installation at all.
+Packaged desktop applications do not require Node.js or npm.
.. _desktop-installation:
-Development and Linux packages
-------------------------------
+Desktop installation
+--------------------
-From a checkout, with `Node.js `_ and npm installed:
+The complete instructions are in :doc:`install-windows` and
+:doc:`install-linux`. Choose work and data folders in **File / Preferences**
+before your first analysis. Keep work files outside the application
+installation directory.
-.. code-block:: console
-
- $ npm install
- $ npm start
-
-`npm install` is only needed once; later sessions start with `npm start`.
-
-Release packages (Linux RPM and AppImage) are produced with:
-
-.. code-block:: console
-
- $ npm run dist:rpm
- $ npm run dist:appimage
-
-Each command also builds the matching standalone ROOT + musrfit runtime
-artifact (``musrflow-runtime`` rpm / AppImage); ``npm run dist:runtime`` builds
-only the runtime. The build and runtime requirements are described in
-``docs/DESKTOP_DEPLOYMENT.md``.
-
-.. _windows-installation:
+.. _getting-started-windows-installation:
Windows installation
--------------------
-Use a 64-bit Intel/AMD Windows PC. Windows 11 is recommended; Windows 10
-requires build 19044 or newer for WSLg, which displays the ``musrview``
-windows. See `Microsoft's WSL GUI requirements
-`_.
-
-1. Open **PowerShell as Administrator** and install WSL:
-
- .. code-block:: powershell
-
- wsl --install --no-distribution
-
- Restart Windows afterwards. Skip this step if WSL is already installed.
- You do not need Ubuntu: muSRFlow supplies its own distribution.
-
-2. Update WSL and check its components in administrator PowerShell:
-
- .. code-block:: powershell
-
- wsl --update
- wsl --version
-
- Follow any restart instructions. The output should include WSL and WSLg.
- See the `Microsoft WSL command reference
- `_.
-
-3. Copy the release installer ``muSRFlow--x64.exe`` to Windows and
- double-click it. It includes ``muSRFlow-runtime-rootfs.tar.gz``; there is
- no separate ROOT or musrfit installation or manual archive import.
-
-4. Launch muSRFlow from the Start menu using your normal Windows account.
- The first launch prepares the runtime, which can take several minutes.
- Fit and Plot wait until preparation finishes. Afterwards, verify:
-
- .. code-block:: powershell
-
- wsl --list --verbose
-
- The list should contain ``muSRFlow-runtime`` with **VERSION 2**.
- ``Running`` and ``Stopped`` are both normal when idle.
-
-5. Create writable work and data folders, for example
- ``C:\Users\\muSRFlow\work`` and
- ``C:\Users\\muSRFlow\data``. Choose them in
- **File / Preferences**. Leave **musrfit binaries** and
- **musrfit startup XML** on automatic detection, then save.
- Enter Windows paths; muSRFlow translates them for WSL.
-
-6. Select a known instrument, year, and run, then press **Plot**. If data
- are missing, muSRFlow offers to download them from ``musruser.psi.ch``
- when the server is reachable. Confirm the spectrum window opens, then
- try **Fit** and check that the parameter table updates. Results stay in
- your Windows work directory.
-
-If setup fails, check WSL, restart muSRFlow, and retry. If plotting fails
-after setup, check that ``wsl --version`` includes WSLg and inspect the
-command log. The Linux **Install runtime...** preference does not apply to
-Windows. Installation and graphical plotting still need validation on a
-Windows PC; automated setup tests use simulated WSL commands.
+The Windows instructions have their own chapter: :doc:`install-windows`.
+It also contains the update steps for older WSL runtimes.
Running the desktop app
-----------------------
-When the window opens, the **Runs** tab is active and the current year is
-already selected. Enter run numbers, choose a model, and press **Fit**. The
-first fit writes the working files next to your MSR document and results
-appear in the **Results** tab.
+When the window opens, the **Runs** tab is active. Choose the instrument,
+year, and run numbers, check the model, and press **Plot** to inspect the
+spectrum. Press **Fit** to fit it and refresh the parameter table. Generated
+files go to the selected work directory; the **Results** tab and run log
+show the outcome.
Opening the web edition
-----------------------
-Point your browser at the deployment URL (e.g.
-``http://musruser.psi.ch/muSRFlow/``). Instrument options and run numbers are
-the ones the server data tree supports. There is nothing to install; the
-parameter table is also served from the same data tree.
+Open the deployment URL in your browser. Instrument options and available
+run data depend on that site's server configuration. Fit and Plot run on
+the server; output files can be opened from the result links.
The Quick Start guide
---------------------
The ``?`` button at the right of the tab bar opens a short, tab-aware guide.
On the desktop it opens in an independent window; in the browser it opens a
-modeless dialog next to the main window. Each of its sections corresponds to
-one tab and is expanded into a chapter of this manual.
+modeless dialog next to the main window. The full workflow chapters follow
+the installation guides in this manual.
Support
-------
-For questions and bug reports contact Zaher Salman
-``_. Issue tracking is linked from the project
-repository.
\ No newline at end of file
+For questions and bug reports, include the version and run log and contact
+`Zaher Salman `_. See :doc:`troubleshooting`
+for common workflow problems.
diff --git a/docs/_build/html/_sources/index.rst.txt b/docs/_build/html/_sources/index.rst.txt
index 41463d2..3e79b4c 100644
--- a/docs/_build/html/_sources/index.rst.txt
+++ b/docs/_build/html/_sources/index.rst.txt
@@ -7,6 +7,9 @@ application and as a browser application, and both editions wrap the same set
of command-line tools (``musrfit``, ``musrview``, ``msr2data``, and
``dump_header``).
+Start with :doc:`install-windows` or :doc:`install-linux` for desktop setup.
+For the browser edition, see :doc:`getting-started`.
+
These pages describe the end-user workflow. They are organised around the
main window tabs, mirroring the Quick Start help that is built into the
application (the ``?`` button).
@@ -17,6 +20,8 @@ application (the ``?`` button).
overview
getting-started
+ install-windows
+ install-linux
runs-fitting
parameters-plots
constraints
@@ -33,6 +38,6 @@ application (the ``?`` button).
If anything in this manual does not match the behaviour you see, contact
`Zaher Salman `_.
-Separate repository documents cover desk build and packaging
+Separate repository documents cover desktop builds and packaging
(``docs/DESKTOP_DEPLOYMENT.md``) and the web-server/CGI deployment
(``cgi/README.md``); this manual concentrates on using the application.
\ No newline at end of file
diff --git a/docs/_build/html/_sources/install-linux.rst.txt b/docs/_build/html/_sources/install-linux.rst.txt
new file mode 100644
index 0000000..bbb6ffe
--- /dev/null
+++ b/docs/_build/html/_sources/install-linux.rst.txt
@@ -0,0 +1,135 @@
+.. _linux-installation:
+
+Linux installation
+==================
+
+Install the muSRFlow application, then select a working ROOT + musrfit
+installation. **The Linux application package does not include the scientific
+runtime.** You can use an existing installation or install the separate
+runtime through Preferences. Node.js and npm are not needed on the target PC.
+
+The current application packages are for x86_64 Linux. Examples below use
+``1.0.0-rc.5``; substitute the version of the package you obtained. Run the
+commands from the folder containing the downloaded files.
+
+Install the application
+-----------------------
+
+Choose one application format.
+
+RPM
+~~~
+
+On an RPM-based distribution with dnf:
+
+.. code-block:: bash
+
+ sudo dnf install ./musrflow-1.0.0-rc.5-x86_64.rpm
+ musrflow
+
+On other RPM systems, use the distribution's package manager. The application
+RPM filename starts with lowercase ``musrflow``.
+
+AppImage
+~~~~~~~~
+
+.. code-block:: bash
+
+ chmod +x muSRFlow-1.0.0-rc.5-x86_64.AppImage
+ ./muSRFlow-1.0.0-rc.5-x86_64.AppImage
+
+The application AppImage filename starts with ``muSRFlow``. It requires a
+compatible Linux desktop and AppImage/FUSE support. If it cannot start,
+check the terminal output or use the RPM on a supported RPM distribution.
+
+Set up ROOT and musrfit
+-----------------------
+
+Use an existing installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open **File / Preferences**. Leave **musrfit binaries** on automatic detection
+for a standard installation, or choose the directory containing ``musrfit``,
+``musrview``, ``msr2data``, ``musrt0``, and ``dump_header``. Save your settings,
+then use **Check tools** to verify the saved selection.
+
+Install the separate runtime from a local bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Obtain the runtime bundle for your architecture. Keep
+ ``runtime-download.json`` and its matching ``musrflow-runtime-*.tar.gz``
+ archive in the same folder. You do not need to unpack it.
+2. Open **File / Preferences / Install runtime...** and select
+ ``runtime-download.json``.
+3. Review the versions and destination, then select **Install and use**.
+ muSRFlow validates the archive, installs it in your personal application
+ data directory, and selects its tools.
+4. Use **Check tools** to confirm the selected runtime starts.
+
+This installation does not require administrator access. Runtime downloads
+are not automatic: obtain the bundle separately before opening the installer.
+A compatible Linux system and desktop/display services are still required.
+
+Alternative: system runtime RPM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ sudo dnf install ./musrflow-runtime-1.0.0-rc.5-x86_64.rpm
+
+This installs the runtime into ``/opt/musrflow/runtime``, which muSRFlow
+recognizes automatically when no explicit tool directory takes precedence.
+
+Alternative: runtime AppImage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a user-writable runtime location:
+
+.. code-block:: bash
+
+ chmod +x musrflow-runtime-1.0.0-rc.5-x86_64.AppImage
+ ./musrflow-runtime-1.0.0-rc.5-x86_64.AppImage --install "$HOME/.local/share/musrflow/runtime"
+
+Launch the application with the installed runtime selected:
+
+.. code-block:: bash
+
+ MUSRFLOW_RUNTIME_ROOT="$HOME/.local/share/musrflow/runtime" musrflow
+
+For the application AppImage, replace ``musrflow`` in that command with its
+path. Leave **musrfit binaries** on automatic detection so the selected
+runtime is used. Without a custom destination, the runtime AppImage installs
+to ``/opt/musrflow/runtime`` and needs permission to write there. Its filename
+is lowercase ``musrflow-runtime``, unlike the application AppImage.
+
+Choose folders and test
+-----------------------
+
+1. In **File / Preferences**, choose a writable **Work directory** outside
+ the application installation folder, for example ``~/muSRFlow/work``.
+ Use **Browse...** to select it.
+2. Set **Data directory** to the root of your instrument data tree, or to a
+ writable folder such as ``~/muSRFlow/data`` for downloaded runs.
+3. Leave **musrfit startup XML** on automatic detection unless you have a
+ specific installation configuration, then save.
+4. Select a known instrument, year, and run. Click **Plot**, then **Fit**.
+ Confirm the spectrum opens, fitted parameters update, and output files
+ appear in your work directory. Missing runs can be downloaded from
+ ``musruser.psi.ch`` after confirmation when the server is reachable.
+
+Updating and troubleshooting
+----------------------------
+
+* Upgrade the application RPM with your package manager, or replace the
+ application AppImage. The separate runtime is not updated by an app upgrade.
+* Preserve work files outside the application/runtime installation directories.
+* For missing tools or shared libraries, run **Check tools** and inspect the
+ reported executable paths. A configured binaries directory overrides
+ automatic detection; clear an obsolete selection or choose the correct one.
+* If fitting works but no spectrum window opens, inspect the run log and
+ confirm your desktop session can display native musrview windows.
+* If data are missing, check the instrument, year, run number, and data root.
+ Downloaded files use the selected writable data root or the personal
+ fallback folder reported in Preferences.
+
+Include the application version and run log when reporting a problem.
diff --git a/docs/_build/html/_sources/install-windows.rst.txt b/docs/_build/html/_sources/install-windows.rst.txt
new file mode 100644
index 0000000..5b19c3d
--- /dev/null
+++ b/docs/_build/html/_sources/install-windows.rst.txt
@@ -0,0 +1,193 @@
+.. _windows-installation:
+
+Windows installation
+====================
+
+The Windows installer includes muSRFlow, ROOT, and musrfit. Install WSL2
+first; muSRFlow prepares its own Linux runtime on first launch. You do not
+need Node.js, npm, Ubuntu, or a separate ROOT/musrfit installation.
+
+Already installed muSRFlow? Read `Existing installations`_ as well: updating
+the application does not update an already imported WSL runtime.
+
+Before you start
+----------------
+
+* Use a **64-bit Intel/AMD PC**. The current package is x64.
+* Windows 11 is recommended. Windows 10 requires build 19044 or newer for
+ WSLg, which displays the musrview spectrum windows.
+* Administrator access is needed to enable the Windows virtualization features.
+* Obtain the Windows installer, named ``muSRFlow--x64.exe``. The
+ current release candidate is ``1.0.0-rc.5``.
+
+**Use the refreshed Windows build.** Earlier rc.5 installers have the same
+filename but lack the WSL fixes. Obtain a build containing commit ``a6981c4``
+or later. In the development workspace, the verified replacement is
+``dist/windows-runtime-fix/muSRFlow-1.0.0-rc.5-x64.exe``; this is a local build
+output, not a public download address.
+
+See `Microsoft's WSL GUI requirements
+`_ for the
+Windows prerequisites.
+
+Install step by step
+--------------------
+
+1. **Install WSL.** Open **PowerShell as Administrator** and run:
+
+ .. code-block:: powershell
+
+ wsl --install --no-distribution
+
+ **Restart Windows afterwards.** Skip this step if WSL is already installed.
+ muSRFlow supplies its own distribution, so Ubuntu is not required.
+
+2. **Update and check WSL.** In administrator PowerShell, run:
+
+ .. code-block:: powershell
+
+ wsl --update
+ wsl --version
+
+ Follow any restart instructions. The output should include WSL and WSLg.
+ These commands are described in the `Microsoft WSL command reference
+ `_.
+
+3. **Install muSRFlow.** Double-click the Windows installer and complete setup.
+ The runtime archive ``muSRFlow-runtime-rootfs.tar.gz`` is included; do not
+ extract or import it manually for a normal installation.
+
+4. **Launch muSRFlow** from the Start menu using your normal Windows account.
+ First launch imports the runtime as ``muSRFlow-runtime`` and can take
+ several minutes. Fit and Plot wait until preparation finishes. Afterwards,
+ verify in PowerShell:
+
+ .. code-block:: powershell
+
+ wsl --list --verbose
+
+ The list should contain ``muSRFlow-runtime`` with **VERSION 2**.
+ ``Running`` and ``Stopped`` are both normal when idle. The runtime is
+ stored under ``%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime`` for this account.
+
+5. **Choose work and data folders before fitting.** Create folders such as:
+
+ .. code-block:: text
+
+ C:\Users\\muSRFlow\work
+ C:\Users\\muSRFlow\data
+
+ In **File / Preferences**, select them as **Work directory** and
+ **Data directory**. Leave **musrfit binaries** and **musrfit startup XML**
+ on automatic detection, then save. Enter normal Windows paths; muSRFlow
+ translates them for WSL.
+
+ Use a work folder outside the application installation directory. The
+ default ``.`` can resolve to the installation folder and place your
+ results among files managed by the installer.
+
+6. **Try Plot, then Fit.** Select a known instrument, year, and run. Click
+ **Plot** and confirm that the spectrum window opens. Missing run data
+ can be downloaded from ``musruser.psi.ch`` after confirmation when the
+ server is reachable. Then click **Fit**, check that the parameter table
+ updates, and inspect the generated files in your work directory.
+
+Existing installations
+----------------------
+
+1. Preserve any MSR/data/result files currently stored inside the muSRFlow
+ installation folder: move them to a separate work folder before upgrading.
+2. Close muSRFlow and install the refreshed Windows application.
+3. If your runtime was imported from an older bundle, add the missing Boost
+ headers from PowerShell:
+
+ .. code-block:: powershell
+
+ wsl -d muSRFlow-runtime -- dnf -y install boost-devel
+
+ This needs access to the distribution's package repositories. ROOT uses
+ these headers when loading musrview plotting classes. Fresh runtimes
+ from the corrected installer already include them.
+4. Reopen muSRFlow, select your work directory in Preferences, and retry Plot
+ and Fit.
+
+Reinstalling the application preserves an existing ``muSRFlow-runtime``
+distribution, so the application update alone does not add those headers.
+The command above repairs it in place; do not unregister the distribution
+as part of this update. The Linux **Install runtime...** preference is not
+used on Windows.
+
+Troubleshooting
+---------------
+
+Required feature is not installed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For ``HCS_E_SERVICE_NOT_AVAILABLE`` during runtime preparation, Windows
+could not create the WSL virtual machine. In **administrator PowerShell**:
+
+.. code-block:: powershell
+
+ dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+
+Restart Windows. Check **Task Manager / Performance / CPU** for
+**Virtualization: Enabled**; if disabled, enable hardware virtualization in
+BIOS/UEFI. If Windows itself is a virtual machine, its host must expose nested
+virtualization. If the error persists, check the boot setting:
+
+.. code-block:: powershell
+
+ bcdedit /enum | findstr -i hypervisorlaunchtype
+
+Only if it reports ``Off``, enable it and restart:
+
+.. code-block:: powershell
+
+ bcdedit /set hypervisorlaunchtype Auto
+
+See `Microsoft's WSL troubleshooting guide
+`_.
+
+Cannot find wsl.exe
+~~~~~~~~~~~~~~~~~~~
+
+For ``spawn wsl.exe ENOENT``, first check that ``wsl --version`` works in
+PowerShell. If it does, install the refreshed muSRFlow build: early rc.5
+builds incorrectly replaced the Windows executable search path. Also check
+that the selected work directory exists and is writable.
+
+Cannot load libCore.so
+~~~~~~~~~~~~~~~~~~~~~~
+
+Install the refreshed muSRFlow build. It passes the ROOT library directory
+inside WSL for every bundled command. Setting a Windows ``ROOTSYS`` or
+``LD_LIBRARY_PATH`` is not a substitute for this launcher fix.
+
+Missing boost/version.hpp or plotting crash
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow `Existing installations`_ to install ``boost-devel`` in an older
+runtime. The corrected runtime includes it. If plotting still crashes,
+include the full command output when reporting the problem.
+
+No spectrum window appears
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Confirm that ``wsl --version`` lists WSLg, update WSL, and inspect the
+muSRFlow run log. Successful runtime import or a successful fit alone does
+not verify interactive graphics support.
+
+Reporting a problem
+~~~~~~~~~~~~~~~~~~~
+
+Include the muSRFlow version, full run log, and the output of:
+
+.. code-block:: powershell
+
+ wsl --version
+ wsl --status
+ wsl --list --verbose
+
+The corrected runtime has completed a real fit and generated a PNG in a
+Linux container. Interactive Windows/WSLg plotting still needs validation
+on the target PC.
diff --git a/docs/_build/html/_sources/platforms.rst.txt b/docs/_build/html/_sources/platforms.rst.txt
index 13f80df..ad051d3 100644
--- a/docs/_build/html/_sources/platforms.rst.txt
+++ b/docs/_build/html/_sources/platforms.rst.txt
@@ -38,28 +38,17 @@ the command-line tools live.
Bundled ROOT and musrfit
------------------------
-Packaged desktop builds can use a self-contained ROOT + musrfit runtime, so a
-separate musrfit installation is not required on the machine. The runtime may
-be bundled inside the application or, on Linux, installed separately (the
-``musrflow-runtime`` rpm or the portable ``muSRFlow-runtime`` AppImage, both
-defaulting to ``/opt/musrflow/runtime``). When a runtime is found muSRFlow runs
-those tools with ``ROOTSYS``, ``MUSRFITPATH``, and ``LD_LIBRARY_PATH`` pointed
-at it; a directory set in **Preferences / musrfit binaries** still takes
-precedence, and on builds without a runtime the system installation is used
-exactly as before. The runtime is built with ``packaging/runtime/build.sh`` and
-packaged with ``packaging/runtime/build-runtime-rpm.sh`` /
-``build-runtime-appimage.sh`` (see ``packaging/runtime/README.md``).
+On Linux, the application and scientific runtime are separate. Use an
+existing ROOT + musrfit installation, install an offline runtime bundle in
+Preferences, or install the system runtime RPM/AppImage. An explicitly
+selected binaries directory takes precedence over automatic detection.
+See :doc:`install-linux` for installation and tool checks.
-On Windows the bundled runtime runs inside a WSL2 distribution that muSRFlow
-ships: the tools are invoked through ``wsl.exe`` and file paths are translated
-between the Windows and WSL forms, so inputs and outputs stay on the Windows
-side. The rootfs is built with ``packaging/wsl2/build-wsl2.sh`` and imported
-once per user (see ``packaging/wsl2/README.md``).
-
-Follow :ref:`windows-installation` for the WSL setup, Windows installer,
-folder preferences, and first Plot/Fit check. The Windows installer includes
-``muSRFlow-runtime-rootfs.tar.gz`` and imports it automatically; the separate
-Linux runtime archive and **Install runtime...** preference do not apply.
+On Windows, the application installer includes the runtime. It runs inside
+a WSL2 distribution named ``muSRFlow-runtime``. Tools are invoked through
+``wsl.exe``, with paths translated so inputs and outputs stay on the Windows
+side. The separate Linux runtime installer does not apply to Windows.
+See :doc:`install-windows` for WSL setup, installation, updates, and fixes.
The workflow chapters of this manual apply to both editions. Where a step is
specific to one edition (handling files, Preferences), the text says so
diff --git a/docs/_build/html/_sources/preferences.rst.txt b/docs/_build/html/_sources/preferences.rst.txt
index e74055a..ef7fdfd 100644
--- a/docs/_build/html/_sources/preferences.rst.txt
+++ b/docs/_build/html/_sources/preferences.rst.txt
@@ -7,7 +7,9 @@ configuration and never exposes this dialog.
Work directory
Where generated files, MSR documents, and result artifacts are written.
- Defaults to the current directory (``.``).
+ Defaults to the current directory (``.``), which can be the application
+ installation folder. Choose a separate writable work folder before fitting
+ so application upgrades do not affect your results.
Data directory
The root of the instrument data tree (for example
@@ -44,6 +46,12 @@ musrfit binaries
sessions, while the web edition takes its tools from the server and never
exposes this field.
+Runtime installation and checks (Linux)
+ **Check tools** checks the saved tool selection. **Install runtime...**
+ installs a local runtime bundle after confirmation and selects its tools.
+ See :doc:`install-linux` for the required files and installation steps.
+ Windows uses its bundled WSL runtime instead; see :doc:`install-windows`.
+
musrfit threads
The number of OpenMP threads passed to a local ``musrfit`` run (``-u``).
Leave it blank to let musrfit use every available core. Set a lower
diff --git a/docs/_build/html/_sources/troubleshooting.rst.txt b/docs/_build/html/_sources/troubleshooting.rst.txt
index 003d840..b58fc0e 100644
--- a/docs/_build/html/_sources/troubleshooting.rst.txt
+++ b/docs/_build/html/_sources/troubleshooting.rst.txt
@@ -1,6 +1,10 @@
Troubleshooting
===============
+For Windows setup, WSL startup errors, missing ROOT libraries, and older
+runtime updates, see :doc:`install-windows`. For Linux package/runtime setup,
+see :doc:`install-linux`. The sections below cover analysis workflows.
+
Fit or plot will not start
--------------------------
diff --git a/docs/_build/html/configuration-sharing.html b/docs/_build/html/configuration-sharing.html
index 1361ed0..b2338cb 100644
--- a/docs/_build/html/configuration-sharing.html
+++ b/docs/_build/html/configuration-sharing.html
@@ -46,6 +46,8 @@
Linux desktop: use a local musrfit installation or install the separate
-ROOT + musrfit runtime. Select the tools through File / Preferences.
-
Windows desktop: the installer includes ROOT and musrfit in a WSL2 runtime.
-Install WSL first, following Windows installation below.
-
Web: the tools are installed on the server that hosts the CGI runner.
+
Windows desktop: follow Windows installation. ROOT and musrfit are
+included in a WSL2 runtime. The guide covers first installation, existing
+runtime updates, and Windows-specific errors.
+
Linux desktop: follow Linux installation. Use an existing musrfit
+installation or install the separate runtime through Preferences.
+
Web: open your site’s muSRFlow URL, for example
+http://musruser.psi.ch/muSRFlow/. The server runs the tools; there is
+nothing to install on your computer.
-
Packaged desktop applications do not require Node.js or npm on the target
-PC. The browser edition needs no local installation at all.
+
Packaged desktop applications do not require Node.js or npm.
npm install is only needed once; later sessions start with npm start.
-
Release packages (Linux RPM and AppImage) are produced with:
-
$ npmrundist:rpm
-$ npmrundist:appimage
-
-
-
Each command also builds the matching standalone ROOT + musrfit runtime
-artifact (musrflow-runtime rpm / AppImage); npmrundist:runtime builds
-only the runtime. The build and runtime requirements are described in
-docs/DESKTOP_DEPLOYMENT.md.
The complete instructions are in Windows installation and
+Linux installation. Choose work and data folders in File / Preferences
+before your first analysis. Keep work files outside the application
+installation directory.
Use a 64-bit Intel/AMD Windows PC. Windows 11 is recommended; Windows 10
-requires build 19044 or newer for WSLg, which displays the musrview
-windows. See Microsoft’s WSL GUI requirements.
-
-
Open PowerShell as Administrator and install WSL:
-
wsl--install--no-distribution
-
-
-
Restart Windows afterwards. Skip this step if WSL is already installed.
-You do not need Ubuntu: muSRFlow supplies its own distribution.
-
-
Update WSL and check its components in administrator PowerShell:
Copy the release installer muSRFlow-<version>-x64.exe to Windows and
-double-click it. It includes muSRFlow-runtime-rootfs.tar.gz; there is
-no separate ROOT or musrfit installation or manual archive import.
-
Launch muSRFlow from the Start menu using your normal Windows account.
-The first launch prepares the runtime, which can take several minutes.
-Fit and Plot wait until preparation finishes. Afterwards, verify:
-
wsl--list--verbose
-
-
-
The list should contain muSRFlow-runtime with VERSION 2.
-Running and Stopped are both normal when idle.
-
-
Create writable work and data folders, for example
-C:\Users\<your-name>\muSRFlow\work and
-C:\Users\<your-name>\muSRFlow\data. Choose them in
-File / Preferences. Leave musrfit binaries and
-musrfit startup XML on automatic detection, then save.
-Enter Windows paths; muSRFlow translates them for WSL.
-
Select a known instrument, year, and run, then press Plot. If data
-are missing, muSRFlow offers to download them from musruser.psi.ch
-when the server is reachable. Confirm the spectrum window opens, then
-try Fit and check that the parameter table updates. Results stay in
-your Windows work directory.
-
-
If setup fails, check WSL, restart muSRFlow, and retry. If plotting fails
-after setup, check that wsl--version includes WSLg and inspect the
-command log. The Linux Install runtime… preference does not apply to
-Windows. Installation and graphical plotting still need validation on a
-Windows PC; automated setup tests use simulated WSL commands.
When the window opens, the Runs tab is active and the current year is
-already selected. Enter run numbers, choose a model, and press Fit. The
-first fit writes the working files next to your MSR document and results
-appear in the Results tab.
+
When the window opens, the Runs tab is active. Choose the instrument,
+year, and run numbers, check the model, and press Plot to inspect the
+spectrum. Press Fit to fit it and refresh the parameter table. Generated
+files go to the selected work directory; the Results tab and run log
+show the outcome.
Point your browser at the deployment URL (e.g.
-http://musruser.psi.ch/muSRFlow/). Instrument options and run numbers are
-the ones the server data tree supports. There is nothing to install; the
-parameter table is also served from the same data tree.
+
Open the deployment URL in your browser. Instrument options and available
+run data depend on that site’s server configuration. Fit and Plot run on
+the server; output files can be opened from the result links.
The ? button at the right of the tab bar opens a short, tab-aware guide.
On the desktop it opens in an independent window; in the browser it opens a
-modeless dialog next to the main window. Each of its sections corresponds to
-one tab and is expanded into a chapter of this manual.
+modeless dialog next to the main window. The full workflow chapters follow
+the installation guides in this manual.