.. _installation-guide:

**********************
How to install neSmiK
**********************

In the following we describe the process to install the neSmiK.
Currently, we only support GNU/Linux based systems.
We will firstly introduce the requirements needed to install neSmiK, followed by a quick overview of the configuration options
and a guide on how to install neSmiK.

Requirements
=============

* The source files of nesmik e.g downloaded via a `git clone` or a release `.tar.gz` file.
* CMake >= 3.27
* C++ 17 compatible compiler

Optional dependencies
======================

Backends
---------

* `DLB <https://pm.bsc.es/gitlab/dlb/dlb>`_ to enable the DLB backends
* `Extrae <https://github.com/bsc-performance-tools/extrae>`_  to enable the Extrae Backends


Bindings
---------

* Fortran compiler to generate the neSmiK module. (*Be aware that Fortran modules are compiler specific, so you should compiler your application with the same Fortran compiler as neSmiK*)


Configuration options
=======================
Currently, as neSmiK is a rapidly changing code, please take these options as not exhaustive.
We try to keep the documentation up-to-date, but newer versions may contain more or less options.


.. list-table::
   :widths: 25 25 50
   :header-rows: 1

   * - Option
     - Default
     - Description
   * - ENABLE_EXTRAE
     - OFF
     - Enables the Extrae based backends
   * - ENABLE_DLB
     - OFF
     - Enables the DLB-TALP based backends
   * - BUILD_C_FORTRAN
     - ON
     - Builds the Fortran module and C Bindings
   * - SPLIT_FORTRAN_LIBRARY
     - OFF
     - **EXPERIMENTAL** Splits the fortran symbols into a different static library `nesmik_f`
   * - INSTALL_WITH_RPATH
     - ON
     - leaves the RUNPATH of dependencies in the shared object upon installation.
   * - WITH_MPI
     - OFF
     - Enables MPI-awareness (If you wanna use neSmiK in an MPI program, please enable)
   * - NLOHMAN_JSON_PATH
     - ""
     - Path to a previously downloaded `tar.xz` file.




Installation steps
=======================

* Get a copy of neSmiK either via a ``git clone`` or downloading a release version.
* Use the same environment and compilers you used to compiler your application with. (This is mainly important to ensure thread safety, as we use thread_local storage)
* create a build directory like inside the neSmiK source folder: ``mkdir build && cd build``
* configure the project with a command similar to, depending on your needs: ``cmake .. -DCMAKE_INSTALL_PREFIX=<yourPrefix> -DENABLE_EXTRAE=ON``
* by default cmake will generate a ``Makefile``, so as a next step run ``make && make install``
* In order to run the small test suite you can invoke ``ctest`` in the build folder.

.. note::
   If you want to install neSmiK on a cluster without internet access, please download a version of `nlohmann json <https://github.com/nlohmann/json/releases>`_ and configure with:
   ``-DNLOHMAN_JSON_PATH=<path-to-file>.tar.xz``

**Congrats!** Now you can move forward to integrate neSmiK into your :ref:`projects build system <add-nesmik>` and :ref:`start annotation code <annotate-applications>`