Build and publish Windows installers on version tags using the tested WSL packaging path. Keep Windows metadata in its own package and support publication recovery from saved Linux or Windows artifacts. Create one draft Release only after matching Linux and Windows provenance is published. Preserve reviewed release notes and handle concurrent creation safely. Cover publishing, recovery, and coordination with regression tests and update deployment and installation guides.
7.4 KiB
Windows (WSL2) runtime
The Windows package runs the same Linux ROOT + musrfit runtime tree used by the Linux runtime packages inside a bundled WSL2 distribution.
For installation on a Windows PC, follow the
step-by-step Windows installation guide.
It covers WSL/WSLg, the .exe installer, automatic runtime preparation, folder
preferences, and a first Plot/Fit check. The remaining sections describe
building and debugging the runtime.
How it works
muSRFitelec.js detects the Windows host and the bundled runtime
(process.platform === "win32" and <resources>/runtime/bin/musrfit present)
and routes every bundled tool through wsl.exe:
wsl.exe -d muSRFlow-runtime -- env ROOTSYS=/opt/musrfit-runtime MUSRFITPATH=/opt/musrfit-runtime LD_LIBRARY_PATH=/opt/musrfit-runtime/lib PATH=/opt/musrfit-runtime/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin /opt/musrfit-runtime/bin/musrfit <args...>
ROOT and library paths are supplied explicitly inside WSL: setting them in the
Windows host environment does not configure the Linux loader. The launcher also
passes the selected data search roots as MUSRFULLDATAPATH. This applies to
both direct tool launches and shell-based msr2data calls.
Path arguments (C:\dir\file) are translated to their WSL mount form
(/mnt/c/dir/file) so the tools read and write the user's Windows files. Input
and output files therefore stay on the Windows side; musrfit writes into the
working directory, which WSL maps back through /mnt/<drive>.
A user-configured musrfit binaries directory with Windows-native executables is launched directly, and on non-Windows hosts the translation is inert, so the Linux AppImage and development checkouts are unaffected.
Constants (in muSRFitelec.js): the distribution name muSRFlow-runtime and
the in-distro prefix /opt/musrfit-runtime.
Building the rootfs
Requires Docker or Podman and a built Linux runtime. Run from the muSRFlow
repository root. This step copies existing binaries from runtime/; it
does not compile musrfit. After changing the sources, first rebuild the
runtime, then regenerate this archive. See the
complete compilation and Windows packaging sequence
for the source checkout and MUSRFIT_REPO override.
packaging/wsl2/build-wsl2.sh
This installs the distro-level libraries the runtime needs (GSL, FFTW, libxml2,
Boost including its headers, OpenSSL, X11/GL, FreeType, Fontconfig, ...), copies runtime/ to
/opt/musrfit-runtime, writes /etc/wsl.conf, and exports the container
filesystem to packaging/wsl2/out/muSRFlow-runtime-rootfs.tar.gz.
Importing on Windows
The import is automated. On first run main.js (through wsl-runtime.js)
checks whether the muSRFlow-runtime distribution is registered and, if not,
imports the bundled archive into %LOCALAPPDATA%\muSRFlow\muSRFlow-runtime
with wsl --import ... --version 2. The work happens in the background so the
window opens immediately; progress and failures are broadcast to the renderer on
the wslRuntimeStatus channel and exposed through the preload
electronAPI.wslRuntime bridge (status(), ensure(), onStatus()).
A failed import resets so a later ensure() retries. Before running a Fit or
Plot the renderer awaits MusrfitRuntimeGate, so the first action after
startup shows a "Preparing the bundled musrfit runtime" notice and proceeds once
the distribution is ready; the gate is a no-op off Windows.
The equivalent manual command, useful for debugging:
wsl --import muSRFlow-runtime "$env:LOCALAPPDATA\muSRFlow\muSRFlow-runtime" muSRFlow-runtime-rootfs.tar.gz --version 2
Verify:
wsl -d muSRFlow-runtime -- env ROOTSYS=/opt/musrfit-runtime MUSRFITPATH=/opt/musrfit-runtime LD_LIBRARY_PATH=/opt/musrfit-runtime/lib /opt/musrfit-runtime/bin/musrt0 --version
WSLg supplies the X server that musrview needs for the spectra window.
It requires Windows 11 or Windows 10 build 19044 or newer; see
Microsoft's requirements.
Updating an existing imported runtime
Application upgrades preserve the registered distribution. Follow Existing installations for the in-place Boost-header repair needed by older bundles. Keep user-facing update and troubleshooting instructions in that guide.
The rootfs build checks that ROOT can parse PMusrCanvas.h, because
--version alone does not exercise the plotting dependencies.
Packaging
Gitea runner
Use Actions -> Build Windows installer -> Run workflow for Linux-hosted WSL/NSIS packaging. It restores the approved runtime from Gitea Packages (or an explicit runtime run during migration), builds a checked WSL rootfs with Podman, and builds an unsigned Windows installer in a digest-resolved Wine image. Download musrflow-windows-x64 and windows-build-logs from the run.
The workflow also runs on version-tag pushes and publishes musrflow-windows
in Gitea Packages. Tagged builds contribute to one draft Release after both Linux
and Windows packages are ready. Manual builds publish a build-specific version
without creating a Release. Use Publish packages with platform windows
and the original packaging run ID to retry publication without rebuilding.
See the runner instructions and checks.
Local builds
The Windows build ships the rootfs through electron-builder. win.extraResources
copies the archive into resources/wsl-runtime and the runtime's bin/
markers (plus musrfit_startup.xml) into resources/runtime so the renderer
detects the bundled runtime and routes every tool through WSL. Build with:
npm run dist:win
The installer is written to dist/muSRFlow-<version>-x64.exe, using the version
in package.json. Windows and Linux installers are built by separate workflows
on the same version tag. For a local build, build the rootfs first: dist:win packages the
existing archive and does not regenerate it. The Windows installer still
includes the runtime; the separate offline runtime installer in Preferences
currently supports Linux only.
For CI or an explicitly restored runtime, build-wsl2.sh accepts RUNTIME_DIR
and OUTPUT. Set ALLOW_RUNTIME_BUILD=0 to reject a missing runtime rather
than start a local compilation. The default local invocation still builds the
default runtime/ when needed. Container names are unique and failed exports
leave any previous rootfs intact.
Open items
- The rootfs is built from
manylinux_2_28(AlmaLinux 8). AdjustBASE_IMAGEif the runtime is rebuilt against a different baseline. wsl --importof the runtime archive can take a few minutes; status is reported but the import cannot yet be cancelled.- WSL must be installed before launching muSRFlow. On a PC without WSL, use
administrator PowerShell to run
wsl --install --no-distribution, then restart Windows. muSRFlow imports its own distribution afterwards. - Setup tests simulate WSL commands. The corrected runtime has also completed a real fit and PNG plot in its Linux container environment; installation and interactive WSLg plotting still need validation on a Windows PC.
- Only Linux and Windows bundles exist; the macOS runtime is not built yet.