****************
CMake Options
****************

This page lists the user-facing CMake cache options supported by kotekan. Pass options to CMake via
``-D<OPTION>=<VALUE>``, for example:

.. code:: bash

   cmake -S . -B build -DUSE_CUDA=ON -DWERROR=ON

Most feature switches are tri-state and accept ``AUTO`` (probe dependencies and enable when
available), ``ON`` (require the feature and fail if the dependency is missing), or ``OFF`` (skip the
feature entirely). The default value for each option is shown in parentheses below.


General
========

- ``CMAKE_BUILD_TYPE`` (``Test``): Choose ``Debug`` for full symbols, ``Release`` for an optimised build, or
  ``Test`` for asserts/logging without debug symbols.
- ``ARCH`` (``native``): Override the architecture passed to ``-march``/``-mtune`` if you need to target
  a different CPU.
- ``CMAKE_LINK_WHAT_YOU_USE`` (``OFF``): Request link-time diagnostics for unused link dependencies.
  Useful when hunting for missing ``target_link_libraries`` entries, but slows the link step.


GPU Backends
=============

- ``USE_CUDA`` (``AUTO``): Enable the CUDA GPU backend when ``nvcc`` and the CUDA toolkit are discoverable.
  Adds ``-DWITH_CUDA`` and builds CUDA stages.
- ``USE_OPENCL`` (``OFF``): Enable the OpenCL backend. Set to ``AUTO``/``ON`` when OpenCL headers and
  libraries are installed; the build installs kernel files to ``/var/lib/kotekan/opencl``.
- ``USE_HIP`` (``OFF``): Enable the HIP backend when the HIP toolchain is available.


I/O and File Formats
=====================

- ``USE_HDF5`` (``AUTO``): Build HDF5 output stages when HDF5, HighFive, and the runtime plugin directory
  are all detected. Populates ``KOTEKAN_HDF5_PLUGIN_DIR`` for runtime configuration.
- ``USE_ASDF`` (``AUTO``): Build ASDF output stages when ``asdf-cxx`` is found; defines ``-DWITH_ASDF_CXX``.
- ``USE_GDAL`` (``AUTO``): Build GDAL output stages when GDAL headers/libs are available; defines
  ``-DWITH_GDAL``.


Math Libraries
===============

- ``USE_FFTW`` (``AUTO``): Enable the FFTW F-engine when FFTW is installed; defines ``-DWITH_FFTW``.
- ``USE_LAPACK_BLAZE`` (``AUTO``): Enable LAPACKE/OpenBLAS plus Blaze-based linear algebra stages when
  both dependencies are present. Adds the necessary compile definitions for Blaze/OpenBLAS.


Core & Runtime Features
========================

- ``USE_AIRSPY`` (``AUTO``): Build the Airspy capture stages when ``libairspy`` is present; defines
  ``-DWITH_AIRSPY``.
- ``USE_JULIA`` (``AUTO``): Enable Julia-backed components when the Julia executable and C API are
  available.
- ``USE_OMP`` (``AUTO``): Append OpenMP compile/link flags when OpenMP is supported. Automatically
  switches to ``OFF`` if the compiler lacks OpenMP support.
- ``USE_NUMA`` (``ON``): Link ``libnuma`` and enable NUMA-aware buffer management. Required for DPDK.
- ``USE_DPDK`` (``AUTO``): Enable DPDK features when ``libdpdk >= 19.11`` is discoverable via
  ``pkg-config``. This option is forced ``OFF`` when ``WITH_BOOST_TESTS`` is ``ON`` to avoid linker
  conflicts.
- ``USE_OPENSSL`` (``AUTO``): Link OpenSSL (libcrypto) for hashing support in the core. Combine with
  ``-DOPENSSL_ROOT_DIR=<path>`` for non-standard installations.
- ``NO_MEMLOCK`` (``OFF``): Define ``WITH_NO_MEMLOCK`` to skip memory locking and related policy calls,
  which can be necessary in containerised or restricted environments.


Build & Tooling
================

- ``WERROR`` (``ON``): Treat compiler warnings as errors for C/C++ sources. CUDA compilations still emit
  warnings but do not fail when ``WERROR`` is ``OFF`` thanks to ``--warn-no-error``.
- ``CCACHE`` (``OFF``): Use ``ccache`` as the compiler launcher when it is installed.
- ``COMPILE_DOCS`` (``OFF``): Build the Sphinx + Doxygen documentation tree. Even when enabled, the
  documentation is only generated when the ``docs`` target is built explicitly.
- ``IWYU`` (``OFF``): Run include-what-you-use on C/C++ compilations. Requires the ``include-what-you-use``
  executable and the mapping file (``iwyu.kotekan.imp``).
- ``SUPERDEBUG`` (``OFF``): Force ``-O0`` and keep frame pointers in Debug/Test builds for easier debugging
  and coverage analysis.
- ``SANITIZE`` (``OFF``): Enable the Clang/LLVM AddressSanitizer toolchain flags for Debug/Test builds.
- ``WITH_TESTS`` (``OFF``): Build and link the helper stages in ``lib/testing`` into the kotekan binary.
- ``WITH_BOOST_TESTS`` (``OFF``): Build the Boost.Test unit tests under ``tests/boost`` (requires
  ``pytest-cpp``).


Common Paths and Overrides
===========================

- ``OPENSSL_ROOT_DIR``: Point to a non-standard OpenSSL install to help ``USE_OPENSSL`` locate the
  libraries.
- ``BLAZE_PATH``: Provide a custom include path for Blaze headers.
- ``CUDAToolkit_ROOT``: Override the search path for the CUDA toolkit when required.
- ``HDF5_PLUGIN_DIR``: Set the first path to look for HDF5 plugins (libh5blosc.so, etc). If not set will
  check the ``HDF5_PLUGIN_PATH`` environment variable, then the active python package, then other common
  locations.


Notes
======

- Auto-detection: When an option is ``AUTO`` and its dependency is missing, kotekan prints a warning and
  continues without the feature. Setting the option to ``ON`` causes configuration to fail instead.
- Summary output: At the end of configuration, CMake prints a colourised feature summary showing each
  feature’s status and the corresponding toggle flag.
- Developer reminder: When adding a new CMake option, also update this page, the configure summary
  (``cmake/Summary.cmake``), and the version metadata template (``lib/version/version.c.in``).