Installation
============

Dependencies
------------

* Run-time dependencies:

  * `(C)BLAS <https://netlib.org/blas/>`_
  * `LAPACK(E) <https://netlib.org/lapack/>`_

* Code generator dependencies:

  * `Jinja <https://palletsprojects.com/projects/jinja/>`_
  * `jinja2-cli <https://github.com/mattrobenolt/jinja2-cli>`_

* Build dependencies:

  * `CMake <https://cmake.org/>`_
  * `GCC <https://gcc.gnu.org/>`_

* Test dependencies:

  * `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_
  * `Check <https://libcheck.github.io/check>`_
  * `theft <https://github.com/silentbicycle/theft>`_
  * `LCOV <https://github.com/linux-test-project/lcov>`_

* Documentation dependencies:

  * `Doxygen <https://www.doxygen.nl/index.html>`_
  * `Breathe <https://breathe.readthedocs.io/en/latest/index.html>`_
  * `Read the Docs Sphinx Theme <https://github.com/readthedocs/sphinx_rtd_theme>`_

Building (C)BLAS & LAPACK(E) from source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On Ubuntu the (C)BLAS/LAPACK(E) packages are broken. Hence, they should be built from source. We assume that the results will be installed to the ``<dist>`` directory which must be chosen accordingly by the user (e.g. ``$HOME/dist/``).

.. code-block:: sh

   wget https://github.com/Reference-LAPACK/lapack/archive/refs/tags/v3.10.1.tar.gz
   tar -xf v3.10.1.tar.gz
   cd lapack-3.10.1
   mkdir build
   cd build
   cmake -DBUILD_TESTING=Off \
         -DBUILD_SINGLE=Off \
         -DBUILD_COMPLEX=Off \
         -DBUILD_COMPLEX16=Off \
         -DLAPACKE_BUILD_SINGLE=Off \
         -DLAPACKE_BUILD_COMPLEX=Off \
         -DLAPACKE_BUILD_COMPLEX16=Off \
         -DCBLAS=On \
         -DLAPACKE=On \
         -DBUILD_SHARED_LIBS=On \
         -DCMAKE_INSTALL_PREFIX=<dist> \
         ..
   make install

.. note::
   When building static libraries the following configuration should be added (in the above command it is implied by ``BUILD_SHARED_LIBS``): ``-DCMAKE_POSITION_INDEPENDENT_CODE=On``


Configuration
-------------

``hddc2b`` uses CMake as build automation tool. For the "vanilla" configuration with a system-wide (C)BLAS/LAPACK(E) setup use the following steps:

.. code-block:: sh

   mkdir build
   cd build
   cmake ..

If (C)BLAS/LAPACK(E) has been built from source, as explained above, change the ``cmake`` configuration command as follows. Use the same ``<dist>`` directory as before:

.. code-block:: sh

   cmake -DCMAKE_PREFIX_PATH=<dist> ..

Additionally, ``hddc2b`` offers the following build-time configuration flags:

* ``ENABLE_DOC`` to build the HTML documentation from standalone reStructuredText files and in-code Doxygen comments
* ``ENABLE_TESTS`` to build unit tests and property tests.
* ``ENABLE_TEST_COVERAGE`` to enable code coverage (for the unit tests). It is advised to build this project in debug mode to produce correct coverage reports.
* ``ENABLE_PACKAGE_REGISTRY`` to add the package to CMake's `package registry <https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#package-registry>`_. As the package registry is a somewhat "intrusive" feature it must be enabled explicitly with this flag. This is useful during development time so that a rebuild suffices, instead of also installing the package.

To use any of the flags, modify the ``cmake`` configuration command as follows where ``<FLAG>`` must be replaced with the according flag:

.. code-block:: sh

   cmake -D<FLAG>=On ..

CMake presets
^^^^^^^^^^^^^

``hddc2b`` provides the following CMake `presets <https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html>`_, i.e. specialized settings that should not be included in the default configuration:

* To enable address sanitization:

  .. code-block:: sh

     cmake --preset=asan

* To enable additional warnings:

  .. code-block:: sh

     cmake --preset=add-warn

* For fast math (auto vectorization) use:

  .. code-block:: sh

     cmake --preset=math-opt


Building and installation
-------------------------

After the configuration the following command builds the project:

.. code-block:: sh

   make

If the package registry has been enabled during the configuration, already now the ``hddc2b`` package is accessible to other CMake projects via the `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ command. Otherwise, for a user- or system-wide installation execute:

.. code-block:: sh

   make install


Running tests
-------------

If the tests have been enabled during the configuration, they can now be executed via either of the following commands (the former only shows an overview whereas the latter is more verbose):

.. code-block:: sh

   make test
   test/main_test

Test coverage
^^^^^^^^^^^^^

If the test coverage has been enabled, the coverage report can be generated by executing the following command:

.. code-block:: sh

   make coverage


If the test run succeeds, the HTML coverage report can be accessed via the file ``build/coverage/index.html``.


Running example
---------------

If the tests have been enabled during the configuration, they can now be executed via either of the following commands (the former only shows an overview whereas the latter is more verbose):

.. code-block:: sh

   src/example/hddc2b_example


Building documentation
----------------------

If the documentation option has been enabled, the `make` command writes the documentation to the ``build/hddc2b_sphinx`` directory.