.. _installation:

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

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

`Python <https://www.python.org/downloads/>`_, `ROOT <https://root.cern/install/>`_, and `Ph2 ACF <https://gitlab.cern.ch/cms_tk_ph2/Ph2_ACF>`_ are dependencies of ``dirigent`` but do not come packaged with it. Right now, we assume that test centres wishing to use ``dirigent`` already have all these dependencies installed, and are familiar with them. As more institutes develop their testing facilities, this may be revised and dependencies such as Ph2 ACF may come packaged. Below some notes are provided for correct configuration of dependencies. For additional help, Ph2 ACF provides very useful `instructions <https://ph2acf.docs.cern.ch/general/>`_ for a lot of the process.

**Python**

Python 3.9 (minimum) is required for the installation of ``dirigent``. Earlier versions cannot be substituted as modern syntax and language features are used throughout the project.
 
**ROOT**

For the installation of ``ROOT``, it is recommended to follow the instructions on the official website of the `ROOT project <https://root.cern/install/>`_. This is a bit more work than the installation with the package manager, but it is generally easier for usage with environments than the installation through the package manager. For proper behaviour, ``ROOT`` should be sourced prior to running ``dirigent``. Most accomplish this by sourcing ``thisroot.sh`` in their ``.bashrc``. 

On AlmaLinux 9, the following instructions might give some help on what the dependencies are. This is however not an official instruction and it might depend on the specific setup. Therefore, please refer also to the official website::
    
    sudo dnf install epel-release git make cmake gcc-c++ gcc binutils \
    libX11-devel libXpm-devel libXft-devel libXext-devel python openssl-devel \
    xrootd-client-devel xrootd-libs-devel xxhash xxhash-libs tbb-devel python3-numpy
    wget https://root.cern/download/root_v6.32.02.Linux-almalinux9.4-x86_64-gcc11.4.tar.gz
    tar -xzvf root_v6.32.02.Linux-almalinux9.4-x86_64-gcc11.4.tar.gz
    source root/bin/thisroot.sh # also available: thisroot.{csh,fish,bat,ps1}

On AlmaLinux 9, ``ROOT`` can also be installed through the package manager. However, this installation can cause difficulties with python environments. For this, use the following commands::

    dnf install -y epel-release
    dnf config-manager --set-enabled crb
    dnf install -y root python3-root git

From these commands, it is likely, that only ``python3-root`` has to be installed. The rest should be already there, if Ph2 ACF was installed before.

On CentOS 7, both Python 3.9 and ``ROOT`` must be built from source in that order. On CentOS Stream 8, Python 3.9 can be installed via the ``python39 python39-devel python39-numpy`` packages prior to compiling ``ROOT``. ``ROOT`` should be compiled against C++14 to ensure compatibility with Ph2 ACF. 

**Ph2 ACF**

Ph2 ACF must be cloned from the `TK_Ph2 gitlab repo <https://gitlab.cern.ch/cms_tk_ph2/Ph2_ACF>`_ (or for development versions, the `Inner Tracker Upstream Repo <https://gitlab.cern.ch/cmsinnertracker/Ph2_ACF>`_) and compiled/installed using the instructions provided there. It is recommended to use the most recent tagged version of Ph2 ACF (``v6-03`` at the time of writing), but since Ph2 ACF is constantly under development, I also recommend maintaining the ``master`` branch of the development version on lab PCs just in case. Also, Ph2 ACF must be compiled against the ``ROOT`` installation with Python 3.9 bindings (see previous section).

The Ph2 ACF handler requires either ``xterm`` or a compatible version of ``tmux`` (newer than version 1.8). ``xterm`` is to be preferred usually due to a better overview during the scan and better testing. ``tmux`` is currently not fully supported. On AlmaLinux for example, ``xterm`` can simply be installed through the package manager::

    dnf install -y xterm

Clone the repository
--------------------

Navigate to your software folder and create a folder for ``dirigent``::

    mkdir dirigent && cd dirigent

Next, clone the repository into a folder named after the version you want, enter that directory, and checkout the correct version::

    git clone https://gitlab.cern.ch/cms_tk_ph2/dirigent.git dirigent-3.1.0 
    cd dirigent-3.1.0
    git checkout -b 3.1.0 3.1.0

Then initialise all the submodules (dependencies)::

    git submodule update --init --recursive

This command will clone the submodules ``inner-tracker-tests``, ``icicle``, ``felis``, and ``resthub-dev``. ``inner-tracker-tests`` is a repository containing standardised settings for Ph2 ACF scans. ``felis`` is the interface used for uploading data to the `Panthera <https://panthera.fit.edu>`_ database. ``resthub-dev`` is the API used to provide access to the module database.``icicle`` is particularly important as it is used for controlling instruments. 

Python environment
------------------

It is recommended to install ``dirigent`` in a separate python environment. One may use Python virtual environments or anaconda environments for this purpose - it makes litte practical difference. An example of how to set up a python virtual environment for this purpose is below::
    
    python3 -m venv .venv
    source .venv/bin/activate

**Note:** If ``ROOT`` was installed via the package manager, the environment has to be created with the flag ``--system-site-packages``. For flexibility reasons, it is however recommended to install ``ROOT`` directly from the binary.

Then inside the python environment, make sure ``pip`` is upgraded::
    
    pip install --upgrade pip

Then finally::

    pip install .

Or for a developer installation of these packages (i.e. modifications of source files will affect the installation)::

    pip install -e .

Now that installation of ``dirigent`` has been performed in the python environment, on computer reboot, simply enabling that python environment will automatically load ``dirigent`` too::

    source /path/to/software/dirigent/dirigent-3.1.0/.venv/bin/activate

Set up Ph2 ACF
--------------

The activation of the python environment can cause the environment variables set by Ph2 ACF to be reset. Therefore, the environment should be loaded before Ph2 ACF is sourced. Once the ``dirigent`` python virtual environment has been activated, you must ``source`` the ``setup.sh`` file for the specific version of Ph2 ACF you want to use::

    cd path/to/Ph2_ACF/install/
    source setup.sh 

**Note:** Since Ph2 ACF uses absolute paths in their ``setup.sh``, you must ``cd`` to the install directory first.

``dirigent`` should now be ready to run. You can check with::

    dirigent --help