.. SPDX-FileCopyrightText: 2022 Cosylab d.d.
..
.. SPDX-License-Identifier: MIT

##################
Installation Guide
##################

This chapter describes how to compile the ADS device support EPICS modules.

Dependencies
============
Pre-requisite software:

* **EPICS base**: at least R3.15
* **asynDriver**: at least R4-39
* **Boost**: Boost C++ libraries
* **gcc**: GNU Compiler Collection
* **g++**: GCC for C++
* **autoparamDriver**: at least v2.0.0, see :ref:`instructions below <autoparam-install>`

ADS device support software includes :ref:`beckhoff-adslib-ref` as a submodule.

.. _autoparam-install:

AutoparamDriver
========================
The following is a quickstart for compiling Autoparam on Linux. Refer to Autoparam README for more information.

Download the latest stable version from `Github <https://www.github.com/cosylab/autoparamDriver>`__.

The provided ``configure/RELEASE`` file assumes that the module's parent directory contains a *RELEASE.local* file with the required module paths (i.e. *ASYN* and *EPICS_BASE*):

.. code-block:: makefile

  # RELEASE - Location of external support modules
  #
  # Required external module paths:
  # ASYN - asynDriver
  # EPICS_BASE - EPICS base
  
  # External modules are expected to be defined in a RELEASE.local file located
  # in $(TOP)'s parent directory.
  -include $(TOP)/../RELEASE.local

Either edit ``configure/RELEASE``, or your ``$(TOP)/../RELEASE.local`` file to set the correct path to the *EPICS_BASE* and *ASYN* modules:

.. code-block:: makefile
   :emphasize-lines: 4,10

   # RELEASE - Location of external support modules
   # ... <removed for brevity>
   ## EPICS Modules
   ASYN=/opt/epics/modules/asyn
   
   # If using the sequencer, point SNCSEQ at its top directory:
   #SNCSEQ = $(MODULES)/seq-ver
   
   # EPICS_BASE should appear last so earlier modules can override stuff:
   EPICS_BASE = /opt/epics/base
   
   # Set RULES here if you want to use build rules from somewhere
   # other than EPICS_BASE:
   # ... <removed for brevity>

Set the target installation location in ``configure/CONFIG_SITE`` (optional step):

.. code-block:: makefile
   :emphasize-lines: 5

   # CONFIG_SITE
   # ... <removed for brevity>
   # To install files into a location other than $(TOP) define
   # INSTALL_LOCATION here.
   INSTALL_LOCATION=/opt/epics/modules/autoparamDriver

Finally, compile the module:

.. code-block:: console

   $ cd autoparamdriver/
   $ make
   make -C ./configure install
   make[1]: Entering directory '/opt/epics/modules/autoparamdriver/configure'
   perl -CSD /opt/epics/base/bin/linux-x86_64/makeMakefile.pl O.linux-x86_64 ../..
   mkdir -p O.Common
   make -C O.linux-x86_64 -f ../Makefile TOP=../.. \
       T_A=linux-x86_64 install

   ... <output removed for brevity>

   make -C ./iocautoparamTest install
   make[2]: Entering directory '/opt/epics/modules/autoparamdriver/iocBoot/iocautoparamTest'
   perl -CSD /opt/epics/base/bin/linux-x86_64/convertRelease.pl -t /opt/epics/modules/autoparamdriver envPaths
   make[2]: Leaving directory '/opt/epics/modules/autoparamdriver/iocBoot/iocautoparamTest'
   make[1]: Leaving directory '/opt/epics/modules/autoparamdriver/iocBoot'
   make -C ./docs install
   make[1]: Entering directory '/opt/epics/modules/autoparamdriver/docs'
   true
   make[1]: Leaving directory '/opt/epics/modules/autoparamdriver/docs'

.. _ads-driver-install:

ADS Driver
===============
The procedure is similar to the one described for the autoparamDriver above. First download the latest stable version from `Github <https://www.github.com/cosylab/adsDriver>`__ link. Make sure you also clone the submodules.

The provided ``configure/RELEASE`` file assumes that the module’s parent directory contains a *RELEASE.local* file with the required module paths (i.e. *ASYN*, *AUTOPARAM* and *EPICS_BASE*):

.. code-block:: makefile

   # RELEASE - Location of external support modules
   #
   # Required external module paths:
   # ASYN - asynDriver
   # AUTOPARAM - autoparamDriver
   # EPICS_BASE - EPICS base

RELEASE file also contains an option to force compiling with C++11 on Linux. Use this if your toolchain is not compatible with a newer C++ standard.

.. code-block:: makefile
   
   # Set to YES in order to compile with C++11 on Linux, otherwise it will use 14.
   # Default is NO
   LINUX_USE_CPP11=NO

If you compile on Windows and you have TwinCAT installed, you might prefer using the ADS library included with your TwinCAT installation. You can define the path to your TwinCAT installation using TCDIR variable in the RELEASE file.

.. code-block:: makefile

   ## define TCDIR to use ADS library from local Beckhoff TwinCAT install
   ## rather than ADS in submodule
   #TCDIR=C:/TwinCAT

Compile the module:

.. code-block:: console

   $ cd ads/
   $ make
   make -C ./configure install 
   make[1]: Entering directory `/home/epics-dev/ads/configure'
   perl -CSD /opt/epics/base/bin/linux-x86_64/makeMakefile.pl O.linux-x86_64 ../..
   mkdir O.Common
   make -C O.linux-x86_64 -f ../Makefile TOP=../.. \
   T_A=linux-x86_64 install

   ... <output removed for brevity>

   make -C O.linux-x86_64 -f ../Makefile TOP=../../.. \
   T_A=linux-x86_64 install
   make[3]: Entering directory `/home/epics-dev/ads/adsApp/Db/O.linux-x86_64'
   make[3]: Nothing to be done for `install'.
   make[3]: Leaving directory `/home/epics-dev/ads/adsApp/Db/O.linux-x86_64'
   make[2]: Leaving directory `/home/epics-dev/ads/adsApp/Db'
   make[1]: Leaving directory `/home/epics-dev/ads/adsApp'