Files
Zaher Salman afba1faf03 Add app-only Linux packaging scripts
Provide dist:app:rpm, dist:app:appimage, and dist:app:linux to build the
lean muSRFlow application packages without requiring or producing runtime
artifacts. Keep existing dist:rpm/dist:appimage/dist:linux behavior for
full application+runtime distributions and document the difference.
2026-11-18 14:50:53 +01:00

287 lines
13 KiB
Markdown

# 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](../../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` | `<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](../wsl2/README.md#how-it-works).
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.
```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 `<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](../../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-<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:
```sh
./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). `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-<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:
```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.