Files
muSRFlow/packaging/runtime

Bundled ROOT + musrfit runtime

muSRFlow can use a self-contained, relocatable ROOT + musrfit runtime so users do not need a system-wide musrfit installation. The tree is built once in a low-glibc container. On Linux it is distributed separately as an offline bundle, RPM, or runtime AppImage. On Windows the full tree runs inside the bundled WSL2 distribution; only tool markers and startup XML are placed in <app resources>/runtime.

Installing rather than building? Follow the Linux installation guide or Windows installation guide. The following sections describe runtime production and implementation.

Layout

The runtime is a single install prefix that doubles as ROOTSYS:

runtime/
  bin/                      # root-config, musrfit, musrt0, musrview, msr2data, dump_header, ...
  lib/                      # libCore.so…, libPMusr.so…, bundled third-party .so
  include/
  etc/                      # ROOT/system config
  share/
  musrfit_startup.xml       # default startup file found via MUSRFITPATH
  runtime-manifest.json     # actual versions, native architecture, build provenance

ROOT is configured with -Dgnuinstall=OFF so its libraries land in lib/ alongside libPMusr, letting a single LD_LIBRARY_PATH entry cover both. Qt-based tools are disabled (-Dqt_based_tools=OFF) because muSRFlow only needs the command-line tools.

Environment contract

For a selected native Linux runtime, muSRFitelec.js::buildToolEnvironment supplies:

Variable Value
ROOTSYS <runtime>
MUSRFITPATH <runtime> (musrfit finds <runtime>/musrfit_startup.xml)
LD_LIBRARY_PATH <runtime>/lib prepended to the host value
PATH <runtime>/bin prepended (after a user-configured tools dir)

Windows bundled tools receive the corresponding Linux environment inside WSL through prepareLocalLaunch, not through the Windows host environment. See the WSL runtime guide.

Resolution order for a tool (resolveLocalCommand):

  1. user-configured tools directory (Preferences → musrfit binaries)
  2. <resources>/runtime/bin (runtime bundled inside the app)
  3. /opt/musrflow/runtime/bin (separately installed runtime; override with MUSRFLOW_RUNTIME_ROOT)
  4. /usr/local/bin, /usr/bin
  5. <resources>/bin, <resources>
  6. current working directory

If neither runtime has a bin/musrfit (or bin/musrt0), the runtime is considered unavailable and the host installation is used unchanged. This keeps development checkouts and web builds working with no configuration.

Building the tree

Requires Docker or Podman. Run from the muSRFlow repository root.

Source location: the builder reads the local sibling checkout ../musrfit.psi by default, not an automatically downloaded musrfit release. It compiles the current working-tree contents, including local changes, and never clones, fetches, or pulls that checkout. Select/update the intended source revision before building.

bash packaging/runtime/build.sh

Override the checkout with an absolute path when needed:

MUSRFIT_REPO=/path/to/musrfit bash packaging/runtime/build.sh

The host checkout is mounted read-only as /src/musrfit in the container. The source revision and dirty status are recorded in the runtime manifest.

The host wrapper builds the image from Dockerfile and runs build-runtime.sh, which downloads and builds ROOT, builds musrfit against it, bundles the non-system shared-library closure, and writes the result to <repo>/runtime.

Building the distributable runtime

These commands package the existing runtime/ tree; they do not compile musrfit. Re-run the source build above when the scientific tools change. For Windows, also regenerate the WSL archive before creating the installer; see the complete Windows build sequence.

On Linux the runtime ships separately from the app, so the app packages stay lean and can share one runtime (or use a system musrfit):

packaging/runtime/build-runtime-rpm.sh       # dist/musrflow-runtime-<version>-x86_64.rpm
packaging/runtime/build-runtime-appimage.sh  # dist/musrflow-runtime-<version>-x86_64.AppImage

Both install the tree into /opt/musrflow/runtime, which the app discovers automatically (MUSRFLOW_RUNTIME_ROOT overrides the location). The rpm is built with fpm, and the AppImage launcher supports:

./musrflow-runtime-<version>-x86_64.AppImage --install [DIR]
./musrflow-runtime-<version>-x86_64.AppImage --prefix
./musrflow-runtime-<version>-x86_64.AppImage musrfit --version

npm run dist:runtime builds the RPM, AppImage, and download archive. dist:linux, dist:appimage, and dist:rpm build the lean app package and the matching runtime artifact(s); the AppImage builder reuses electron-builder's cached AppImage runtime and mksquashfs, so run an AppImage build once first (or set APPIMAGE_RUNTIME_BIN/MKSQUASHFS_BIN).

On Windows the same tree is delivered inside the app instead: win.extraResources ships the bin/ markers plus the WSL2 rootfs archive.

Overridable environment variables (set before bash packaging/runtime/build.sh):

  • ROOT_VERSION (default 6.38.00)
  • BASE_IMAGE (default quay.io/pypa/manylinux_2_28_x86_64)
  • JOBS (default: number of CPUs)
  • MUSRFIT_REPO (default: the sibling ../musrfit.psi checkout)

Download archive

Produce just the plain Linux runtime download, without electron-builder, fpm, FUSE, or administrator access:

npm run dist:runtime:archive

The Linux release commands also produce this download alongside their normal app/runtime packages. RUNTIME_DIR selects an existing validated runtime and OUT_DIR selects the output base directory (default dist). ARCH, when set, must match the actual binaries. The archive builder uses Python 3 on the build machine; the downloaded runtime does not need Python for installation.

Each complete bundle is published into its own content-addressed directory:

dist/runtime-downloads/musrflow-runtime-linux-x64-<archive-hash-prefix>/
  musrflow-runtime-linux-x64-<archive-hash-prefix>.tar.gz
  musrflow-runtime-linux-x64-<archive-hash-prefix>.tar.gz.sha256
  runtime-download.json

runtime-download.json has schemaVersion: 1, kind: "musrflow-runtime-download", the complete runtime manifest under runtime, and an artifact object containing filename, format, rootDirectory, byte size, and the full archive sha256. The filename is relative to this descriptor, so the bundle can be published unchanged on a trusted HTTPS release server without embedding build-machine paths or URLs. The Linux desktop can install this bundle locally through Preferences. Online runtime downloads are not enabled yet; no default release-server URL is assumed.

The archive contains one top-level runtime/ directory, including the startup XML, manifest, ROOT headers/fonts/configuration, and relative library links. The builder copies a private snapshot, validates it, and preserves executable permissions while normalizing timestamps and archive ownership. Rebuilding identical contents reuses the existing bundle. Any payload change, including a support file outside the manifest's core fingerprints, produces a different archive checksum and bundle. Failed or conflicting builds do not overwrite previous downloads. Absolute/external/broken symlinks and special files are rejected rather than producing a non-relocatable package.

For manual/offline use, run these commands from the bundle directory to verify the SHA-256 sidecar, extract into a fresh writable directory, and point the existing application at the resulting prefix:

sha256sum -c ./*.sha256
tar -xzf ./musrflow-runtime-*.tar.gz -C /path/to/empty-directory
MUSRFLOW_RUNTIME_ROOT=/path/to/empty-directory/runtime musrflow

This bundles the scientific toolchain, not the operating system. A compatible Linux installation and the normal desktop/display services are still needed. Windows continues using its WSL2 rootfs; native macOS delivery is a separate step.

Offline desktop installation

User steps are in the Linux installation guide. The following describes validation and persistence for maintainers.

After Install and use, the main process verifies the entire archive hash, checks its entries and disk-space requirements, extracts into private staging, verifies the manifest/core files, and starts the required tools before keeping the new tree under Electron's per-user runtimes/ directory. No Python, system tar, FUSE, administrator privileges, or network connection are required for this installation path. Progress and cancellation are available in Preferences, and Fit/Plot stay disabled until the operation finishes.

The verified bin/ directory becomes the saved binaries preference only after success. Merely having private runtimes on disk does not shadow a host setup; its ROOT environment is used only when that private tree is explicitly selected. System tools and user startup XML files are not rewritten. Failed or cancelled installs retain the previous selection. Existing valid trees can be reused; repair installs keep a damaged tree intact and use a fresh sibling. Cancelling other Preferences edits after a successful install does not undo the separately confirmed installation/selection.

Notes / open items

  • The manylinux_2_28 base (AlmaLinux 8, glibc 2.28) is used because ROOT 6.38 needs a C++17 toolchain that the original CentOS 7 / manylinux2014 image does not provide out of the box. Override BASE_IMAGE to target a different glibc baseline.
  • bundle-deps copies the non-glibc shared-library closure using an allow-list of host-provided libraries. Review runtime/lib after a build and add any missing sonames to the allow-list in build-runtime.sh.
  • The runtime is git-ignored (runtime/*, !runtime/.gitkeep); only the build recipe and the placeholder are committed.
  • Windows delivery reuses this same Linux tree inside a bundled WSL2 distribution (tracked separately).

Verifying a build

bash packaging/runtime/validate-runtime.sh runtime
ldd runtime/bin/musrt0 | grep -v "$PWD/runtime"   # only host-provided libs left

The runtime build and RPM/AppImage packaging all run this validation. The WSL2 builder runs it inside the staging container at the installed prefix before exporting the rootfs. Missing tools, missing/empty startup XML, and failing version commands stop production rather than producing a partial runtime.

Each version command has a 15-second limit (RUNTIME_CHECK_TIMEOUT overrides the seconds) and uses only the runtime's own ROOT/musrfit library path. This is a headless startup check, not a substitute for a Fit/Plot smoke test on a clean target system. It does not change how the application uses an existing local ROOT/musrfit installation.

Runtime identity

Runtime artifacts now require runtime-manifest.json. The build records it only after the required tools start successfully. Packaging checks the record but never regenerates it automatically. Python 3 is needed on the build/packaging machine (and in the WSL staging container), not by the installed application.

The versioned JSON record contains:

  • A runtimeId independent of the GUI version, derived from the platform, architecture, ROOT/musrfit versions, musrfit revision, and file fingerprints.
  • The actual native architecture from ELF headers, rather than an artifact name.
  • SHA-256 fingerprints of the six tools and the principal ROOT/musrfit libraries.
  • For source builds, the source checkout's full revision and dirty status, the container base-image reference, and relevant options from the CMake caches.
  • A UTC recording date, distinct from any claimed historical build date.

Artifact filenames still carry the GUI release label; runtimeId identifies the underlying runtime independently, allowing its reuse across GUI releases.

Every musrfit tool must report the same version/revision and the same ROOT version as root-config. The source revision must also match the built tools when a source checkout is supplied. RPM/AppImage packaging currently targets x86_64; other architecture labels are rejected. The WSL payload retains its Linux identity because its executables run inside Linux.

For an existing runtime predating this metadata, explicitly record its current contents once, then validate normally:

bash packaging/runtime/validate-runtime.sh --record-manifest runtime
bash packaging/runtime/validate-runtime.sh runtime

This inspects the actual binaries without rebuilding or altering them. Unknown historical build settings remain null with build.origin set to existing; the current source checkout is not assumed to have produced those binaries. Fingerprint checks cover the listed tools/libraries, not the entire runtime tree; archive checksums and clean-system Fit/Plot tests remain necessary. No manifest is required for a user's ordinary host-installed musrfit/ROOT.