=========================
Installation Instructions
=========================

By default, the SPS Test Suite is installed to :code:`/opt/sps` location.  Installation can only be done by a user with :code:`sudo` privileges.
First clone :code:`ska-low-sps-testsuite` into your local area, i.e your home directory.

.. code-block::

    git clone https://gitlab.com/ska-telescope/ska-low-sps-testsuite.git  --recurse-submodules
    cd ska-low-sps-testsuite
    git checkout main
    git pull

Install SPS software onto your machine by running the deploy script.

.. code-block::

    pushd scripts/install
    ./deploy.sh

A custom install path can be specified as below. We still recommend installing to the :code:`/opt` location however.

.. code-block::

    ./deploy.sh -a /opt/my-sps-testing

This script should _not_ be executed with :code:`sudo`, however the user executing it must have :code:`sudo` privileges. Only the user running this script will have privileges to install additional Python packages in the virtual environment.

This script uses :code:`/usr/bin/python3` as default Python interpreter. To use another interpreter, for instance Python 3.11, instead of the default :code:`python3`, run the following before deploying to set the :code:`SPS_PYTHON_BIN` environment variable.

.. code-block::

    export SPS_PYTHON_BIN=/usr/bin/python3.11

After running the deploy script the Python virtual environment can be sourced as below:

.. code-block::

    source /opt/sps/python/bin/activate

**NOTE:** This path includes the default install location so if using a custom install path as above the command will be something like:

.. code-block::

    source /opt/my-sps-testsing/python/bin/activate

Alternatively, the deployment sets the following BASH alias for activating the virtual environment which can be used from any location:

.. code-block::

    sps_python

Using the command line option :code:`-c` will delete the following directories before installing :code:`ska-low-sps-testsuite`.

.. code-block::

    /opt/sps/python
    src/build
    src/dist
    scripts/install/third_party

To allow development of the testsuite's dependencies, :code:`SKA-Low SPS TPM API`, :code:`SKA-Low MCCS DAQ` and :code:`iTPM Bios` branches
can be specified with the :code:`-b`, :code:`-D` and :code:`-t` arguments, all of which default to :code:`main`. For example:

.. code-block::

    cd ska-low-sps-testsuite
    git fetch
    git switch feature-branch-sps-testsuite
    git pull
    ./deploy.sh -b feature-branch-tpm-api -D feature-branch-mccs-daq -c

Below are all command line arguments supported by the deploy script:

.. code-block::

    Arguments:
    -C             Correlator will be compiled, installing CUDA and xGPU in the process (off by default)
                NOTE: Automated install of CUDA and xGPU not supported yet
    -p             Activate SPS virtualenv in .bashrc (off by default)
    -a <install path> specifies location of installed SPS Testsuite (default /opt/sps), must be absolute
    -v <venv path> specifies location of 'python' virtualenv folder (default /opt/sps)
    -b <tpm_api_branch> specifies TPM API branch to be installed
    -D <DAQ branch> specifies MCCS DAQ branch to be installed
    -d             specifies the number of FPGA firmware releases downloaded from the SKAO CAR
    -L <DAQ core branch (aavs-daq) specifies DAQ core (aavs-daq) branch to be installed
    -t <itpm_bios_branch> specifies itpm-bios branch to be installed
    -c             clean build directories and installed python virtual environment
    -h             Print this message