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):
- user-configured tools directory (Preferences → musrfit binaries)
<resources>/runtime/bin(runtime bundled inside the app)/opt/musrflow/runtime/bin(separately installed runtime; override withMUSRFLOW_RUNTIME_ROOT)/usr/local/bin,/usr/bin<resources>/bin,<resources>- 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(default6.38.00)BASE_IMAGE(defaultquay.io/pypa/manylinux_2_28_x86_64)JOBS(default: number of CPUs)MUSRFIT_REPO(default: the sibling../musrfit.psicheckout)
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_IMAGEto target a different glibc baseline. bundle-depscopies the non-glibc shared-library closure using an allow-list of host-provided libraries. Reviewruntime/libafter a build and add any missing sonames to the allow-list inbuild-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
runtimeIdindependent 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.