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:
1 parent
43e961a147
commit
fcc86d5038
1 file changed
+32
-18
@@ -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
|
||||
|
||||
Reference in new issue
Block a user