.. _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 **CMakeList.txt** file present at the root of the project contains the *entry point* for the compilation. It also 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
==============================

Compilation (using ninja) in "release" can be done using the folowing commands:
For more information about option of cmake please refer to the cmake documentaion [#cmakedoc]_:

.. code-block::

    mkdir cmake_build
    cd cmake_build
    cmake -DPython_FIND_STRATEGY=LOCATION -DCMAKE_BUILD_TYPE=Release --fresh ..

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

.. code-block::
    cmake -G Ninja -DPython_FIND_STRATEGY=LOCATION -DCMAKE_BUILD_TYPE=Release --fresh ..


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

Notes for maintaining the build system
======================================

As the build system is hierarchical, it is necessary to explicity 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/