Compiling COBALT
=================

To install COBALT, several dependencies need to be installed. The most convenient method is by using the **Spack** package manager.  

If provided, an existing Spack environment can be used. In this case, one can immediately proceed to the compilation of COBALT. If not environment is provided, or the CPU architecture
of the provided spack environment does not match the target CPU, an new spack environment shall be created. Please refer to the 

.. rubric:: Quick Links  

- `Automatic Spack Installation <#automatic-installation>`_
- `Manual Spack Installation <#manual-installation>`_
- `Compiling COBALT <#compiling-cobalt>`_
- `Common issues <#common-issues>`_

Automatic Spack Installation
----------------------
.. _automatic_installation:

.. note::

    These instructions were sourced from the `cobalt-installation <https://git.astron.nl/RD/cobalt-installation>`_ repository.

1. First, clone the repository:

.. code-block:: bash

    git clone https://git.astron.nl/RD/cobalt-installation

2. Ensure a :code:`cobalt` user exist on all target machines. If not, create one:

.. code-block:: bash

    useradd cobalt

3. Create the :code:`/data/cobalt` directory on each target machine:

.. code-block:: bash

    mkdir -p /data/cobalt
    chown cobalt:cobalt /data/cobalt

4. Then, run the installation script:

.. code-block:: bash

    cd cobalt-installation/infra
    chmod +x install_cobalt.sh
    ./install_cobalt.sh

The script will create a new spack environment.


Manual Spack Installation
-------------------

.. _manual_installation:

In this section, instructions are provided to prepare the COBALT spack environment.

Creating a New Spack Environment  
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If no compatible spack environment is available or if your system's CPU architecture differs from the provided environment, you will need to create a new one.
We assume that spack is already installed. Instructions to install spack can be found `here <https://spack.io/>`_.

1. First, enable spack:  

.. code-block:: bash  

    source /var/scratch/root/spack/v0.22.1/share/spack/setup-env.sh  

2. Then, create a new spack environment using the provided :code:`environment.yaml` file in the root of the repository:  

.. code-block:: bash  

    spack env create lofar 
    spack env activate lofar
    cp environment.yaml $SPACK_ENV/spack.yaml

3. Finally, install the environment. Running :code:`spack install` may take up to
a couple hours and builds and installs roughly 100 packages.

.. code-block:: bash

    spack install


4. Create module files by copying the :code:`modules.yaml` file in the root directory:

.. code-block:: bash

    cp modules.yaml ~/.spack/modules.yaml
    spack module tcl refresh -y

5. Provided that your shell is set-up properly, or you sourced :code:`/etc/profile.d/modules.sh`, you can now add the module path, e.g.:

.. code-block:: bash

    module use /opt/spack/0.22.1/share/spack/modules/linux-debian12-zen2/gcc/12.2.0

6. Running :code:`module avail` should list all packages installed through Spack. Note that one different systems the architecture, in our case 
`zen2`, the output may be different.

Compiling COBALT
----------------

1. First, activate the spack environment by running:

.. code-block:: bash

    module load spack/12.2.0 # COBALT is tested with spack 12.2.0, but other versions may work as well

.. note::

    Check if the packages are loaded by running :code:`module list`.

2. Then, load the required packages:

.. code-block:: bash

    module load dal2

.. code-block:: bash

    source /var/scratch/root/spack/v0.22.1/share/spack/setup-env.sh
    module load binutils cuda log4cplus postgresql openblas diffutils dal2 \
                fftw openmpi boost pqxx casacore python numactl unittest-cpp \
                hdf5 py-lxml gcc gmake cmake openmpi

3. Now, clone COBALT and compile it from source:

.. code-block:: bash

    git clone https://git.astron.nl/cobalt/cobalt
    cd cobalt
    cmake -Bbuild/gnucxx11_optarch -DUSE_MPI=ON .
    cd build/gnucxx11_optarch

.. warning::

    If you want to create a debug build, you can set the directory prefix accordingly. For example:

    .. code-block:: bash

        cmake -Bbuild/gnucxx11_debug -DUSE_MPI=ON .

    Furthermore, ensure that the `USE_MPI` directive is set to `ON`. This can be done using the following command: :code:`ccmake .`

5. Run make:

.. code-block:: bash

    make -j

6. Finally, install the compiled binaries:

.. code-block:: bash

    make install


Common Issues
-------------
.. _common-issues:

Compiling COBALT on DAS-6
^^^^^^^^^^^^^^^^^^^^^^^^^

To compile COBALT on DAS-6, the following script can be used to activate the required modules:

.. code-block:: bash

    . /var/scratch/root/cobalt-installation/infra/activate_cobalt_das6.sh

Please note that this script assume the AMD zen2 architecture. If you are using a different architecture, please modify the script to point to the right spack environment.

.. note::

    To make the script available on every login, add the following line to your :code:`.bashrc` file:

    .. code-block:: bash

        # ...
        source /var/scratch/root/cobalt-installation/infra/activate_cobalt_das6.sh