Files
Zaher Salman 53e71f0940
Build and package / build-package (push) Successful in 5m23s
Build Windows installer / build-windows (push) Successful in 6m57s
Fix Windows installer build provenance generation
The Windows build stages git archive output into the Wine container, so the
staged tree has no .git directory. write-build-info.js previously called
git rev-parse there and aborted the installer build. Pass the source revision
and clean-tree state from the host checkout instead, and cover the wiring in
the WSL packaging test.

Release 1.0.2.
2026-11-09 22:41:18 +01:00

160 lines
6.9 KiB
Markdown

# muSRFlow
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 version: **1.0.2**.
## 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
- [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
npm ci
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)
The manual uses Sphinx. Rebuild its HTML and PDF with:
```bash
cd docs
make html
make latexpdf
```
## Web Deployment
The browser application consists of `index.html`, `quick-start.html`, `ZGUI.css`,
`muSRFitweb.js`, `muSRFitRoot.js`, `muSRFitParameterPlot.js`, and `muSRFitlib.js`. The web plot window uses
JSROOT to draw the ROOT files produced by `musrview --root`. Its server-side
runner is documented in
[`cgi/README.md`](cgi/README.md).
Build the HTML manual, then install the browser files, manual, and CGI endpoint.
The build needs Sphinx and `sphinx_rtd_theme`; deployment only copies the generated
files, so Sphinx is not needed on the web server. The script targets the default
Apache paths and hands the files to the web server's owner:
```bash
make -C docs html
sudo ./scripts/deploy-web.sh
```
To deploy to a remote server (e.g. musruser.psi.ch) from this machine,
`deploy-remote-web.sh` copies a tarball, extracts it on the remote host, and
runs `deploy-web.sh` via sudo (remote user must have sudo rights):
```bash
make -C docs html
./scripts/deploy-remote-web.sh [path/to/muSRFlow.tar.gz]
# or let it create a temporary archive from the current tree:
./scripts/deploy-remote-web.sh
```
Set `MUSRFLOW_REMOTE_HOST` / `MUSRFLOW_REMOTE_USER` / `MUSRFLOW_REMOTE_SSH` as
needed. `MUSRFLOW_WEB_TARGET`, `MUSRFLOW_CGI_TARGET`,
`MUSRFLOW_STARTUP_XML_TARGET`, and `MUSRFLOW_DATA_ROOT` are passed through.
The complete manual is installed under `/muSRFlow/docs/`, including its styles
and search index. Rebuild it before each deployment to include documentation and
version changes. If `docs/_build/html/index.html` is missing or empty, deployment
stops before changing installed files. When deploying from a separate source
checkout on the server, transfer `docs/_build/html/` into that checkout first.
The web-only owner (`apache`/`www-data`/`httpd`) is auto-detected when the
deployed tree is not already owned by the invoking user, so the script also
runs unprivileged against a developer-owned web tree (skip that case's `sudo`).
Override the targets and owner as needed with `MUSRFLOW_WEB_TARGET`,
`MUSRFLOW_CGI_TARGET`, `MUSRFLOW_STARTUP_XML_TARGET`, `MUSRFLOW_WEB_OWNER`, and
`MUSRFLOW_WEB_GROUP`. Official Git source archives carry their commit through
`build-revision.txt`, so Quick Start can identify an archive deployment without
a `.git` directory. For a tar file produced by another tool, set
`MUSRFLOW_BUILD_REVISION` to its full Git commit when running the deployment
script; otherwise the UI identifies it as a versioned source archive.
The installed `musrfit_startup.xml` is rewritten when the machine's data tree
lives under a non-PSI root: set `MUSRFLOW_DATA_ROOT` (e.g. `/mnt/fake`) and the
`<data_path>` roots in the installed copy are rewritten to it so the portable
RUN-name resolver matches the local data layout. The repository source file is
never modified.
The server-side data root is configured separately: the CGI reads
`MUSRFIT_DATA_ROOT` (default `/psi.ch/group/lmu/public/data`) and reports it to
the browser through its health endpoint. When `MUSRFLOW_DATA_ROOT` is used,
set `MUSRFIT_DATA_ROOT` to the same value so the path the browser shows and the
security boundary agree with the rewritten startup-XML roots. See
[`cgi/README.md`](cgi/README.md) for the full list of CGI environment variables.
## Code Organization
The project splits platform code from shared logic so that a change is made
once instead of duplicated across the desktop and web runtimes:
- `muSRFitlib.js` — shared, platform-agnostic logic (MSR generation/parsing,
series-fit planning and merge, fit-statistic parsing, shared-configuration
protocol, command/parameter formatting). This is the canonical home for any
logic that both runtimes need.
- `muSRFitelec.js` — Electron-specific code (filesystem and IPC access, local
process execution, local transaction adapter).
- `muSRFitweb.js` — web-specific code (CGI transport, browser clipboard,
drag-and-drop windows).
As a rule, the adapters supply only platform-specific primitives (filesystem,
process, clipboard, HTTP) while `muSRFitlib.js` owns the logic. Pure
transformations such as `displayCommand`, `seriesRunDirectiveIdentity`, and
`normalizeParameterDataHeaderLines` live in `muSRFitlib.js`. The CGI endpoint
writes files and runs external executables on the server; generated artifacts
are served back over HTTP.
## Contact
Zaher Salman <zaher.salman@psi.ch>
## License
Copyright (C) 2026 Zaher Salman. muSRFlow is distributed under the
GNU General Public License, version 3 or later (`GPL-3.0-or-later`). See
[`LICENSE`](LICENSE) for the full license text.
## Downloads
Prebuilt packages are available from the [Gitea releases page](https://gitea.psi.ch/salman/muSRFlow/releases).