mx/Jungfraujoch
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 67 Wiki Activity

docs: write down what a release ships

Browse Source 
Nothing said what is in a release or what it needs of the machine it lands on: that the
Linux binaries are built -march=x86-64-v3 and the Windows ones /arch:AVX, so each has a
CPU floor; that the portable .tgz is built on RHEL 8 for its glibc; that the Windows
installer is MSVC (Visual Studio 2026), CUDA 13.3, Qt 6.11 and carries the Qt runtime;
and above all what the CUDA variants need. Only cuFFT is linked dynamically, and it has
no link-time dependency on the driver library, so a CUDA build starts on a machine with
no NVIDIA GPU at all and falls back to the CPU path - as long as cuFFT can be loaded,
which the .tgz and the installer arrange by shipping it and the distribution packages
arrange through the distribution's own CUDA packages. Collected into a new page rather
than scattered over the install instructions.

The repository page had the RHEL 9 rows pointing at el8 paths under the wrong slsdet
number, no rows at all for the two slsdet9 repositories the pipeline uploads, a driver
package named jfjoch-driver where it is jfjoch-driver-dkms, and a note that RPMs are
unsigned from before the pipeline started uploading them with sign=true.

The FPGA page had a paragraph that stopped mid-sentence, in the middle of a link, and a
section describing a firmware build triggered by commit message. The firmware is stable
and carried from version to version now.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
leonarski_f
2026-08-03 20:53:19 +02:00
co-authored by Claude Opus 5
parent d615b900dd
commit 46930142dd
7 changed files with 161 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOYMENT.md
+7 -4
View File
@@ -7,9 +7,11 @@ To deploy Jungfraujoch, one needs to follow four steps:
3. Install Jungfraujoch writer
4. Install Python OpenAPI client
Installation procedure depend a lot on the operating system. For RedHat Enterprise Linux 8, Rocky 8, or compatible
installation can be done with prebuilt RPMs and is relatively straightforward. For other systems one needs to build
software from source. Both ways will be presented.
Installation procedure depend a lot on the operating system. For RedHat Enterprise Linux 8/9, Rocky 8/9,
Ubuntu 22.04/24.04 or compatible, installation can be done with prebuilt packages from the
[package repositories](REPOSITORIES.md) and is relatively straightforward. For other systems one needs
to build software from source. Both ways will be presented. What each released package contains, and
what it needs on the machine, is described in [Release contents](RELEASE_CONTENTS.md).
## Install main Jungfraujoch code and frontend web interface
@@ -88,7 +90,8 @@ $ dmesg |grep jfjoch
```
If things work, it is recommended to install the driver with DKMS, so it is rebuilt for kernel updates.
On RHEL 8 you can install prebuilt RPM provided in the Gitlab package registry. On other systems follow procedure in
On RHEL 8 you can install the prebuilt `jfjoch-driver-dkms` package from the
[Gitea package registry](REPOSITORIES.md). On other systems follow procedure in
[PCIe driver](FPGA_PCIE_DRIVER.md).
NOTE: Driver installation procedure on non-RHEL 8 systems is not well understood/optimized at the moment.
docs/DETECTORS.md
+3 -1
View File
@@ -2,7 +2,9 @@
## PSI detectors
Jungfraujoch supports PSI JUNGFRAU and PSI EIGER detectors. Jungfruajoch controls the detector via statically compiled `slsDetectorPackage` into its source code.
It is important that detector firmware has to match `slsDetectorPackage` version used in Jungfraujoch (8.0.2 at the moment).
It is important that detector firmware has to match `slsDetectorPackage` version used in Jungfraujoch.
The default is 8.0.2; 9.2.0 is built with the `SLS9=ON` CMake option and published in the `slsdet9`
[package repositories](REPOSITORIES.md).
See [PSI Detector group website](https://www.psi.ch/en/lxn/software-releases) for details.
# DECTRIS detectors
docs/FPGA.md
+6 -5
View File
@@ -23,8 +23,8 @@ are necessary. It is designed for detector directly connected to the Jungfraujoc
See [network documentation](FPGA_NETWORK.md) for details of network.
## Building firmware
Xilinx Vivado version has to precisely match version described in [the system requirements](../README.md.
only when `vivado` and `vitis_hls` are detected in the path.
The firmware build targets are generated by CMake only when `vivado` and `vitis_hls` are detected in
the path, and the Vivado version has to match the one below precisely.
### Xilinx Vivado
The following procedures require having AMD (Xilinx) Vivado and Vitis HLS toolsets version **2022.2** installed on the machine.
@@ -69,9 +69,10 @@ $ make pcie_100g
make: *** No rule to make target 'pcie_100g'. Stop.
```
### Gitlab CI
If Gitlab CI is properly set-up, firmware will be automatically built for every commit that starts with FPGA.
Built firmware should be downloaded as MCS files.
### Firmware releases
The firmware is stable and is carried from version to version: the MCS files attached to a release
are normally the ones from the release before it (see [Release contents](RELEASE_CONTENTS.md)). When
it does need to change, it is rebuilt with the targets above on a machine with Vivado.
### Frame generator
docs/RELEASE_CONTENTS.md
+115
View File
@@ -0,0 +1,115 @@
# Release contents
This page describes **what a Jungfraujoch release ships and what each artefact needs on the target
machine** — which CPU instruction set the binaries were compiled for, which CUDA toolkit they were
built against, and which runtime libraries are bundled rather than expected from the host.
The artefacts in the table below are built and published by the continuous-integration pipeline
(`.gitea/workflows/build_and_test.yml`) when a tag is pushed. For *how* to install and configure the
result see [Deployment](DEPLOYMENT.md); for the package-repository URLs see
[Linux package repositories](REPOSITORIES.md).
## Artefacts
| Artefact | Distributed via | Contains |
| --- | --- | --- |
| `.rpm` / `.deb` packages | [package repositories](REPOSITORIES.md) | The full server stack: `jfjoch` (broker, frontend, FPGA and detector tools), `jfjoch-writer`, `jfjoch-viewer` (incl. the XDS plugin), `jfjoch-driver-dkms` |
| `jfjoch_viewer-<version>-linux-cuda<major>.tgz`, `...-linux-cpu.tgz` | Gitea release page | Portable Linux viewer package: `jfjoch_viewer`, `rugnux`, `jfjoch_extract_hkl`, `jfjoch_recompress` and the license notices |
| `jfjoch-viewer-<version>-win64-cuda<major>.exe`, `...-win64-cpu.exe` | Gitea release page | Windows installer with the same four programs, plus the Qt runtime |
| `jfjoch-writer` `.rpm` / `.deb` | Gitea release page | The writer alone, for a file-writing machine without the rest of the stack |
| `libjfjoch_xds_plugin.so.<version>` | Gitea release page | XDS HDF5 read plugin (built on RHEL 8); see [Integration with MX software](SOFTWARE_INTEGRATION.md) |
| `jfjoch-client` | [PyPI](https://pypi.org/project/jfjoch-client/) and the Gitea PyPI index | Generated Python OpenAPI client |
| Documentation | [Read the Docs](https://jungfraujoch.readthedocs.io) and the `gitea-pages` branch | This documentation set |
The FPGA firmware (`.mcs`) images are attached to the release as well. The firmware is stable and is
carried from version to version, and is rebuilt with Vivado (see [FPGA smartNIC](FPGA.md)) when it
needs to change — so a card keeps its image across a software upgrade unless the release notes say
otherwise.
## CPU instruction set
The architecture flags live in the CI configuration rather than in `CMakeLists.txt`, so a site
building from source picks its own (`x86-64-v4` on an AVX-512 cluster, `-march=native`, or the plain
baseline the compiler defaults to). The released binaries are compiled to a fixed floor:
| Release | Flags | Minimum CPU |
| --- | --- | --- |
| Linux (all packages, and the portable `.tgz`) | `-march=x86-64-v3 -flto=auto` | AVX2 + FMA + BMI2 — Intel Haswell (2013) / AMD Zen (2017) and newer |
| Windows installer | `/arch:AVX` | AVX — Intel Sandy Bridge (2011) / AMD Bulldozer and newer |
The Windows floor is lower because MSVC has no spelling for the `x86-64-v2` level; `/arch:AVX` is
the nearest one and implies SSE4.1/4.2, which is what actually matters — without it Eigen has no
vectorised `round` and falls back to a libm call per element. Link-time optimisation is applied on
Linux only.
A binary will fault with an illegal instruction on a CPU below its floor. If you must run on older
hardware, build from source without the flags.
## Operating-system floor
The `.rpm` / `.deb` packages are built per distribution (RHEL/Rocky 8 and 9, Ubuntu 22.04 and 24.04)
and are tied to it. The portable viewer `.tgz` is built on RHEL 8, the oldest supported
distribution, so its glibc floor is low enough to run on any newer Linux — that is what it is for,
and why it replaces the per-distro packaging of the viewer on the release page. The Windows
installer is built and verified on Windows 11.
## CUDA and non-CUDA builds
Every binary artefact is released in **two variants**, `cuda<major>` and `cpu`. The CUDA variant adds
the GPU fast-feedback indexer (`ffbidx`), the GPU FFT indexer and GPU image processing; the CPU-only
variant runs the same pipeline on the CPU with the FFTW indexer, at much lower throughput.
The CUDA toolkit used is the one on the corresponding build machine: **CUDA 12** for the RHEL 8
packages, **CUDA 13** for RHEL 9, Ubuntu and Windows. The major version is part of the artefact and
repository name, so a download is self-identifying. Building from source needs CUDA 12.8 or newer.
**A CUDA build does not require a CUDA machine.** Of the CUDA components only **cuFFT** is linked
dynamically — the CUDA runtime and the fast-feedback indexer are linked statically — and cuFFT
itself has no link-time dependency on the NVIDIA driver library. Jungfraujoch asks how many CUDA
devices are present at start-up and treats "none" (including "no driver installed") as zero GPUs,
falling back to the CPU path. So a CUDA build starts and runs correctly on a machine with no NVIDIA
GPU at all, provided the cuFFT runtime can be loaded:
- **Portable `.tgz` and Windows installer** — cuFFT is **part of the distribution**, shipped next to
the executable (on Linux found through an `$ORIGIN` rpath). Nothing else is needed: no CUDA
toolkit, and on a GPU machine only the NVIDIA driver.
- **`.rpm` / `.deb`** — cuFFT comes from the distribution's own CUDA packages, so that one
dependency is managed centrally with the rest of CUDA. Install the cuFFT package alongside, or use
the `nocuda` repositories on a machine where CUDA is not wanted.
The cuFFT runtime is large (the Windows DLL is ~256 MB), so the CUDA artefacts are correspondingly
bigger than the CPU ones — the other reason for shipping both.
On a machine with an NVIDIA GPU, take the CUDA variant: only that one uses the GPU.
## Windows installer
The Windows artefact covers `jfjoch_viewer` and the portable analysis CLIs only; the rest of
Jungfraujoch (broker, receiver, FPGA host, detector control) is Linux-only.
The toolchain bounds of the released installer are:
- **Visual Studio 2026** with the C++ (MSVC) toolset. MSVC is not optional — CUDA on Windows builds
through it — and it is what the release is compiled with.
- **CUDA Toolkit 13.3** for the `cuda13` variant.
- **Qt 6.11** for MSVC (`msvc2022_64`), including Qt Charts.
- Ninja as the generator; zlib and Eigen 3.4 supplied from a build prefix.
The installer is generated with NSIS and **bundles the Qt runtime** (via `windeployqt`) and, on the
CUDA variant, the cuFFT DLL — so the end user installs neither Qt nor a CUDA toolkit. The two
variants share an install directory and Start Menu group and replace each other (CUDA is a strict
superset); they are told apart by the installer filename and the Add/Remove Programs entry:
| Build | Installer file | Add/Remove Programs |
| --- | --- | --- |
| CUDA (default) | `jfjoch-viewer-<version>-win64-cuda<major>.exe` | `Jungfraujoch (CUDA)` |
| CPU-only | `jfjoch-viewer-<version>-win64-cpu.exe` | `Jungfraujoch (CPU)` |
To build the viewer yourself on Windows, see
[jfjoch_viewer ▸ Building from source on Windows](JFJOCH_VIEWER.md#building-from-source-on-windows).
## Licenses
Every package variant carries the project license, the third-party manifest and the verbatim
license texts of the bundled dependencies under `share/doc/jfjoch`. See
[Third-party software notices](THIRD_PARTY_NOTICES.md).
docs/REPOSITORIES.md
+24 -18
View File
@@ -2,30 +2,37 @@
For convenience, we are providing package repositories. With versions including and excluding CUDA linking.
We recommend to install Jungfraujoch viewer from `nocuda` repository and remaining packages from `cuda12`/`cuda13` repository.
The repository name encodes two choices: the [slsDetectorPackage](DETECTORS.md) version the packages
were built against (`slsdet8` = 8.0.2, `slsdet9` = 9.2.0 — it must match the detector firmware) and
whether CUDA is linked in. What ends up inside each package, and what it needs on the target
machine, is described in [Release contents](RELEASE_CONTENTS.md).
## RHEL based systems
For RHEL systems we provide the following repositories:
| RHEL version | CUDA | Repository file |
|--------------|------|-------------------------------------------------------------------------|
| 8.x | 12.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo |
| 8.x | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-nocuda.repo |
| 9.x | 13.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet9-cuda13.repo |
| 9.x | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet9-nocuda.repo |
| RHEL version | slsDetectorPackage | CUDA | Repository file |
|--------------|--------------------|------|------------------------------------------------------------------------|
| 8.x | 8.0.2 | 12.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo |
| 8.x | 9.2.0 | 12.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet9-cuda12.repo |
| 8.x | 8.0.2 | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-nocuda.repo |
| 9.x | 8.0.2 | 13.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-cuda13.repo |
| 9.x | 9.2.0 | 13.x | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet9-cuda13.repo |
| 9.x | 8.0.2 | - | https://gitea.psi.ch/api/packages/mx/rpm/centos/el9/slsdet8-nocuda.repo |
To install the repository, run:
```bash
dnf config-manager --add-repo https://gitea.psi.ch/api/packages/mx/rpm/centos/el8/slsdet8-cuda12.repo
```
Currently signing of RPMs is not supported, so the repository file needs to be manually modified to set `gpgcheck=0`
or installation must run with `--nogpgcheck`.
RPMs are signed by the Gitea package registry as they are uploaded. If your system cannot verify the
signature, set `gpgcheck=0` in the repository file or install with `--nogpgcheck`.
We provide the following packages in the repository:
* jfjoch
* jfjoch-driver
* jfjoch-writer
* jfjoch-viewer
* jfjoch — broker, web frontend, FPGA and detector command-line tools
* jfjoch-driver-dkms — PCIe kernel-module source, built by DKMS
* jfjoch-writer — HDF5 writer service
* jfjoch-viewer — desktop viewer, the offline analysis tools and the XDS plugin
## Ubuntu based systems
@@ -37,11 +44,10 @@ sudo apt update
```
`$distribution` uses Ubuntu names `jammy` (22.04) and `noble` (24.04). `$component` can be set to `cuda13` and `nocuda`.
Only slsDetectorPackage 8.0.2 is built for Ubuntu.
We provide the following packages in the repository:
* jfjoch-jfjoch
* jfjoch-driver
* jfjoch-writer
* jfjoch-viewer
The same four packages as above are provided: `jfjoch`, `jfjoch-driver-dkms`, `jfjoch-writer` and
`jfjoch-viewer`. Up to 1.0.0-rc.160 the first of them was misnamed `jfjoch-jfjoch`; the current
package replaces it, so `apt upgrade` handles the rename.
Ubuntu packages are currently only going through a very limited testing.
Ubuntu packages are currently only going through a very limited testing.
docs/SOFTWARE.md
+5 -4
View File
@@ -7,12 +7,13 @@ On experimental basis we also build repositories for Ubuntu 22.04 and 24.04.
Running Jungfraujoch on Red Hat Enterprise Linux 7 is currently not tested and not recommended,
but likely possible with providing some packages from external repositories.
The desktop viewer `jfjoch_viewer` (only) can additionally be built on **Windows 11** with Visual
Studio 2026 (MSVC), CUDA 13.3 and Qt 6.11 — see
[jfjoch_viewer ▸ Building from source on Windows](JFJOCH_VIEWER.md#building-from-source-on-windows).
The desktop viewer `jfjoch_viewer` (only) additionally runs on **Windows 11**, where it is shipped as
a pre-built installer; it can also be built from source with Visual Studio 2026 (MSVC), CUDA 13.3 and
Qt 6.11 — see [jfjoch_viewer ▸ Building from source on Windows](JFJOCH_VIEWER.md#building-from-source-on-windows).
The Windows installer bundles the Qt runtime, and on the CUDA build the CUDA runtime (cuFFT) as
well, so end users need neither Qt nor a CUDA toolkit installed — only an NVIDIA GPU driver for the
GPU path. The rest of Jungfraujoch is Linux-only.
GPU path. The rest of Jungfraujoch is Linux-only. See [Release contents](RELEASE_CONTENTS.md) for the
CPU baseline and CUDA requirements of each released package.
## Software dependencies
docs/index.rst
+1
View File
@@ -23,6 +23,7 @@ Jungfraujoch is distributed under the GPLv3 license.
SOFTWARE
VERSIONING
DEPLOYMENT
RELEASE_CONTENTS
REPOSITORIES
NAMING
CHANGELOG