.. ======================================================================
..  © (or copyright) 2019-2026. Triad National Security, LLC. All rights
..  reserved.  This program was produced under U.S. Government contract
..  89233218CNA000001 for Los Alamos National Laboratory (LANL), which is
..  operated by Triad National Security, LLC for the U.S.  Department of
..  Energy/National Nuclear Security Administration. All rights in the
..  program are reserved by Triad National Security, LLC, and the
..  U.S. Department of Energy/National Nuclear Security
..  Administration. The Government is granted for itself and others acting
..  on its behalf a nonexclusive, paid-up, irrevocable worldwide license
..  in this material to reproduce, prepare derivative works, distribute
..  copies to the public, perform publicly and display publicly, and to
..  permit others to do so.
.. ======================================================================

.. _building:

.. Generative AI was used to assist with modifications to this file.

Building and Installation
==========================

``Spiner`` is self-contained and header-only. Clone it as:

.. code-block:: bash

  git clone --recursive git@github.com:lanl/spiner.git


Building from source
^^^^^^^^^^^^^^^^^^^^^

To build tests and install:

.. code-block:: bash

  cd spiner  # cd to repo root
  mkdir bin
  cd bin
  cmake -DBUILD_TESTING=ON ..
  make -j
  make test
  make install

Spiner supports a few ``cmake`` configuration options:

* ``BUILD_TESTING`` enables tests
* ``SPINER_USE_HDF5`` enables support for saving and loading tables as `hdf5`_.
* ``SPINER_USE_PORTABLE_NQT`` uses the portable NQT implementation for fast
  nonuniform grids. The default uses the faster aliased binary64 implementation.
* ``SPINER_HDF5_INSTALL_DIR`` tells the build system where `hdf5`_ is located.
* ``SPINER_USE_KOKKOS`` enables `Kokkos`_ as a backend
* ``SPINER_USE_KOKKOS_SRC`` tells the build system to build `Kokkos`_ from source, and where the source directory is located. Note that if you use this option, you cannot install Spiner, only build the tests.
* ``SPINER_KOKKOS_INSTALL_DIR`` tells the build system where to find pre-compiled `Kokkos`_
* ``SPINER_USE_CUDA`` enables the Kokkos cuda backend
* ``CMAKE_INSTALL_PREFIX`` sets the install location
* ``CMAKE_BUILD_TYPE`` sets the build type
* ``SPINER_FORCE_INTERNAL_PORTS`` forces use of a `ports-of-call`_ submodule rather than a system install

.. _`hdf5`: https://www.hdfgroup.org/solutions/hdf5

.. _`Kokkos`: https://github.com/kokkos/kokkos

.. _`ports-of-call`: https://lanl.github.io/ports-of-call/main/index.html

HDF5 is searched for and configured via the usual `cmake`_ machinery.

.. _`cmake`: https://cmake.org/

A ``format_spiner`` target is also added if ``clang-format`` is found, so
that ``make format_spiner`` will auto-format the repository.

Testing is enabled via `Catch2`_, which is automatically downloaded
during the cmake configure phase if needed.

.. _`Catch2`: https://github.com/catchorg/Catch2

Spack
^^^^^^

Spiner is available through `Spack`_. If you have spack installed, simply call:

.. code-block:: bash

  spack install spiner

Including Spiner in your Project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Spiner can be included into a cmake project, either in-tree as a
submodule or after installation via ``find_package``.
The cmake system provides the ``spiner::spiner`` cmake target.