Document CI packaging, releases, and Wine build requirement
Validate TRIMSP / validate (push) Successful in 9s

This commit is contained in:
salman committed 2026-11-16 17:28:18 +01:00
1 parent 032649eaeb
commit 9c5e78ff03
7 files changed
+152 -6

No files matched your search

+22
View File
@@ -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<version>`
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 <https://doi.org/10.1103/PhysRevApplied.19.044018> and
<https://doi.org/10.1016/j.nimb.2025.165954>, replacing the previous
"unpublished" note.
### Fixed
+24
View File
@@ -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<package.json version>` 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
+1 -1
View File
@@ -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
+1
View File
@@ -27,6 +27,7 @@ tabs and mirroring the in-app Quick Start help (the ``?`` button).
advanced
sharing
web-deployment
releasing
troubleshooting
glossary
+88
View File
@@ -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``.
+4
View File
@@ -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.
+12 -5
View File
@@ -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.