:orphan:

.. highlight:: rest

.. _iochlafolderstructure:

IOC and HLA folder structures.
===============================


Software packages are classified by ``cram`` into various package types.
Package types are nothing more than a name and two folders but there are these kinds of package types

* EPICS IOC software packages
* HLA software packages
* Tools/script - This category also includes scripts like ``cram``.

----------------------
IOC folder structures.
----------------------

IOC software packages are those that have multiple instances of the same software package in the same facility.
A version of an EPICS IOC software package typically has this folder structure.

.. image:: img/iocfolder.png
	:scale: 50%

The source code for the IOC is typically in an ``app`` folder which gets compiled into a ``bin`` folder.
Each IOC instance has a folder in the ``iocBoot`` folder - the folder name is identical to the IOC name.
Each ``iocBoot`` folder has a ``st.cmd`` that contains the boot commands for that IOC.
These are mostly identical - typically, only the ``msi`` macro expansions vary from IOC to IOC but this need not be the case.
Some IOC software packages can have multiple executables that cater to completely different hardware; however, the folder structure even in these cases is as shown here.


Each site/facility has a release folder where the various versions of the IOC software packages are kept.
This is sometimes referred to as ``iocTop`` and has the following folder structure.

.. image:: img/ioctop.png
	:scale: 50%


Each site/facility has a startup folder where the various initial startup scripts/boot images are kept.
This is a fixed location and is often used in ``DHCP`` or ``/etc/init.d`` configuration.
This is sometimes referred to as ``iocCommon``.

.. image:: img/ioccommon.png
	:scale: 50%

For EPICS IOC software packages, ``cram`` uses two soft links to control a master release and a IOC specific release.

.. image:: img/iocsoftlink.png
	:scale: 50%


* In ``iocTop``, there is a softlink called ``current`` that points to the current master release for this software package.
* In ``iocCommon``, for each IOC, there is a soft link called ``iocSpecificRelease`` that typically points to the current master release. However, to use a release other than the current master release for an IOC, the ``iocSpecificRelease`` changes from pointing to the current master release and points directly to the appropriate release.



----------------------
HLA folder structures.
----------------------

HLA applications have a simpler folder structure.
HLA applications do not have multiple instances like EPICS IOCs.
Each facility typically has only one instance of the software package.
For this reason, a single softlink is sufficient to switch releases.
This softlink has the same name as the name of the package.

.. image:: img/hlasoftlink.png
	:scale: 50%

--------------------------------
Tools/script folder structures.
--------------------------------
``cram`` is also used to manage the various scripts that are used our facilities.
For example, ``cram`` itself is one such software package.
Typically, a site specific folder called ``tools/script`` is added to the PATH to facilitate running scripts like ``cram`` from the command line.
In a fashion similar to the HLA apps, the ``tools/script`` folder also contains a ``release`` folder where the various software package versions are maintained.
In a fashion similar to the HLA apps, there is a softlink with the same name as the package name that points to the current version of the software package.
Individual scripts are softlinks to ``<package name>/<script name>``. For example, ``cram`` points to ``multi_site_build/cram``.


.. image:: img/toolsscriptsoftlink.png
	:scale: 50%

Note that the folder structure for ``tools/script`` is identical to the folder structure for HLA applications.