Contents Previous Next

3. Managing a <top>

3.1. Definition of <top>

An autonomously managed area which has a structure like that created by makeBaseApp.
Autonomously managed means that each <top> can follow its own release schedule.
The locations of software that a <top> uses from outside its own area are specified in its config/RELEASE file. For example:
#RELEASE Location of external products


In the above example: For ioc applications there are two flavors of <top>:
A <top> area in which a set of related iocs are managed and booted.
A set of software meant to be used by one or more <ioctop> s, e.g. device and driver support for a particular hardware interface board, or a commonly used database template. See the Support Management: Overview section for details.
It is expected that a small set of application engineers will be responsible for a particular <ioctop>, and that the iocs in an <ioctop> are responsible for a limited set of functions. If this is done it is much easier to manage ioc applications.

3.2. Directory Structure

*       CONFIG
*       CONFIG_APP
*       RELEASE
    xxxApp/ or xxxapp
        src/ or xxxSrc/ or xxxsrc/
*           Makefile.Host
*           Makefile.Vx
*           base.dbd
*           baseLIBOBJS
*           <app>Include.dbd
*           C and State Notation Language source
*           menu, recordtype, device and driver database definitions
        Db/ or db/ or xxxDb/ or xxxdb/
*           record instance files
*           record template and substitution files
        privately managed directories
    iocBoot/ or iocboot/
*           Makefile
*           st.cmd
$           cdCommands
$   dbd/
        installed database description files
$   db/
        installed record instance files
$   include/
  	installed include files
$   bin/
$       <host_arch>
            installed Host executables
$       <ioc_arch>
            installed IOC products
$   lib/
Files above marked "*" are user created and/or edited. Each of these file types is discussed in this section.

Entries marked "$" are directories or files created by gnumake. Since gnumake clean uninstall removes these files and directories, no permanent data should be stored here.


The user-modifiable directories are:
Directory containing configuration files for gnumake.
Directory containing source files and database files. An arbitrary number of xxxApp directories are allowed. Each must have App or app appended to the name because the top-level Makefile looks for this pattern.
Directory containing source files. An arbitrary number of source directories can appear under each xxxApp. The names must have the suffix src or Src. A source directory is where C code, sequence programs, scripts, etc. are created and built.
Directory containing record instance files. An arbitrary number of Db directories can exist under each xxxApp. The name must have the suffix db or Db. Each Db directory can contain record instance, template, and substitution files or the equivalent CapFast schematics.
Directory containing a subdirectory for each IOC.
Directory from which IOC iocxxx is booted. Each must have ioc prepended to the name because iocBoot/Makefile looks for it.
The following directories are created by gnumake to hold built objects:
Installed Database Definitions Directory.
Include Directory. The directory in which include files generated from menu and record type definitions are installed.
Binaries Directory. This directory contains a subdirectory for the host architecture and for each target architecture. These are the directories in which executables, binaries, etc. are installed.
Library Directory. This directory contains a subdirectory for the host architecture and for each target architectiure. These are the directories in which libraries are installed.
Installed Databases Directory. The directory into which record instance, template and substitutions files are installed.


The makefiles are described in the section Description of Makefiles.


These files contain definitions, make rules, and perl scripts used by the various Makefiles in <top>. Please note that most developers will only need to modify the files RELEASE and, until release 3.13.2, CONFIG_APP.

The following describes the files generated by makeBaseApp using either template simple or example. It is possible to create templates for makeBaseApp that act differently.

This is the file in which you add to or modify make variables in EPICS base. A useful definition to override is:
This specifies the vxWorks architecture to build. If your site builds base for multiple target architectures but your IOCs only use a single architecture, overriding this variable with a subset of the base target architectures will save build time.

If you are using capfast you may want to add the definition:


This file contains definitions for external products such as EPICS base and share. You should edit this file if you are using external products besides epics_base and share. Follow the models already in the file.

NOTE: Beginning with base release 3.13.2 the definitions that previously had to be manually added to this file to support external products will automatically be generated from the definitions in RELEASE. This is done by gnumake which executes a new script From 3.13.2 onwards therefor it will no longer be necessary to edit this file.

This file specifies the location of external products such as EPICS base. All entries in the RELEASE file must define a full path name, either directly or using gnumake macro substitutions. The procedures for going to a new release of an external product are described later in this chapter. One step in those procedures is to edit this file. The config files created by makeBaseApp provide support for the following variables:
This convenience (optional) variable is usually set to the top of the directory tree holding support applications; succeeding definitions are usually given relative to this.
This variable must be defined, but usually as the last entry.
This variable specifies the location of the template top area for makeBaseApp.
This file contains rules for building and installing database files. Databases generated from templates and/or CapFast schematics are supported.
The template file includes the RULES.Host from base. If you want to add rules that apply to all Makefile.Host files then this is the place to add the rules.
The template file includes the RULES.Vx from base. If you want to add rules that apply to all Makefile.Vx files then this is the place to add the rules.
This is a file containing rules for the Makefiles in the directories from which IOCs are booted.
This is a file containing rules for the Makefiles in the iocBoot directory. It should not be necessary to modify this file.
This file includes the RULES_ARCHS from base. It is seldom necessary to modify this file.
This file includes the RULES_DIRS from base. It is seldom necessary to modify this file.
This file includes RULES_TOP from base. If MASTER_IOCAPPS is defined it also runs a utility that creates soft links to the master IOC. This feature only works if the host operating system supports soft links.
This is a perl script that generates a cdCommands file for use by IOCs. See the section Component: Directory Structure : cdCommands in this chapter for details.
This is a perl script that generates make dependencies from substitutions files.
Starting with release 3.13.2 this script will be provided. It automatically generates the definitions which previously had to be added to CONFIG_APP. It puts the definitions into a file CONFIG_APP_INCLUDE.
This is a perl script that changes VAR(xxx) style macros in CapFast generated databases into the $(xxx) notation used in EPICS databases.


These files are used to configure database definitions for the following: base.dbd contains definitions obtained from the base release. It contains statements like:
include "menuGlobal.dbd"
include "menuConvert.dbd"
include "aiRecord.dbd"
#include "aaiRecord.dbd"
device(ai,CONSTANT,devAiSoft,"Soft Channel")
#device(ai,CONSTANT,devAiSoftRaw,"Raw Soft Channel")
Thus it has a definition for all menus, record types, devices, and drivers supplied in EPICS base. Some record types and ALL hardware device and driver support are proceeded by the comment symbol "#". You are expected to edit this file and select the desired support routines, by removing the "#" from the relevent lines.

A version of base.dbd appropriate to your version of EPICS base can be obtained from <epics_base>/templates/makeBaseApp/top/exampleApp/src.

The file <app>Include.dbd is used to construct a complete list of definitions needed by the application. It must contain the line

include "base.dbd"
to incorporate all the definitions from base, followed by any definitions needed for locally built support. The name of this file is specified in the DBDEXPAND variable in Makefile.Host . Then when gnumake is executed, a file with the name defined by DBDNAME in Makefile.Host and having all of the include statements expanded will be installed into <top>/dbd/.


This file lists all the compiled binary object files needed for the record, device, and driver support supplied in EPICS base. Since the file is intimately related to base.dbd, if base.dbd (is, is not) used in a particular xxxApp/src directory, then baseLIBOBJS should (be, not be) used in that directory.

baseLIBOBJS contains a series of definitions as follows:

#LIBOBJS += $(EPICS_BASE_BIN)/aaiRecord.o
#LIBOBJS += $(EPICS_BASE_BIN)/aaoRecord.o
# Device Support
#LIBOBJS += $(EPICS_BASE_BIN)/devAaiCamac.o
# Driver support ANSI
As with the base.dbd file, some record types and ALL hardware device and driver support are proceeded by the comment symbol "#". You are expected to edit this file and select the desired support routines, by removing the '#' from the front of the appropriate lines. These edits should match those made in the base.dbd file, although no harm will usually come from uncommenting entries in baseLIBOBJS that correspond to commented-out entries in base.dbd, the effect is just to use up memory unnecessarily. The reverse is not generally true, and this also assumes that there are no references to the relevent record or device type in any database loaded by the IOCs concerned.

Makefile.Vx contains rules that will combine all support into a single module with a name given by the value of LIBNAME .

NOTE: A version of baseLIBOBJS can be obtained from

APOLOGY: It would be nice if this file could be automatically generated from the information in the expanded dbd file described above. This is not currently possible because there is no naming convention for device and driver support source files.


The vxWorks startup file is described in a later section.


This file is automatically generated within each <top>/iocBoot/iocxxx directory by gnumake executing When this cdCommands script is called by st.cmd it generates a series of vxWorks shell string variables for use with the vxWorks cd command. For example the subsequent line in st.cmd
cd startup
will change to the directory containing the st.cmd file. The perl script used differs between releases 3.13.1 and 3.13.2. The following describes the variables generated for each release

Release 3.13.1

The full path to the directory containing the startup file.
The full path to <top>/bin/<ioc_arch>
If SHARE is defined in <top>/config/RELEASE this gives the full path to share

Release 3.13.2

The full path to <top>
The full path to the directory containing the startup file.
The full path to <top>/bin/<ioc_arch>
In addition, for each external <top> listed in <top>/config/RELEASE via an entry "<PROD>=<path>" the following variables are also created:
The full path <path> to the product if the the directory actually exists
The full path to <path>/bin/<ioc_arch> if this directory exists.
Thus in 3.13.2 it is easy to get to the <prod> and <prod>/bin/<ioc_arch> directories of all external products specified in <top>/config/RELEASE. Once at the top of a product its db and dbd subdirecties can be accessed by using relative pathnames.

3.3. Using External <top> Components

The structure of <top> is designed to make it easy to link to other <top> areas, each with it's own release schedule. The basic methods that make this possible are:

3.4. Switching to a New Release of an External <top> component

The file <top>/config/RELEASE contains definitions for components obtained from outside <top>. If you want to link to a new release of anything defined in the file do the following:
cd <top>
gnumake clean uninstall
vi config/RELEASE
     change the relevent line to point to the new release
All definitions in <top>/config/RELEASE must result in complete path definitions, i.e. relative path names are not permitted. If your site could have multiple releases of base and other <supporttop> components installed at once, these path definitions should contain a release number as one of the components. However as the RELEASE file is read by gnumake, it is permissible to use macro substitutions to define these pathnames, for example:
SUPPORT = /usr/local/iocapps/R3.13.1
EPICS_BASE = $(SUPPORT)/base/3-13-1-asd2

Contents Previous Next