Files
salman 12ecbf4f7d Automate Windows publication and coordinated cross-platform releases
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.
2026-10-30 09:22:59 +01:00

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). Adjust BASE_IMAGE if the runtime is rebuilt against a different baseline.
  • wsl --import of 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.