156 lines
6.2 KiB
Markdown
156 lines
6.2 KiB
Markdown
# Windows (WSL2) engine runtime
|
|
|
|
Windows has no native TRIM.SP-NL engine; the Linux engine cannot be run
|
|
directly. Instead TRIMSP-NL Workbench ships the **same statically linked engine**
|
|
used by the Linux bundle and runs it inside a bundled WSL2 distribution.
|
|
|
|
## How it works
|
|
|
|
`TrimSPelec.js` detects the Windows host and the bundled engine
|
|
(`process.platform === "win32"` and `<resources>/bin/trimspNL` present) and
|
|
routes the engine through `wsl.exe`:
|
|
|
|
```
|
|
wsl.exe -d trimspNL-runtime -- /opt/trimsp-runtime/bin/trimspNL <run> [rng]
|
|
```
|
|
|
|
Path arguments (`C:\dir\file`) are translated to their WSL mount form
|
|
(`/mnt/c/dir/file`) so the engine reads and writes the user's Windows files.
|
|
Run inputs and outputs therefore stay on the Windows side.
|
|
|
|
A user-configured **engine binaries** directory with a Windows-native executable
|
|
is launched directly, and on non-Windows hosts the translation is inert, so the
|
|
Linux build and development checkouts are unaffected.
|
|
|
|
Constants (in `TrimSPelec.js`): the distribution name `trimspNL-runtime` and the
|
|
in-distro prefix `/opt/trimsp-runtime`.
|
|
|
|
## Building the rootfs
|
|
|
|
Requires Docker or Podman and the static engine
|
|
(`npm run build:fortran`, built automatically when missing).
|
|
|
|
```sh
|
|
npm run build:wsl2 # packaging/wsl2/build-wsl2.sh
|
|
```
|
|
|
|
Because `trimspNL-static` is a fully static executable (no libc/libgfortran
|
|
runtime dependencies) the rootfs is just a minimal base filesystem plus
|
|
`/opt/trimsp-runtime/bin/trimspNL`. The script writes `/etc/wsl.conf` and exports
|
|
the container filesystem to
|
|
`packaging/wsl2/out/trimspNL-runtime-rootfs.tar.gz`.
|
|
|
|
The script refuses to run if `resources/bin/trimspNL` is not statically linked.
|
|
|
|
## Importing on Windows
|
|
|
|
The import is automated. On first run `main.js` (through `wsl-runtime.js`) checks
|
|
whether the `trimspNL-runtime` distribution is registered and, if not, imports
|
|
the bundled archive into `%LOCALAPPDATA%\TrimSP\trimspNL-runtime` with
|
|
`wsl --import ... --version 2`. The work happens in the background so the window
|
|
opens immediately; progress and failures are broadcast to the renderer on the
|
|
`wslRuntimeStatus` channel. A failed import resets so a later `ensureWslRuntime`
|
|
retries. Before running the engine the renderer awaits `window.TrimSPRuntimeGate`,
|
|
so the first run after startup shows a "Preparing the bundled engine runtime"
|
|
notice and proceeds once the distribution is ready; the gate is a no-op off
|
|
Windows.
|
|
|
|
The equivalent manual command, useful for debugging:
|
|
|
|
```powershell
|
|
wsl --import trimspNL-runtime "$env:LOCALAPPDATA\TrimSP\trimspNL-runtime" trimspNL-runtime-rootfs.tar.gz --version 2
|
|
```
|
|
|
|
Verify:
|
|
|
|
```powershell
|
|
wsl -d trimspNL-runtime -- /opt/trimsp-runtime/bin/trimspNL
|
|
```
|
|
|
|
## Packaging
|
|
|
|
The Windows build ships the rootfs through **electron-builder** (NSIS). The
|
|
`build.win.extraResources` entries in `package.json` copy the rootfs archive flat
|
|
into `resources/` and the engine to `resources/bin/`, matching what
|
|
`wsl-runtime.js` looks for. Linux/macOS packaging still uses electron-forge
|
|
(`forge.config.js`); the two tools coexist.
|
|
|
|
Build the NSIS `Setup.exe`, which contains the app **and** the WSL2 rootfs:
|
|
|
|
```sh
|
|
npm run make:win
|
|
```
|
|
|
|
This runs the whole chain: it compiles the static engine, builds the rootfs, then
|
|
packages and makes the installer for `win32`. A Windows build **requires** the
|
|
rootfs — `packaging/wsl2/require-rootfs.js` fails if `packaging/wsl2/out/` is
|
|
empty, so the `.exe` can never silently ship without its engine. Build from
|
|
Linux/WSL or Windows after building the rootfs first (Windows cannot compile the
|
|
Fortran engine or run the rootfs builder).
|
|
|
|
The installer is written to `dist/` as `TRIMSP-NL-Workbench-Setup.exe`.
|
|
|
|
### Build-host prerequisites
|
|
|
|
- Building the `.exe` **on Windows**: nothing extra.
|
|
- Building the `.exe` **on Linux** (cross-build): **Wine is required**.
|
|
electron-builder runs `signtool.exe`/NSIS helpers under Wine even for an
|
|
unsigned build; without it the NSIS step fails with
|
|
`wine process failed ENOENT`. Mono is not needed (unlike the former Squirrel
|
|
path).
|
|
- On CI, Wine is supplied by a builder container rather than the runner:
|
|
`.gitea/workflows/build-windows.yml` pulls
|
|
`docker.io/electronuserland/builder:wine` (override with the
|
|
`TRIMSP_WINDOWS_BUILDER_IMAGE` repository variable) and runs
|
|
`packaging/wsl2/build-windows-ci.sh`, which calls electron-builder inside it.
|
|
|
|
### Verifying the shipped .exe
|
|
|
|
The app inside the install loads the engine only through WSL, so the same manual
|
|
remote-session check below applies after installing the `.exe`.
|
|
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
npm run test:wsl-runtime # tests/wsl-runtime.test.js + tests/runtime-gate.test.js
|
|
```
|
|
|
|
Covers the pure main-process module (with an injected `wsl.exe` spawner), the
|
|
renderer-side launch translation, including inertness on Linux, and that the
|
|
scan pipeline awaits the runtime gate before launching the engine.
|
|
|
|
## Manual remote-session smoke test
|
|
|
|
The engine path is a console process and never touches the display, so it cannot
|
|
misroute a window the way the file dialogs could. It is still worth checking once
|
|
on a real Windows host, and especially over SSH/RDP, since that is how the
|
|
workbench is often driven remotely. After the first-run import, verify:
|
|
|
|
1. The import succeeded and the engine runs in the distribution:
|
|
|
|
```powershell
|
|
wsl -d trimspNL-runtime -- /opt/trimsp-runtime/bin/trimspNL
|
|
```
|
|
|
|
Expected: the `Usage: trimspNL <run_basename> [ranlux|pcg32|xoshiro]` banner.
|
|
|
|
2. Over a remote session (SSH/RDP, not just a local console), launch the app, set
|
|
a Work Folder on a Windows drive, and click Run. Expected: `<prefix>_E*_.rge`
|
|
and `_Seq_Results.dat` appear in that folder, proving both the path
|
|
translation and the `wsl.exe` spawn work without a local display.
|
|
|
|
3. The status bar first shows "Preparing the bundled engine runtime (first run
|
|
only)..." and the run then proceeds, proving the runtime gate waited for the
|
|
import rather than racing it.
|
|
|
|
### Open items
|
|
|
|
- The rootfs is built from `almalinux:8`. Adjust `BASE_IMAGE` if the engine is
|
|
rebuilt against a different baseline.
|
|
- `wsl.exe` availability is assumed; older Windows builds without WSL2 must
|
|
install it (`wsl --install`) first.
|
|
- The macOS runtime is not built.
|
|
- Cross-building the `.exe` from Linux requires Wine (or the CI builder
|
|
container); Windows builds need none.
|