Several EPICS Application Source/Release systems are available. Your
site may have adapted one of them. Consult your EPICS system manager.
This manual describes procedures that can be used for simple or
This document describes how to create and build IOC applications.
Procedures are described for managing large applications. The
principle features are:
- IOC databases.
- vxWorks startup files.
- State Notation Programs.
- Record/Device/Driver support.
- Access security configuration files.
- Other code to be executed in an IOC.
- Special Host code.
The structure of the EPICS CVS repository is described, along with the
distributed maintenance approach which will apply to all hardware
support modules in the future. The responsibilities of a module owner
are also covered here.
This manual assumes that the reader:
- The IOC software is divided into <top> areas. Each
<top> is maintained separately.
- Different <top> areas can be linked to different releases
of software outside of that <top> such as EPICS base.
- Two basic classes of <top> exist:
- A <top> the products of which are meant to be used by
other <top> areas. Examples are EPICS base and various
unbundled hardware support modules.
- A <top> for a set of iocs which share the same
- Where two or more <top> areas are linked, the linked
versions must be coherent (i.e. all the same release of EPICS base and
- All editable files are placed under CVS control.
- Each application developer makes changes in a private copy of one
or more <top> areas.
- Operations maintains the official <top> areas from which
the operational iocs are booted.
- cvs,gnumake,and makeBaseApp are the main
tools used to create and build applications.
- Templates are provided for creating new application directories.
EPICS base provides two sets of templates: simple and example.
Additional templates can be created.
Before you can generate EPICS IOC applications your host and/or EPICS
system manager must have done the following:
- Understands the C language
- Knows how to use a text editor
- Has at least a superficial knowledge of the make utility
EPICS provides an extensive set of make rules. These rules only work
with the GNU version of make, gnumake, which is supplied by the Free
Software Foundation. Thus, on most Unix systems, the native make will
not work. On some systems, e.g. Linux, GNU make may be the default.
This manual always uses gnumake in the examples.
A <top> has the following structure:
- Installed vxWorks and a board support package. Consult the vxWorks
documentation for details.
- Installed EPICS base.
Each <top> area is a separately managed set of
application files. Separately managed means that each <top>
can use it's own release of software obtained from outside the
application, e.g. a release of EPICS base.
A <top> area may contain one or more xxxApp subdirectories
and at most one iocBoot directory. The xxxApp areas are created by
application developers as needed to manage the software in a logical
structure. All software components needed by IOCs are built in these
xxxApp directories. The iocBoot directory contains a subdirectory for
each IOC that boots from this <top> area. An IOC can only use
a single <top> area for booting, and only one IOC should boot
from each iocxxx subdirectory under iocBoot. The most important source
file in a boot directory is the st.cmd file which is executed
after vxWorks is started on an IOC (the vxWorks boot parameters should
have the full path to this file as the startup script). The st.cmd
file loads various files which were built in the xxxApp directories
and installed in the bin/<arch> or other installation
directories, then starts the IOC software.
Application developers decide what constitutes a <top>.
For example, at APS, the Linac is completely contained in a single
<top> area, while the RF is spread over three <top>
areas: parrf, boosterrf, and srrf. No <top> area contains
iocxxx directories from multiple subsystems. A decision on how to
divide a control system between different <top> areas and
xxxApp directories within each <top> may be obvious for purely
technical reasons. Where this is not the case also consider the effects
of future upgrades and maintenance, for both the IOC applications and
their support software.
Under xxxApp are source and database directories. A source directory
contains source files for building executables and database description
files. Makefiles specify what to build. These makefiles can specify
components obtained from outside the <top> area, such as EPICS
base. After modifing files in this directory the command:
will rebuild components that depend on the modified
files. (It will be seen below that the generated components are
actually copied to an install directory)
The xxxApp database directories contain IOC database files and/or
template and substitution files used to generate database files. If
templates are used then whenever a template or substitution file is
modified the gnumake will recreate the database file(s).
After changes are made in any xxxApp directory and the components
rebuilt, the affected IOCs can be rebooted from the appropriate iocBoot
subdirectory. If new components are added, it may be necessary to
modify the st.cmd files.
This directory contains make rules, configuration files, and file
RELEASE. RELEASE contains a list of the locations of all
products needed by this <top> that are maintained elsewhere
(normally these are <supporttop> areas, see next section).
There are two different flavours of <top> described in this
document which are used for slightly different purposes:
The makeBaseApp.pl utility creates new application areas. It does this
by copying and transforming directory trees from a template area. EPICS
base provides templates for a simple application and for an example
application. Each site can, however, create their own set of templates.
The following tools are used:
- A <supporttop> contains products meant for use by other
<top> areas, incuding other <supporttop> and <ioctop>
areas. If a <supporttop> contains an iocBoot directory its
only purpose is for use in testing the <supporttop> software,
not for operational systems. All files meant for use by other <top>
s are installed into standard subdirectories such as include, bin and
- An <ioctop> has an iocBoot directory with an iocxxx
sub-directory for each ioc. This contains the st.cmd file for
the ioc, and can also be used for other ioc-specific files needed by
Version Management with CVS, Per Cederqvist et al.
- gnumake - GNU make plus EPICS supplied configuration
definitions, make rules, and script files.
- makeBaseApp - An epics/base supplied tool for creating
GNU Make, Richard M. Stallman and Ronald McGrath
EPICS Application Developer's Guide, Marty Kraimer