Jungfraujoch/docs/RELEASE_CONTENTS.md

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; for the package-repository URLs see Linux package repositories.

Artefacts

Artefact	Distributed via	Contains
.rpm / .deb packages	package repositories	The full server stack: jfjoch (broker, frontend, FPGA and detector tools), jfjoch-writer, jfjoch-viewer (incl. the XDS plugin), jfjoch-driver-dkms, and rugnux (offline analysis, independent of the rest)
jfjoch_viewer-<version>-linux-cuda<major>.tgz, ...-linux-cpu.tgz	Gitea release page	Portable Linux viewer: jfjoch_viewer, its desktop entry, icon and D-Bus service, and the license notices
jfjoch-viewer-<version>-win64-cuda<major>.exe, ...-win64-cpu.exe	Gitea release page	Windows installer for jfjoch_viewer, plus the Qt runtime
jfjoch-viewer-<version>-macos-arm64.dmg	Gitea release page	macOS disk image with jfjoch_viewer.app (Apple Silicon), the Qt runtime and the license notices inside the app
rugnux-<version>-linux-x86_64-cuda<major>.tgz, ...-linux-x86_64-cpu.tgz	Gitea release page	Portable Linux rugnux, the offline analysis CLI, and the license notices. One executable
rugnux-<version>-linux-aarch64-cuda<major>.tgz	Gitea release page	The same, cross-built for 64-bit Arm — NVIDIA GH200 and DGX Spark
rugnux-<version>-win64-cuda<major>.zip, ...-win64-cpu.zip	Gitea release page	The same for Windows, plus the cuFFT DLL in the CUDA variant
rugnux-<version>-macos-arm64-cpu.tgz	Gitea release page	The same for macOS on Apple Silicon, CPU only
jfjoch-writer .rpm / .deb	Gitea release page	The writer alone, for a file-writing machine without the rest of the stack
jfjoch_xds_plugin-<version>-linux-x86_64.tgz	Gitea release page	XDS HDF5 read plugin (lib/libjfjoch_xds_plugin.so.<n>, built on RHEL 8) and its license notices; see Integration with MX software
jfjoch-client	PyPI and the Gitea PyPI index	Generated Python OpenAPI client
Documentation	Read the Docs 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) 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
macOS .dmg and rugnux .tgz	none (the compiler's default Apple Silicon target)	Any Apple Silicon Mac — M1 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. The macOS artefacts need no flag: the Apple compiler's default target is already the M1, the oldest Apple Silicon chip.

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 and the x86_64 rugnux .tgz are built on RHEL 8, the oldest supported distribution, so their glibc floor is low enough to run on any newer Linux — that is what they are for, and why they replace the per-distro packaging of those programs on the release page. The aarch64 rugnux .tgz is the exception: it is cross-built against Ubuntu 24.04, so it needs glibc 2.39 or newer (which DGX OS 7 and any current Arm server distribution have). The Windows installer is built and verified on Windows 11. The macOS artefacts need macOS 13 (Ventura) or newer — the floor of the Qt 6.11 they bundle — and an Apple Silicon Mac; see macOS below.

The portable archives have no top-level directory. They unpack straight into bin/ and share/, so always extract them into a directory of their own (tar xzf … -C /opt/rugnux-<version>) rather than into a working directory.

CUDA and non-CUDA builds

Every Linux and Windows binary artefact is released in two variants, cuda<major> and cpu (the macOS ones exist only as cpu: there is no CUDA on macOS). 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. 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. What each artefact has to find at run time differs:

• Portable Linux .tgz — nothing. The CUDA runtime, the fast-feedback indexer and cuFFT are all linked statically, so each archive is a single executable that depends on nothing but the C and C++ runtimes. On a GPU machine the NVIDIA driver is the only NVIDIA component needed.
• Windows installer and .zip — the CUDA toolkit ships no static cuFFT for Windows, so the cuFFT DLL is part of the distribution, next to the executable. No CUDA toolkit is needed.
• .rpm / .deb — these deliberately keep cuFFT dynamic, 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.

Static CUDA linkage makes the Linux CUDA artefacts substantially bigger than the CPU ones, and the Windows cuFFT DLL is ~256 MB — which is the other reason for shipping both variants.

On a machine with an NVIDIA GPU, take the CUDA variant: only that one uses the GPU.

GPU generations and the NVIDIA driver

A CUDA variant carries compiled device code for a fixed set of GPU generations, and which generations those are follows from the CUDA toolkit it was built with. The CUDA runtime is linked statically, so the only NVIDIA component the target machine has to supply is the driver — there is no CUDA-toolkit version requirement on the host.

Artefact	CUDA toolkit	GPU generations	Minimum driver
RHEL 8 packages, portable viewer .tgz, x86_64 rugnux .tgz	12.9	Volta (V100) through Blackwell: sm_70, 75, 80, 86, 89, 90, 100, 120, 121	525.60.13
RHEL 9 and Ubuntu packages, Windows installer, Windows rugnux .zip	13.x	Turing (T4) through Blackwell: the same list without sm_70	580.65.06 (Linux), R580 (Windows)
aarch64 rugnux .tgz	13.x	sm_90 (GH200) and sm_121 (DGX Spark) only	580.65.06
any cpu / nocuda variant, and everything for macOS	—	—	none

The aarch64 build is cross-compiled and verified in CI to be Arm, self-contained and to carry both GPU targets, but it is not exercised on hardware — CI has no GH200 or Spark runner.

A V100 needs the CUDA 12 build. CUDA 13 dropped offline compilation for Volta, and the PTX that a fatbin also carries only ever JIT-compiles forwards, so a CUDA 13 artefact contains nothing a V100 can execute: every kernel launch fails with no kernel image is available for execution on the device. On a V100 host take the RHEL 8 packages or the portable Linux .tgz. Nothing older than Volta is supported.

Newer GPUs never need a newer build — the highest generation in the list ships PTX as well as SASS, which the driver JIT-compiles for a GPU that came out after the release.

The minimum driver above is the floor for the whole CUDA major version, which is what applies here because the CUDA runtime is statically linked (CUDA minor version compatibility). Newer drivers are always fine; they are backward compatible. A driver from the same release as the build toolkit (575.57.08 for the CUDA 12.9 build, 610.43.02 for a CUDA 13.3 one) additionally rules out the single caveat of minor version compatibility — a call into a driver API newer than the installed driver, which fails with cudaErrorCallRequiresNewerDriver.

Windows installer

The Windows artefacts are the jfjoch_viewer installer and the separate rugnux .zip; 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; every third-party library is fetched and built by the configure.

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.

macOS

The macOS artefacts are the jfjoch_viewer disk image and the rugnux .tgz; as on Windows, the rest of Jungfraujoch, including the XDS plugin, is Linux-only. Both are CPU-only — macOS has no CUDA, so indexing uses the FFTW indexer and the whole pipeline runs on the CPU — and both are built for Apple Silicon only. They need macOS 13 (Ventura) or newer.

Intel Macs are not supported. No Intel (x86_64) code is built for macOS, and Rosetta cannot help here: it runs Intel programs on Apple Silicon, not the other way round.

jfjoch-viewer-<version>-macos-arm64.dmg holds jfjoch_viewer.app; open the image and drag the app onto the Applications shortcut next to it. The app is self-contained: the Qt frameworks are inside it, and so are the license notices (Contents/Resources), which is where a macOS app keeps them.

Both artefacts are signed with the project's Apple Developer ID and notarized by Apple, so a downloaded copy opens like any other Mac application. The disk image carries its notarization ticket; the rugnux binary in the .tgz cannot (a bare executable has nowhere to staple one), so the first run of a freshly downloaded rugnux looks the ticket up online and needs an internet connection.

The toolchain of the released macOS artefacts is Xcode (Apple Clang) and Qt 6.11 for macOS, including Qt Charts; to build the viewer yourself see jfjoch_viewer ▸ Building from source on macOS.

Licenses

Every package variant carries the project license, the third-party manifest and the verbatim license texts of the bundled dependencies, each package under a directory of its own — share/doc/jfjoch_broker, jfjoch_writer, jfjoch_viewer, jfjoch_rugnux, jfjoch_driver_dkms — so that no two packages claim the same path and they can be upgraded independently. The macOS viewer is the exception: its notices are inside the app, in jfjoch_viewer.app/Contents/Resources. See Third-party software notices.