The locations of software that a <top> uses from outside its
own area are specified in its config/RELEASE file. For example:
- 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.
In the above example:
#RELEASE Location of external products
For ioc applications there are two flavors of <top>:
- IMAGEFLOW and MSITOP are obtained from outside the IOC
- Release numbers such as 1-1-asd1 are explained later in
- The order of entries in the file is important when searching
include files. EPICS_BASE should usually be listed last to
allow other support areas to override its entries.
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.
- A <top> area in which a set of related iocs are managed
- 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.
Files above marked "*" are user created and/or
edited. Each of these file types is discussed in this section.
xxxApp/ or xxxapp
src/ or xxxSrc/ or xxxsrc/
* 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/
installed database description files
installed record instance files
installed include files
installed Host executables
installed IOC products
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:
The following directories are created by gnumake to hold
- 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
- 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
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.
- 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 following describes the files generated by makeBaseApp using
either template simple or example. It is possible to create templates
for makeBaseApp that act differently.
These files are used to configure database definitions for the
- 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:
DB_OPT = YES
- 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
makeConfigAppInclude.pl. 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
- This file contains rules for building and installing database
files. Databases generated from templates and/or CapFast schematics are
- 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
- 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
- This is a perl script that changes VAR(xxx) style macros
in CapFast generated databases into the $(xxx) notation used
in EPICS databases.
base.dbd contains definitions obtained from the base release.
It contains statements like:
- record types
- device support
- driver support
- breakpoint tables
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.
#device(ai,CONSTANT,devAiSoftRaw,"Raw Soft Channel")
A version of base.dbd appropriate to your version of EPICS
base can be obtained from
The file <app>Include.dbd is used to construct a complete
list of definitions needed by the application. It must contain the line
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:
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.
#LIBOBJS += $(EPICS_BASE_BIN)/aaiRecord.o
#LIBOBJS += $(EPICS_BASE_BIN)/aaoRecord.o
LIBOBJS += $(EPICS_BASE_BIN)/aiRecord.o
# Device Support
#LIBOBJS += $(EPICS_BASE_BIN)/devAaiCamac.o
# Driver support ANSI
#LIBOBJS += $(EPICS_BASE_BIN)/drvAb.o
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
makeIocCdCommands.pl. 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
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
- 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
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 to <top>
- The full path to the directory containing the startup file.
- The full path to <top>/bin/<ioc_arch>
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.
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:
- The full path <path> to the product if the the directory
- The full path to <path>/bin/<ioc_arch> if this directory
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:
- A <supporttop> installs its public components into
standard subdirectories. For example all executables are stored into
- To use components from another <supporttop> in any
<top> do the following:
- Add a line to <top>/config/RELEASE defining the external
product's location, eg:
MYPROD = $(SUPPORT)/myprod/1-3
- If using EPICS releases before 3.13.2, add definitions to
<top>/config/CONFIG_APP. For example:
From release 3.13.2 onwards, executing gnumake in the
config directory performs an equivalent step.
MYPROD_BIN = $(MYPROD)/bin/$(T_A)
USR_INCLUDES += -I$(MYPROD)/include
USER_DBDFLAGS += -I $(MYPROD)/dbd
- In one or more of the <top>'s source and database
directories reference components from the <supporttop> as
required. These references can take the following forms:
- #include statements used in C and C++ source code will
search the <supporttop>/include directory for any installed
- include statements found while expanding an
<app>Include.dbd file will search the <supporttop>/dbd
directory for the installed dbd files named.
- Compiled object files from a <supporttop>/bin/<arch>
directory can be linked into an xxxLib object library by
adding the object filename to the definition of LIBOBJS in
Makefile.Vx using statements like:
LIBOBJS += $(MYPROD_BIN)/myprod.o
- From release 3.13.2 the automatically generated cdCommands
file in each iocBoot/iocxxx directory defines string
constants which can be used in the st.cmd file to cd
to the top and bin/<arch> directories of any <supporttop>
defined in <top>/config/RELEASE. For example:
- A full description on how to use an external <supporttop>
module in an application should form part of the module's
documentation, which may over-ride some of the above instructions. If
such documentation is not provided, ask the module maintainer why not.
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:
gnumake clean uninstall
change the relevent line to point to the new release
SUPPORT = /usr/local/iocapps/R3.13.1
EPICS_BASE = $(SUPPORT)/base/3-13-1-asd2