From fcc86d503856b14f2344836f4732f3dac8588eb2 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Tue, 10 Nov 2026 13:41:00 +0100 Subject: [PATCH] CLAUDE.md: build options, notices install path, refine mode and library notes match the tree Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 20a2a96e8..d90043cb0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,7 @@ changing CLI behaviour, update the parser, that page and, for a basic option, th ## Build Out-of-source CMake build, C++20, heavy use of `FetchContent` (spdlog, zstd, HDF5, -slsDetectorPackage, Catch2, cpp-httplib, libzmq, libtiff, FFTW, Ceres, zlib-ng and Eigen are +slsDetectorPackage, Catch2, cpp-httplib, libzmq, libtiff, FFTW, Ceres (with abseil), zlib-ng and Eigen are downloaded and statically linked — the **first configure needs network access** and is slow; the fast-feedback indexer behind FFBIDX is vendored in `image_analysis/indexing/fast-feedback-indexer/`). **No library has to come from the host**: `zlib-devel`/`eigen3-devel` are no longer needed. @@ -37,18 +37,23 @@ make -j$(nproc) jfjoch_broker # the main service; build other targets by na Key CMake options: - `JFJOCH_USE_CUDA` (default ON) — GPU path. Needs CUDA ≥ 12.8 (older is warned about and - ignored). Provides the `ffbidx` and `fft` GPU indexers; without it only the CPU `fftw` indexer is - available. FFTW is fetched and `JFJOCH_USE_FFTW` defined unconditionally, so `fftw` is always - there. CUDA absence is not a build error — nvcc is looked for on `PATH`, `CUDA_PATH` and - `/usr/local/cuda`. -- `JFJOCH_WRITER_ONLY` (default OFF) — builds only the HDF5 writer; skips broker, FPGA, + ignored). Provides the `ffbidx` and `fft` GPU indexers; without it the indexers are the CPU `fftw` + and a CPU port of the fast-feedback indexer (`FFBIDXIndexerCPU`, always built). FFTW is fetched and + `JFJOCH_USE_FFTW` defined unconditionally, so `fftw` is always there. CUDA absence is not a build + error — nvcc is looked for on `PATH`, `CUDA_PATH`, `CUDA_HOME`, `CUDA_ROOT`, `/usr/local/cuda` and + `/opt/cuda`. +- `JFJOCH_WRITER_ONLY` (default OFF) — builds only the HDF5 writer (with the detector control, + image puller, reader, preview, `gemmi_gph` and XDS-plugin libraries it needs); skips broker, FPGA, receiver, analysis, tests, frontend. - `JFJOCH_VIEWER_BUILD` (default OFF) — builds the Qt6 `jfjoch_viewer` desktop app in addition to the server stack. - `JFJOCH_VIEWER_ONLY` (default OFF on Linux, **forced ON on Windows/macOS**) — builds only `jfjoch_viewer`, `rugnux`, the XDS plugin (Linux only) and the libraries they link; skips - receiver, FPGA, detector control, tests and the frontend. `cpack` then writes one archive per - program (Linux: three `.tar.gz`; macOS: the viewer `.dmg` plus the rugnux `.tar.gz`). + receiver, FPGA, detector control, `jfjoch_test` and the frontend (the broker API library, `tools/` + and `jfjoch_portable_test` are still built). `cpack` then writes one archive per program (Linux: + three `.tar.gz`; macOS: the viewer `.dmg` plus the rugnux `.tar.gz`). +- `JFJOCH_RUGNUX_ONLY` (default OFF) — builds only `rugnux` and the libraries it links (no Qt); it + takes precedence over `JFJOCH_VIEWER_ONLY`, whose Windows/macOS forcing applies only when this is off. - `SLS9` (default OFF) — build against slsDetectorPackage 9.2.0 instead of 8.0.2. - `JFJOCH_INSTALL_DRIVER_SOURCE` (default OFF) — install the PCIe driver source for DKMS/RPM. @@ -83,6 +88,8 @@ built automatically — `make install` only copies whatever already sits in `fro ## Test Tests use **Catch2** and are collected into a single binary `tests/jfjoch_test`. +`jfjoch_portable_test` holds the `[portable]` subset; it is built in every configuration and is what +the macOS/Windows CI jobs run. ``` make -j$(nproc) jfjoch_test @@ -261,9 +268,10 @@ Taking someone's source *and* following their paper incurs both. Do both. add a row to the root `THIRD_PARTY_NOTICES.md` — component, path, copyright, SPDX id, link to the licence text. Both are required; a licence text nobody lists is not attribution. `docs/THIRD_PARTY_NOTICES.md` is **generated** from the root file by `update_version.sh` — never -hand-edit it. `CMakeLists.txt` installs `LICENSE`, `THIRD_PARTY_NOTICES.md` and all of `licenses/` -into `share/doc/jfjoch` for every package component, so nothing further is needed to reach the built -product. +hand-edit it. `CMakeLists.txt` installs `LICENSE`, `THIRD_PARTY_NOTICES.md`, `docs/ACKNOWLEDGEMENT.md` +and all of `licenses/` into a per-component `share/doc/jfjoch_` +(no component writes a plain `share/doc/jfjoch`; the macOS viewer carries them inside the `.app`), so +nothing further is needed to reach the built product. **The XDS plugin ships its own notices** (`xds-plugin/THIRD_PARTY_NOTICES.md` + `JFJOCH_XDS_PLUGIN_LICENSES` in its CMakeLists); update both when its link line changes. @@ -367,17 +375,21 @@ generated API model and internal types. merging writes `.mtz`/`.cif`/`.hkl` and skips the bulky `_process.h5` unless `--write-process-h5`, while `--no-merge` writes only `_process.h5`. `--mode` picks what a run does: `mx` (the full pipeline, the default), `azint` (azimuthal integration only), `scale` (re-scale/merge the - already-integrated reflections in a `_process.h5`) or `calibration` (detector geometry from a - calibrant's powder rings, written as a `.poni`; `--calibrant`, `--calibration rings|spots`). + already-integrated reflections in a `_process.h5`), `calibration` (detector geometry from a + calibrant's powder rings, written as a `.poni`; `--calibrant`, `--calibration rings|spots`) or + `refine` (refine `--model` against merged structure factors from an MTZ/SF-mmCIF; processes no + images). (rugnux = the data-processing half of the system; see `docs/NAMING.md`.) **`image_analysis/` pipeline** (subdirs): `spot_finding`, `indexing` (`ffbidx`/`fft` GPU, `fftw` CPU), `lattice_search`, `geom_refinement`, `bragg_prediction`, `bragg_integration`, -`image_preprocessing`, `azint`, `roi`, `scale_merge`, plus `rotation_indexer/` and -`dark_mask_analysis/` and `beam_stop/` compiled straight into `JFJochImageAnalysis` +`image_preprocessing`, `azint`, `roi`, `scale_merge`, `structure_refinement` (model refinement and MR), +plus `rotation_indexer/`, `dark_mask_analysis/`, `hot_pixels/` and `beam_stop/` compiled straight into +`JFJochImageAnalysis` (`beam_stop/ShadowFinder` is built and runs by default in `rugnux` — it is no longer the unbuilt prototype an older version of this file described). Least-squares refinement uses **Ceres** (fetched in -`image_analysis/CMakeLists.txt`, built with miniglog, no MKL, no Ceres-CUDA, CXX_THREADS). +`image_analysis/CMakeLists.txt` together with the abseil it logs through, no MKL, no Ceres-CUDA, +CXX_THREADS). The indexer is chosen with `-X` (`Auto|FFT|cuFFT|FFTW|FFBIDX|None`, default `Auto`, which resolves to a GPU indexer when one is present and `fftw` otherwise): `ffbidx` wants a known cell (`-C`) and suits sparse serial stills; `fft` indexes de novo and suits strong rotation data - it is the algorithm, run @@ -394,7 +406,7 @@ the host-side driver, `pcie_driver/` is the kernel module. The HLS algorithms ar (EIGER). **`jungfrau/`**: JUNGFRAU ADU→energy gain/pedestal calibration. **Other libs:** `common/` (geometry, diffraction experiment, image buffer, CUDA wrappers — the -shared core, linked nearly everywhere), `compression/` (vendored bitshuffle + LZ4 + zstd; the +shared core, linked nearly everywhere), `compression/` (vendored bitshuffle, bitshuffle_hperf and LZ4; zstd is fetched; the algorithms are `BSHUF_LZ4`, `BSHUF_ZSTD`, `BSHUF_ZSTD_RLE`, `BSHUF_ZSTD_RLE_HUFF`), `frame_serialize/` (CBOR stream codec), `reader/` (HDF5 dataset read-back), `gemmi_gph/` (vendored GEMMI for MTZ/XDS_ASCII I/O), `xds-plugin/` (XDS HDF5 read plugin). @@ -439,7 +451,9 @@ Qt is supplied externally as before. `broker/jfjoch_api.yaml` defines the entire REST API **and the shared data schemas**. From it, `update_version.sh` regenerates three clients — **do not hand-edit generated code**: - C++ server model → `broker/gen/` (cpp-pistache-server generator; compiled as `JFJochAPI`). -- Python client → `python-client/` (and `gen_python_client.sh`, published as PyPI `jfjoch-client`). +- Python client → `python-client/` (and `gen_python_client.sh`, published as PyPI `jfjoch-client`); + the directory is gitignored and regenerated, and `update_version.sh` itself `git rm`s and `git add`s + the generated trees (`broker/gen/model`, `frontend/src/client`, `docs/python_client`). - TypeScript frontend client → `frontend/src/client/` (hey-api `openapi-ts`, `npm run openapi`). When you change `jfjoch_api.yaml`, regenerate the relevant client(s); for a version bump write the new version into `VERSION` and run