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.
160 lines
6.9 KiB
Markdown
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).
|