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.
287 lines
13 KiB
Markdown
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.
|