CLAUDE.md: build options, notices install path, refine mode and library notes match the tree

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK
This commit is contained in:
leonarski_fandClaude Opus 5.5 committed 2026-11-10 13:41:00 +01:00
1 parent 43e961a147
commit fcc86d5038
1 file changed
+32 -18
+32 -18
View File
@@ -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_<broker|writer|viewer|rugnux|driver_dkms>`
(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