Document CI packaging, releases, and Wine build requirement
Validate TRIMSP / validate (push) Successful in 9s
Validate TRIMSP / validate (push) Successful in 9s
This commit is contained in:
1 parent
032649eaeb
commit
9c5e78ff03
7 files changed
+152
-6
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -27,6 +27,7 @@ tabs and mirroring the in-app Quick Start help (the ``?`` button).
|
||||
advanced
|
||||
sharing
|
||||
web-deployment
|
||||
releasing
|
||||
troubleshooting
|
||||
glossary
|
||||
|
||||
|
||||
@@ -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``.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user