.. _cmake:

=====
CMake
=====

Architecture of the Build System
================================

The build system aims to be subdivided to locally generate files.
It is intended to build as much as possible out of source (when possible).
A ``cmake/`` folder contains all the **tools/macro/functions** to lighter the ``CMakeLists.txt``.

* The **CMakeLists.txt** file present at the root superbuild folder of the project contains the *entry point* for the compilation. Prior to configuring and building Muscat's project, if Kokkos not found it builds Kokkos dependencies with the desired backend (OpenMP, CUDA, HIP, *etc.*) and auto-detects the device architecture.
* The **CMakeLists.txt** file present at the root is the real *entry point* of Muscat's project. It holds all the available options for the compilation.
* The ``cmake/Requirements.cmake`` is being the first imported and ensure that all the **softwares/dependencies** required for Muscat compilation are present on the sytem. It however comes after the options to allow tuning of what are the requirements accordingly.
* There is a ``CMakeLists.txt`` in each source directories (*cpp_src*, *src*) as well as in the *cpp_generators* folder.

CMake Compilation
=================

By default, the project is configured and built with Kokkos::OpenMP backend and to add CUDA support add the CMake argument *-DKokkos_ENABLE_CUDA=ON*. For more Kokkos CMake keywords, please refer to [#kokkosconfig]_.
Compilation (using ninja) in "release" with default Kokkos::OpenMP backend can be done using the following commands:
For more information about option of cmake please refer to the cmake documentation [#cmakedoc]_:

.. code-block::

    mkdir cmake_build
    cd cmake_build
    cmake -DCMAKE_BUILD_TYPE=Release --fresh ../superbuild/

We recommend to use ``Ninja`` build system if available on your system by replacing the last command by:

.. code-block::

    cmake -G Ninja  -DCMAKE_BUILD_TYPE=Release --fresh ../superbuild/


To build the project:

.. code-block::

    cmake --build .

To install (this is **experimental** not supported for all OS/python version/distributions)

.. code-block::

    cmake --install .

.. _run_tests:

To run all the tests

.. code-block::

    ctest --test-dir Muscat-build/

You will find more explanations on tests in :ref:`testing`.

Notes for Maintaining the Build System
======================================

As the build system is hierarchical, it is necessary to explicitly specify when a variable will be reused in a *parent scope* by writing:

.. code-block:: cmake

    set(MyVar ${MyVar} PARENT_SCOPE) #Export it outside of the file

.. rubric:: Footnotes
.. [#cmakedoc] https://cmake.org/documentation/
.. [#kokkosconfig] https://kokkos.org/kokkos-core-wiki/get-started/configuration-guide.html