From 46930142dd7b524ff6b9f5ae8ddc2dfc3e0bab87 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 3 Aug 2026 20:53:19 +0200 Subject: [PATCH] docs: write down what a release ships 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) --- docs/DEPLOYMENT.md | 11 ++-- docs/DETECTORS.md | 4 +- docs/FPGA.md | 11 ++-- docs/RELEASE_CONTENTS.md | 115 +++++++++++++++++++++++++++++++++++++++ docs/REPOSITORIES.md | 42 ++++++++------ docs/SOFTWARE.md | 9 +-- docs/index.rst | 1 + 7 files changed, 161 insertions(+), 32 deletions(-) create mode 100644 docs/RELEASE_CONTENTS.md diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 1a3e757b..12a394ec 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -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. diff --git a/docs/DETECTORS.md b/docs/DETECTORS.md index 4e817fe3..a4d56b76 100644 --- a/docs/DETECTORS.md +++ b/docs/DETECTORS.md @@ -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 diff --git a/docs/FPGA.md b/docs/FPGA.md index 61a4fcc7..a92e413b 100644 --- a/docs/FPGA.md +++ b/docs/FPGA.md @@ -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 diff --git a/docs/RELEASE_CONTENTS.md b/docs/RELEASE_CONTENTS.md new file mode 100644 index 00000000..5b131f8f --- /dev/null +++ b/docs/RELEASE_CONTENTS.md @@ -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--linux-cuda.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--win64-cuda.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.` | 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` 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--win64-cuda.exe` | `Jungfraujoch (CUDA)` | +| CPU-only | `jfjoch-viewer--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). diff --git a/docs/REPOSITORIES.md b/docs/REPOSITORIES.md index b03b211f..133f8b6f 100644 --- a/docs/REPOSITORIES.md +++ b/docs/REPOSITORIES.md @@ -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. \ No newline at end of file +Ubuntu packages are currently only going through a very limited testing. diff --git a/docs/SOFTWARE.md b/docs/SOFTWARE.md index 4361129c..365c1a4c 100644 --- a/docs/SOFTWARE.md +++ b/docs/SOFTWARE.md @@ -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 diff --git a/docs/index.rst b/docs/index.rst index af2cd19d..20b8256d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ Jungfraujoch is distributed under the GPLv3 license. SOFTWARE VERSIONING DEPLOYMENT + RELEASE_CONTENTS REPOSITORIES NAMING CHANGELOG