# 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 `/runtime`. **Installing rather than building?** Follow the [Linux installation guide](../../docs/source/install-linux.rst) or [Windows installation guide](../../docs/source/install-windows.rst). 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` | `` | | `MUSRFITPATH` | `` (musrfit finds `/musrfit_startup.xml`) | | `LD_LIBRARY_PATH` | `/lib` prepended to the host value | | `PATH` | `/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](../wsl2/README.md#how-it-works). Resolution order for a tool (`resolveLocalCommand`): 1. user-configured tools directory (Preferences → musrfit binaries) 2. `/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. `/bin`, `` 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. ```sh bash packaging/runtime/build.sh ``` Override the checkout with an absolute path when needed: ```sh 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 `/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](../../docs/DESKTOP_DEPLOYMENT.md#building-the-windows-installer). 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): ```sh packaging/runtime/build-runtime-rpm.sh # dist/musrflow-runtime--x86_64.rpm packaging/runtime/build-runtime-appimage.sh # dist/musrflow-runtime--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: ```sh ./musrflow-runtime--x86_64.AppImage --install [DIR] ./musrflow-runtime--x86_64.AppImage --prefix ./musrflow-runtime--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). `npm run dist:app:rpm`, `dist:app:appimage`, and `dist:app:linux` build only the lean muSRFlow application package(s) and do not require a local `runtime/` tree. 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: ```sh 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: ```text dist/runtime-downloads/musrflow-runtime-linux-x64-/ musrflow-runtime-linux-x64-.tar.gz musrflow-runtime-linux-x64-.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: ```sh 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](../../docs/source/install-linux.rst#install-the-separate-runtime-from-a-local-bundle). 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 ```sh 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: ```sh 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.