Contents Next

1. Overview

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 complicated applications.

This document describes how to create and build IOC applications. This includes:

Procedures are described for managing large applications. The principle features are: 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.

User Prerequisites

This manual assumes that the reader:

System Prerequisites

Before you can generate EPICS IOC applications your host and/or EPICS system manager must have done the following:

Make vs. Gnumake

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.

1.1. Overview of Application Structure

A <top> has the following structure: 
<top>/
    config/
    xxxApp/
        src/
        xxxSrc/
        ...
        Db/
        xxxDb/
        ...
    xxxApp/
    ...
    iocBoot/
        iocxxx/
        ...
    bin/
        <host_arch>
        <target_arch(s)>
    include/
    db/
    dbd/
    ...
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.

1.2. Use by Application Developers

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: 
gnumake
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.

<top>/config

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).

Types of Top

There are two different flavours of <top> described in this document which are used for slightly different purposes:
<supporttop>
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 dbd.
<ioctop>
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 the application.

Templates

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.

Tools

The following tools are used:

References

Version Management with CVS, Per Cederqvist et al.

GNU Make, Richard M. Stallman and Ronald McGrath

EPICS Application Developer's Guide, Marty Kraimer

Contents Next