From 9c5e78ff03484f31863a0e74e1e31796ae3295a0 Mon Sep 17 00:00:00 2001 From: salman Date: Mon, 16 Nov 2026 17:28:18 +0100 Subject: [PATCH] Document CI packaging, releases, and Wine build requirement --- CHANGELOG.md | 22 +++++++++ README.md | 24 ++++++++++ docs/source/advanced.rst | 2 +- docs/source/index.rst | 1 + docs/source/releasing.rst | 88 ++++++++++++++++++++++++++++++++++ docs/source/web-deployment.rst | 4 ++ packaging/wsl2/README.md | 17 +++++-- 7 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 docs/source/releasing.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b6d77c..ae355e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,28 @@ `TRIMSP-NL-Workbench-Setup.exe`) built with electron-builder that bundles the WSL2 runtime; the build refuses to proceed without it. Linux/macOS packaging continues to use electron-forge. +- Automatic packaging and publication in Gitea Actions. `Validate TRIMSP` runs + the runtime tests, `Build and package` produces and publishes the Linux + DEB/RPM set, `Build Windows installer` builds the NSIS installer inside a + Wine-enabled container and publishes it, and `Publish packages` can retry + publication from a saved artifact without rebuilding. Pushing a `v` + tag assembles a draft release once both platforms have published. +- Platform installation guides (`docs/install-windows.md`, + `docs/install-linux.md`), a Sphinx user manual under `docs/`, and a + `scripts/deploy-remote-web.sh` helper that mirrors a tree to a remote web + server and runs `deploy-web.sh` there. + +### Changed + +- Windows packaging moved from electron-forge/Squirrel to electron-builder + NSIS. Cross-building on Linux needs Wine (electron-builder runs + `signtool.exe` under it even for unsigned builds) but no Mono or WoW64 + prefix; `npm run make:win` still works on a developer machine, while CI runs + electron-builder inside `electronuserland/builder:wine`. +- Updated the electronic stopping coefficient references shown for Advanced + option 3 to and + , replacing the previous + "unpublished" note. ### Fixed diff --git a/README.md b/README.md index 23ba6eb..abc9a2e 100644 --- a/README.md +++ b/README.md @@ -240,6 +240,30 @@ npm run checksums The current Flatpak config grants access to the home directory and `/tmp`, which matches how the packaged app currently handles simulation input/output. +###### Automated builds and releases ###### + +Gitea Actions builds and publishes the packages (workflows under +`.gitea/workflows`): + +- **Validate TRIMSP** runs `npm run test:wsl-runtime`. +- **Build and package** produces the Linux DEB/RPM set and publishes the + `trimsp` package group. +- **Build Windows installer** builds the NSIS installer inside a Wine-enabled + container and publishes the `trimsp-windows` package group. +- **Publish packages** retries publication from an existing run artifact + without rebuilding. + +Pushing a `v` tag (e.g. `v1.6.2`) starts both packaging +workflows and assembles a draft Release once Linux and Windows are published. +Publishing requires a `PACKAGES_TOKEN` Actions secret with package write +access (`RELEASES_TOKEN` is optional for release drafts); the Windows job needs +`podman` on the runner and pulls `docker.io/electronuserland/builder:wine` +unless the `TRIMSP_WINDOWS_BUILDER_IMAGE` repository variable overrides it. + +See the [automated builds and releases chapter](docs/source/releasing.rst) for +the full procedure, or the [rendered manual](https://gitea.psi.ch/LMU/TRIMSP) +when available. + ###### Deploying on a web server ###### The repository includes the browser assets, CGI runner, and deployment scripts diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst index 2dd7f53..14238cd 100644 --- a/docs/source/advanced.rst +++ b/docs/source/advanced.rst @@ -1,5 +1,5 @@ Advanced transport parameters -=========================== +============================= The **Advanced** tab exposes collision/recoil and model choices (e.g. interaction potential and electronic stopping parameterizations) used by diff --git a/docs/source/index.rst b/docs/source/index.rst index be7d2b7..407d4d5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,6 +27,7 @@ tabs and mirroring the in-app Quick Start help (the ``?`` button). advanced sharing web-deployment + releasing troubleshooting glossary diff --git a/docs/source/releasing.rst b/docs/source/releasing.rst new file mode 100644 index 0000000..a909a20 --- /dev/null +++ b/docs/source/releasing.rst @@ -0,0 +1,88 @@ +Automated builds and releases +============================= + +Packages are built by the repository's Gitea Actions workflows under +``.gitea/workflows``. They use the shared ``ubuntu-latest-full`` runner and a +Node.js 22 toolchain. Linux and Windows packages are published to the Gitea +generic package registry, and a tagged build also creates a draft Release. + +Workflows +--------- + +``validate.yml`` + Runs ``npm ci`` and the runtime tests (``npm run test:wsl-runtime``) on + pushes to ``master``/``electron-builder-nsis`` and on manual dispatch. + +``build-and-package.yml`` + Builds the static engine, produces the Linux DEB and RPM with + electron-forge, checksums them, uploads the ``trimsp-linux-packages`` + artifact, and publishes the ``trimsp`` package group. + +``build-windows.yml`` + Builds the static engine and the WSL2 rootfs, then builds the NSIS + installer with electron-builder **inside a Wine-enabled container** (the + runner itself does not need Wine). Uploads ``trimsp-windows-x64`` and + publishes the ``trimsp-windows`` package group. + +``publish-packages.yml`` + Re-runs publication for an existing packaging workflow run, so a registry + or token failure can be retried without rebuilding. + +Manual builds +------------- + +Run **Build and package** and/or **Build Windows installer** from the Actions +tab (``workflow_dispatch``). Manual builds publish build-specific package +versions and do not create a draft Release. + +Tagged releases +--------------- + +1. Set the intended version in ``package.json`` (and update ``CHANGELOG.md``). +2. Commit and push to ``master``. +3. Create and push a matching tag, e.g. for version ``1.6.2``: + + .. code-block:: bash + + git tag v1.6.2 + git push origin v1.6.2 + git push gitea-lmu v1.6.2 + +Both packaging workflows start. Each publishes its package group with a +``release-context.json`` marker; the last one to finish creates the draft +Release once Linux and Windows are both available. Review and smoke-test the +downloads before publishing the draft. + +Required secrets and variables +------------------------------ + +Configure these in **Settings > Actions** for the repository: + +``PACKAGES_TOKEN`` + Token with package write access (required; the job token often cannot + write packages). Used for registry uploads and linking. + +``RELEASES_TOKEN`` + Optional token with release write access. Falls back to ``GITEA_TOKEN``. + +``TRIMSP_WINDOWS_BUILDER_IMAGE`` + Optional repository **variable** overriding the Wine builder image used on + the Windows runner. Default: ``docker.io/electronuserland/builder:wine``. + The workflow resolves the image to a digest before building. + +Windows build details +--------------------- + +The Windows job needs ``gfortran``, ``podman``, and network access to pull the +builder image. ``packaging/wsl2/build-windows-ci.sh`` stages the committed +source plus ``resources/bin/trimspNL`` and the rootfs archive, then runs +``electron-builder --win nsis`` in the container. The installer is unsigned; +installation, first-launch WSL import, and a simulation still need a smoke +test on a real Windows host (see :doc:`install-windows`). + +Local packaging +--------------- + +For local builds use ``npm run make`` (Linux) or ``npm run make:win`` +(Windows). Local Windows builds require Wine when cross-building on Linux; +see ``packaging/wsl2/README.md``. diff --git a/docs/source/web-deployment.rst b/docs/source/web-deployment.rst index c80acac..2ed285e 100644 --- a/docs/source/web-deployment.rst +++ b/docs/source/web-deployment.rst @@ -9,3 +9,7 @@ scripts for environment variables such as ``TRIMSP_BIN_PATH`` and On SELinux systems, review denied operations with ``ausearch -m avc -ts recent`` if the CGI or engine cannot execute. + +Packaged desktop builds (Linux DEB/RPM and the Windows installer) are produced +by Gitea Actions; see :doc:`releasing` for the workflows, required secrets, and +the tagged-release procedure. diff --git a/packaging/wsl2/README.md b/packaging/wsl2/README.md index 8a2c913..1b031b4 100644 --- a/packaging/wsl2/README.md +++ b/packaging/wsl2/README.md @@ -93,9 +93,16 @@ 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): nothing extra either. - electron-builder's NSIS target uses its own native tooling, so **no Wine and no - Mono** are required (unlike the former Squirrel path). +- 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 @@ -144,5 +151,5 @@ workbench is often driven remotely. After the first-run import, verify: - `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 needs no extra tooling (electron-builder - NSIS); Windows builds need none either. +- Cross-building the `.exe` from Linux requires Wine (or the CI builder + container); Windows builds need none.