EPICS IOC Applications
Building 
and 
Source Release Control

Marty Kraimer, Janet Anderson , and Ralph Lange
June 15, 1998 
EPICS Release 3.13.0.beta12

Changes since beta11

Between release 3.13.0.beta11 and 3.13.0.beta12 makeBaseApp was changed from one very long perl script to a four page perl script plus template files. It supports templates in addition to those supplied with EPICS base. Other improvements were made including support for capfast. The primary developer of the new version of makeBaseApp was Ralph Lange (BESSY). Rozelle Wright (LANL) and Thomas Birke (BESSY) contributed to this development. In addition no soft links are required so that makeBaseApp works on winXX hosts.

Quick Start

If you are new to EPICS or are trying a new release, then follow the instructions in section Quick Start. Look at all the files that are generated. They give examples of how to manage each of the IOC components.
 

Index

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:

In addition procedures are described for managing large applications. The principle features are:

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.

Quick Start

This section explains how to quickly create an example IOC application in a directory <top> and named example.

Check Environment

Execute the command: 
echo $HOST_ARCH
This should display your workstation architecture.

Create example Application

Execute the commands: 
mkdir <top>
cd <top>
<base>/bin/<arch>/makeBaseApp.pl -t example example
<base>/bin/<arch>/makeBaseApp.pl -i -t example example
where:

<top> - Any directory name you chose.
<base> - Full path name to EPICS base.
<arch> - Your host architecture.

For example at ANL/APS the following commands create an application: 

cd
mkdir myapp
cd myapp
/usr/local/epics/baseR3.13.0.beta12/bin/solaris/makeBaseApp.pl -t example example
/usr/local/epics/baseR3.13.0.beta12/bin/solaris/makeBaseApp.pl -i -t example example
WIN95/NT notes:  Perl scripts are invoked with the command "perl  <scriptname>" on win95/NT and
Perl scripts are case sensitive. For example to create an application on WIN95/NT: 
     perl C:\epics\base\bin\win32\makeBaseApp.pl -t example example

Inspect Files

Spend some time looking at the files that appear under <top>. Do this BEFORE building.

Build

In directory <top> execute the command: 
gnumake

Inspect Files

Again look at all the files that appear under <top>.

Boot Parameters

The next step is to set the IOC boot parameters via the console serial port on your IOC. Life is much easier if you find out how to connect the serial port to a window on your workstation. See your EPICS system manager for details.

The vxWorks boot parameters look something like the following: 

boot device          : xxx
processor number     : 0
host name            : xxx
file name            : <top>/bin/<target_arch>/vxWorks
inet on ethernet (e) : xxx.xxx.xxx.xxx:<netmask>
inet on backplane (b):
host inet (h)        : xxx.xxx.xxx.xxx
gateway inet (g)     :
user (u)             : xxx
ftp password (pw) (blank = use rsh): xxx
flags (f)            : 0x0
target name (tn)     : <hostid for channel access security>
startup script (s)   : <top>/iocBoot/iocexample/st.cmd
other (o)            :
The actual values for each field are site and IOC dependent. Consult your EPICS system manager for help. Two fields that you can change at will are the vxWorks boot image and the location of the startup script.

Boot

You are now ready to boot your IOC. If your boot parameters are defined properly, just press the reset button on your IOC. You will find it VERY convenient to have the console port of the IOC attached to a scrolling window on your workstation.

Test

See the description of the example given in section  Templates Supplied with base. Also try some of the vxWorks shell commands described in chapter "IOC Test Facilities" of the Application Developer's Guide.

Introduction

Background

Before EPICS base release 3.13, APS/ASD used an Application Source Release control system called appSR. appSR uses sccs for source file control. Since appSR was written several things that impact S/R control have changed. For the above reasons we decided to redo the APS/ASD IOC Applications S/R control system. Our goals were: A major decision is What Directory Structure should we use. Before the original appSR was written a lot of discussion went into this topic. There were several meetings between the Application Developers and Bob Zieman, who implemented appSR. This directory structure was used to implement the entire APS/ASD contol system software. Thus a lot of correct decisions were made. The only major problem is that it was not easy to share code, mainly record/device/driver support, across <top> areas. This resulted in sharing by copying source modules from one <top> area to another. When one developer would make changes to a source module, the other developers would often not even be aware of the changes. Thus over time the source modules evolved in different directions.

Since the overall directory layout appears to be correct, it is kept in the new system. A brief description of the APS/ASD environment may help explain why the directory layout works.

One other topic to discuss before describing the overall directory structure is the idealized Application Development Cycle. It consists of the following steps:
  1. Define I/O requirements.

    2. This involves meeting with the user, in this case the engineers who are responsible for the application in order to decide the types and number of I/O modules needed.
  2. Assemble control hardware and software.

    3. This includes IOCs, I/O modules, software device/driver support, etc. If EPICS software support is not already available, it has to be written and tested.
  3. Build databases, sequence programs, etc.
In reality there is overlap between these steps. In addition as new needs arise the three steps again have to be performed. However, an application developer tends to spend a large part of his/her attention on each step before moving on to the next step.

The application structure described in the next section is designed to meet these needs.

Overview of Application Source Release Control

The application directory structure appears as follows: 
        <top>/
            config/
            xxxApp/
                src/
                xxxSrc/
                ...
                Db/
                xxxDb/
                ...
            xxxApp/
            ...
            iocBoot/
                iocxxx/
                ...
            bin/
                <host_arch>
                <target_arch>
            ...
Each <top> area is a separately managed set of applications. Separately managed means that each <top> can be using it's own release of software obtained from outside the application, e.g. a release of EPICS base.

Within a <top> area, multiple xxxApp subdirectories and a single iocBoot directory appear. The xxxApp areas are created by application developers as needed. The iocBoot directory contains a subdirectory for each IOC that belongs to that <top> area. No IOC belongs to more than one <top> area. All software components needed by IOCs are built in the xxxApp directories. Each IOC is booted from bin/<target_arch> (actually from any directory containing a vxWorks and vxWorks.sym compatible with the version of vxWorks against which the target was built) and uses a startup file from a subdirectory under iocBoot. The only important source file in a boot directory is the st.cmd file which is executed after vxWorks is started on an IOC. The st.cmd file loads various files built in the xxxApp directories.

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, however, contains iocxxx directories from multiple subsystems.

Now lets describe how the application developers use the above structure.

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 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 command gnumake will recreate the database file(s).

After changes are made in any xxxApp directory, the affected IOCs can be rebooted from the appropriate iocBoot subdirectory. If new components are added, it may be necessary to modify st.cmd files.

share

As mentioned above the one major defect with the old appSR system is that there was no easy way to share code across <top> areas. To solve this problem a new <top> area called share is present. It is structured somewhat differently than other <top> areas, but development in it is done just like in any other <top>. Releases of share are created. A release contains built and installed object modules. Other <top> areas take things from releases of share rather then from share itself.

At aps the releases of share, which are dependent on releases of EPICS base, are named: 

    baseXXXshareYYY
where XXX is the EPICS base release and YYY is a release of share for that base release. At aps the share releases are stored at locations: 
    /usr/local/iocapps/iocsys/baseXXXshareYYY
If it is necessary to obtain a bug fix or enhancement to a single module from EPICS base or a share release, the application developer has at least two choices. The first is to build a new release of base or share. A second choice is to copy the source module to an appropriate src directory and build it there. In this case the developer must remember to use the version from share after share is rebuilt.

Note: Other software packages can be handled like share.

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:

Classes of Users

Application System Manager :
The Application System Manager is responsible for the Operations Area.
Application Developer :
Anyone who tests, modifies, or extends an application's software. If multiple developers are working on the same system each should develop in a private development area.

References

Version Management with CVS for CVS 1.9, Per Cederqvist et al.

GNU Make, Edition .51 for make Version 3.75 Beta, May 1996, Richard M. Stallman and Ronald McGrath

EPICS: Application Developer's Guide R3.13, Marty Kraimer

Directory Structure

Structure

    <top>/
        Makefile
        config/
*           CONFIG
*           CONFIG_APP
*           RELEASE
            RULES.Db
*           RULES.Host
*           RULES.Vx
            RULES.ioc
            RULES.iocBoot
            RULES_ARCHS
            RULES_DIRS
            RULES_TOP
            makeDbDepends.pl
            makeIocCdCommands.pl
            replaceVAR.pl
        xxxApp/ or xxxapp
            src/ or xxxSrc or xxxsrc
                Makefile
*               Makefile.Host
*               Makefile.Vx
*               base.dbd
*               baseLIBOBJS
*               <app>Include.dbd
*               <source code>
*               <state programs>
*               < menu, recordtype, device, driver database defs>
            Db/ or db or xxxDb or xxxdb
                Makefile
*               <record instance files>
*               <record template and substitution files>
            privately managed directories
        iocBoot/ or iocboot
            Makefile
            Makefile.Host
            nfsCommands
            iocxxx/
*               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 marked with an "*" are user created and/or edited. Each such file is discussed in this section.

Files marked with "**" are directories created by gnumake. Since gnumake uninstall removes all files in these directories, no permanent files should be created in these directories.

Directories

The directories are:
config
Directory containing configuration files for gnumake.
xxxApp or xxxapp
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 Makefile looks for it.
xxxsrc or  xxxSrc
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.
xxxdb or xxxDb
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.
iocBoot or iocboot
Directory containing a subdirectory for each IOC.
iocxxx
Directory from which IOC iocxxx is booted. Each must have ioc prepended to the name because iocBoot/Makefile looks for it.
dbd
Installed Database Definitions Directory.
include
Include Directory. The directory in which include files generated from menu and record type definitions are installed.
bin
Bin Directory. This directory contains a subdirectory for the host architecture and for each target architectiure. These are the directories in which executables, binaries, etc. are installed.
lib
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.
db
Installed Databases Directory. The directory into which record instance, template and substitutions files are installed.

Makefiles

The makefiles are described in section Description of Makefiles below.

<top>/config/*

These files contain definitions included in the various makefiles.
CONFIG
This is the file in which you add to or modify make variables in EPICS base. A useful definition to override is:
    CROSS_COMPILER_TARGET_ARCHS =
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 variables saves build time.
If you are using capfast you may want to add the definition:
DB_OPT = YES
CONFIG_APP
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.
RELEASE
This file specifies the location of external products such as EPICS base. The procedures for going to a new release of an external product are described later in this chapter. One step in the procedures is to edit this file. The config files created by makeBaseApp provide support for the following variables:
EPICS_BASE
This variable must be defined.
SHARE
This variable, which is optional, specifies the location of a release of a <top> area containing code that can be shared by other applications.
TEMPLATE_TOP
This variable specifies the location of the template top area for makeBaseApp.
IMPORTANT: Each of the above variables must be specified with a full path name.
RULES.Db
This file contains rules for building and installing database files. Databases generated from templates and/or CapFast schematics are supported.
RULES.Host
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.
RULES.Vx
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.
RULES.ioc
This is a file containing rules for the Makefiles in the directories from which IOCs are booted.
RULES.iocBoot
This is a file containing rules for the Makefiles in the iocBoot directory. It should not be necessary to modify this file.
RULES_ARCHS
This file includes the RULES_ARCHS from base. It is seldom necessary to modify this file.
RULES_DIRS
This file includes the RULES_DIRS from base. It is seldom necessary to modify this file.
RULES_TOP
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.
makeIocCdCommands.pl
This is a perl script that generates a cdCommands file for use by IOCs.
makeDbDepends.pl
This is a perl script that generates make dependencies from substitutions files.
replaceVAR.pl
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 and <app>Include.dbd

NOTE: A version of base.dbd can be obtained from
<epics_base>/templates/makeBaseApp/top/exampleApp/src.
These files are used to configure database definitions for the following: When gnumake is executed, an expanded file, i.e. a file with all include statements expanded, is installed into: 
    <top>/dbd/
with the name specified by DBDNAME in Makefile.Host.

base.dbd contains definitions obtained from the base release. It contains definitions 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")
    ...
    #driver(drvXy010)
    #driver(drvVxi)
    ...
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 desired support.

File <app>Include.dbd, which contains definitions like: 

    include "base.dbd"
    #local menu, record, device, driver, breakpoint definitions
is the place where you define locally built support.

baseLIBOBJS

NOTE: A version of baseLIBOBJS can be obtained from
<epics_base>/templates/makeBaseApp/top/exampleApp/src.
This file defines all the object modules for record, device, and driver support supplied by EPICS. 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 definitions as follows: 

    #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
    ...
Thus it has a definition for all record, device and driver support 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 front of the appropriate lines. Makefile.Vx contains rules that will combine all support into a single module called xxxSupport.

APOLOGY: It would be nice if this file could be automatically generated. This is not possible because there is no naming convention for device support source files.

st.cmd

The vxWorks startup file is described in a later section.

makeBaseApp

makeBaseApp is a perl script that creates application areas. It can create the following: makeBaseApp creates directories and then copies template files with replacements into the newly created directories. EPICS base supports two sets of template files: simple and example. These are meant for simple applications. Each site, however, can provide its own set of template files which may provide additional functionality. This section will describe the functionality of makeBaseApp itself and the next section will describe details about the simple and example templates.

makeBaseApp  has the following usage: 

<base>/bin/<arch>/makeBaseApp.pl -l
<base>/bin/<arch>/makeBaseApp.pl -t type [options] app ...
             create application directories
<base>/bin/<arch>/makeBaseApp.pl -i -t type [options] ioc ...
             create ioc boot directories
where
 app  Application name (the created directory will have "App" appended to name)
 ioc  IOC name (the created directory will have "ioc" prepended to name)
 
 -t type  Set the application type (-l for a list of valid types)
          If not specified, type is taken from environment
          If not found in environment, "default" is used
 -T top   Set the template top directory (where the application templates are)
          If not specified, top path is taken from config/RELEASE
          If config does not exist, top path is taken from environment
          If not found in environment, the templates from EPICS base are used
 -l       List valid application types for this installation
          If this is specified the other options are not used
 -a arch  Set the IOC architecture (e.g. mv167)
          If not specified, you will be prompted
 -b base  Set the location of EPICS base (full path)
          If not specified, base path is taken from config/RELEASE
          If config does not exist, base path is taken from command
 -d       Verbose output (useful for debugging)
 
Environment Variables:
EPICS_MBA_DEF_APP_TYPE  Application type you want to use as default
EPICS_MBA_TEMPLATE_TOP  Template top directory
 
To create a new <top> issue the commands: 
    mkdir <top>    # If <top> does not exist
    cd <top>
    <base>/bin/<arch>/makeBaseApp -t <apptype> <app> ...
    <base>/bin/<arch>/makeBaseApp -i -t <apptype> <ioc> ...
makeBaseApp does the following: EPICS base supplies the following sets of template files simpleApp creates an xxxApp with a Db and src directory. Each directory contains skeleton makefiles. simpleBoot creates an iocBoot directory and iocBoot/iocxxx directories. Each directory contains makefiles. The iocxxx directories also contain a skeleton st.cmd file.

exampleApp and exampleBoot create a complete example application. It contains the following files.

caExample.c
A Host application that interfaces to Channel Access. It is executed from a Unix shell by issuing the command:
    caExample "pvname"
It issues a Channel Access get request for the specified process variable and prints the value. If you have booted an IOC from the example then try the following:
dbExample1.db
This is an example of record instances. Each name is proceeded by <userid>, which is the userid of the person who executed makeBaseApp. The records are:
<userid>aiExample
This is a passive ai (analog input) record which obtains its input from record calcExample,
<userid>calcExample
This is a calc (calculation) record that acts as a counter that continually counts from 0 to 9. It is scanned once a second. It also has a forward link to aiExample. Since aiExample is passive it will also scan once a second.
<userid>xxxExample
This is a sample record of type xxx, as described below. It is a passive record. You can change its VAL field via a Channel Access client or via the dbpf IOC command.
dbExample2.template / dbExample2.substitutions
This is another example of record instances. The database is generated from a template database, which is instantiated using the entries in the substitutions file. Each name is proceeded by <userid>, which is the userid of the person who executed makeBaseApp. Each line in the substitutions file creates a two record database, whose records are described above (aiExample and calcExample).
sncExample.st
This is a sequencer, i.e. state notation language, example. It prints a message on the IOC console every time the VAL field of record <userid>xxxExample becomes > 5.0 and also every time it becomes <=5.0..
xxxRecord.dbd xxxRecord.c
A skeleton record support module. The record support module is the one described in the Application Developer's Guide.
devXxxSoft.c
A device support module for xxxRecord. The device support module provides synchronous support for the record support.

st.cmd

NOTE: The commands dbLoadDatabase, dbExpand, dbLoadRecords, and dbLoadTemplate are described in chapter , "Database Definition" of the Application Developer's Guide.

This file is the vxWorks startup file. The version created by makeBaseApp is:

The cdCommands file defines vxWorks variables so that cd commands may be used later in the startup file. Definitions are provided for The first ld command loads the core EPICS components. File xxxLib is installed when gnumake is run in the <top>/xxxApp/src directory. It contains the executable for all record, device, and driver support as well as any other application specific object modules. If an IOC wants to use support generated in a sub-application src directory, this statement will have to be changed to coincide with the LIBNAME value.

The dbLoadDatabase command loads the definitions of all menus, record types, device support, driver support, and breakpoint tables needed in this IOC. These are actually expanded files created by dbExpand and installed into dbd. If an application wants to use database definitions generated in a sub-application src directory, this statement will have to be changed to coincide with the DBDNAME value.

The command: 

    dbLoadRecords("../../db/xxx.db","user=USER")
is an example command for loading record instances. One of these commands is supplied for each record instance file.

The command: 

    dbLoadTemplate("../../db/xxx.substitutions")
is an example command for loading record templates. One of these commands is supplied for each substitutions file.

The iocInit command initializes the EPICS system.

The remaining commands in the file show how to load and start sequence programs.

Switching to a new Release

The file <top>/config/RELEASE contains definitions for components obtained form 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 <top>/config/RELEASE
cd <top>
gnumake
Note that all definitions in <top>/config/RELEASE must be complete path definitions, i.e. relative path names are not permitted. If your site keeps releases of base and/or share, the path definitions should contain the release number (e.g. EPICS_BASE=/usr/local/epics/baseR3.13.0.beta12).

Make

Where make can be Executed

Make can be executed in any subdirectory where a Makefile appears, which is almost every subdirectory.
<top>
The most useful commands at the top level directory are:
xxxApp
Two useful commands at this level are
gnumake
or
gnumake rebuild
which is the same as issuing the command in each subdirectory of xxxApp.

 
xxxApp/src or xxxApp/xxxSrc
Running the command:
    gnumake
which is the same as executing "gnumake install"  builds and installs all out of date Host and IOC components described by the files Makefile.Host and Makefile.Vx. The builds are performed in subdirectories O.<arch>.

 
It is possible to build for a single architecture via the command:
    gnumake <arch>
For example, if your IOC is an MV167 system, then the directory is O.mv167, and the make command is:
    gnumake mv167
Another useful command is:
    gnumake clean
This removes the host and target architecture directories created by make. ".<arch>" can be appended to invoke clean for a particular architecture.
The command:
gnumake rebuild
is the same as "gnumake clean install".
xxxApp/xxxDb
Executing gnumake in this directory generates and installs database instance files, template and substitution files plain sources or CapFast schematics.
iocBoot
Executing
    gnumake
is the same as issuing "gnumake" in each subdirectory of iocBoot.
iocBoot/iocxxx
Executing gnumake in this directory creates the cdCommands file.

make targets

The following is a summary of targets that can be specified for gnumake: where:
<arch>
sun4, solaris, hp700, mv167, etc.

or
host - Builds for host architecture only.
or
cross - builds for vxWorks architecture(s) only.
<action>
clean, inc, install, build, rebuild, buildInstall, uninstall, or tar

NOTE: uninstall and tar can only be specified at <top>
<dir>
subdirectory name

Description of Makefiles

<top>/Makefile

This makefile performs a make in the xxxApp and iocBoot subdirectories. In addition it allows the top level make options uninstall and tar described in the previous section. There is seldom need to modify this file.

<top>/xxxApp/Makefile

This makefile just executes make in each  *src*, *Src*, *db* and *Db* subdirectory.

<top>/xxxApp/src/Makefile.Host

The following IOC related components can be built:
Breakpoint Tables
For each breakpoint table add the following definition
    BPTS += <table name>.dbd
Record Support
For each new record type, the following definitions must be added to the makefile:
    RECTYPES += <rectype>Record.h
and the record support files:
    <Record>Record.dbd
must exist.
If a menuXXX.dbd file is present, then add the following definition:
    MENUS += menu<name>.h
Expanded Database Definition File
Files containing database definition files are expanded by utility dbExpand and installed into <top>/dbd. The following variables are available. 
    DBDEXPAND += xxxInclude.dbd
    DBDNAME = xxxApp.dbd
    USER_DBDFLAGS += -I <include path>
    USER_DBDFLAGS += -S <macro substitutions>

    DBDINSTALL += xxx.dbd
where:
  • DBDEXPAND - A file containing database definitions.
  • DBDNAME - The name of the file containing expanded definitions to be created and installed into <top>/dbd.
  • USER_DBDFLAGS - Flags for dbExpand. Currently only an include path and macro substitution are supported.

    • DBDINSTALL - Installs the file into <top>/dbd.
     
    Makefile.Host has many facilities for building host components.. Replace <arch_class> in the following by the specific architecture class.
    USR_CFLAGS                      C compiler flags for all systems
USR_CFLAGS_<arch_class>         os-specific C compiler flags
USR_CFLAGS_DEFAULT              C compiler flags for systems with no
                                USR_CFLAGS_<arch_class> specified

USR_CXXFLAGS                    C++ compiler flags for all systems
USR_CXXFLAGS_<arch_class>       os-specific C++ compiler flags
USR_CXXFLAGS_DEFAULT            C++ compiler flags for systems with no
                                USR_CXXFLAGS_<arch_class> specified

INC                             include-files to install for all systems
INC_<arch_class>                os-specific includes go to the
                                include/os-directory:
INC_DEFAULT                     include-files to install for systems
                                with no INC_<arch_class> specified

LIBSRCS                         source files for building library,
                                specified as LIBSRCS += xxx.c yyy.c zzz.c
LIBSRCS_<arch_class>            os-specific library source files 
LIBSRCS_DEFAULT                 library source files for systems with no
                                LIBSRCS_<arch_class> specified

PROD                            Product names (without execution suffix)
                                to build and install (e.g. PROD=myprod)
PROD_<arch_class>               os-specific products to build and install
PROD_DEFAULT                    products to build and install for systems
                                with no PROD_<arch_class> specified
    SRCS                            Source files needed to build every PROD
                                (e.g. SRCS=a.c b.c c.c )
    PROD_LIBS                       libs needed to link every PROD for all systems
PROD_LIBS_<arch_class>          os-specific libs needed to link every PROD
PROD_LIBS_DEFAULT               libs needed to link every PROD for systems with
                                no PROD_LIBS_<arch_class> specified
    <lib>_DIR                       Directory to search for the specified lib. (For libs 
                                in PROD_LIBS, <PROD>_LIBS, <target>_LIBS, and USR_LIBS)
    SYS_PROD_LIBS                   system libs needed to link every PROD for all systems
SYS_PROD_LIBS_<arch_class>      os-specific system libs needed to link every PROD
SYS_PROD_LIBS_DEFAULT           system libs needed to link every PROD for systems with
                                no SYS_PROD_LIBS_<arch_class> specified
    <prod>_SRCS                     Source files needed to build a specific PROD
                                (e.g. myprod_SRCS=a.c b.c c.c )
<prod>_SRCS_<arch_class>        os specific source files to build a specific PROD
<prod>_ARCS_DEFAULT             source files needed to build a specific PROD for systems
                                with no <prod>_SRCS_<arch_class> specified
    <prod>_CFLAGS                   prod specific C compiler flags (e.g. xxxRecord_CFLAGS )
<prod>_CXXFLAGS                 prod specific C++ compiler flags
<prod>_CPPFLAGS                 prod specific cpp flags
<prod>_LDFLAGS                  prod specific ld flags
<prod>_LIBS                     prod specific ld libraries (e.g. X11 Xt )
<prod>_SYS_LIBS                 prod specific  system ld libraries (e.g. m)
    SCRIPTS                         scripts to install
SCRIPTS_<arch_class>            os-specific scripts to install
SCRIPTS_DEFAULT                 scripts to install for systems with no
                                SCRIPTS_<arch_class> specifieD

SHARED_LIBRARIES                Build shared libraries? Must be YES or NO
SHARED_LIBRARIES_<arch_class>   Build os specific shared libraries? Must be YES or NO
SHARED_LIBRARIES_DEFAULT        Build shared libraries for os systems with
                                no SHARED_LIBRARIES_<arch_class> specified
    SHRLIB_VERSION                  Shared library version number

USER_VPATH                      List of directories that gnumake should
                                search for files not in current dir.

LIBRARY                         Name of library to build. The name should
                                NOT include a prefix or extension, i.e.
                                specify Ca NOT libCa.a

TESTPROD                        Product names (without execution suffix)
                                to build but not install. Built from 
                                source file having same name.
    TESTPROD_SRCS                   Source files needed to build every TESTPROD

INSTALL_DIR                     Location of install directory (default $(TOP))

MAN1,MAN2,MAN3...               Name of man files to be installed
                                into $(INSTALL_DIR)/man/mani directory

DOCS                            Name of text files to be installed into
                                the $(INSTALL_DIR)/doc directory

TEMPLATES_DIR                   Template directory to be created,
                                $(INSTALL_DIR)/templates/$(TEMPLATE_DIR)
TEMPLATES                       List of template files to be installed
                                into $(TEMPLATE_DIR)


USR_CPPFLAGS                    cpp flags (for all makefile compiles)
USR_INCLUDES                    Directories to search for include files
                                (e.g. -I$(EPICS_EXTENSIONS_BIN) )
USR_LDFLAGS                     linker options (for all makefile links)
    USR_LDFLAGS_<arch_class>        os specific linker options (for all makefile links)
    USR_LIBS                        load libraries (e.g. -lXt -lX11) (for all makefile links)
    USR_LIBS_<arch_class>           os specific load libraries (for all makefile links)

YACCOPT                         yacc options
LEXOPT                          lex options
SNCFLAGS                        snc options
E2DB_FLAGS                      e2db options
SCH2EDIF_FLAGS                  sch2edif options
RANLIBFLAGS                     ranlib options

<target>_CFLAGS                 target specific C compiler flags (e.g. xxxRecord_CFLAGS)
<target>_CXXFLAGS               target specific C++ compiler flags
<target>_CPPFLAGS               target specific cpp flags
<target>_LDFLAGS                target specific ld flags
<target>_LIBS                   target specific ld libraries (e.g. X11 Xt )
    <target>_INCLUDES               Directories to search for include files for a
                                specific target (e.g. -I$(MOTIF_INC))

HOST_WARN                       Are compiler warning messages desired
                                (YES or NO) (default is NO)
HOST_OPT                        Optimization level  (default is no optimization)

STATIC_BUILD                    Is static build desired (YES or NO)
                                (default is NO)
    CLASSES                         Names of Java classes to be built and installed
TESTCLASSES                     Names of Java classes to be built
PACKAGE                         Names of Java package to be installed
JAR                             Name of Jar file to be built
JAR_INPUT                       Names of files to be included in JAR
MANIFEST                        Name of manifest file for JAR
    RCS                             Resource files needed to build every PROD
<prod>_RCS                      Resource files needed to build a specific PROD
<prod>_RCS_<arch_class>         os specific resource files to build a specific PROD

    <top>/xxxApp/src/Makefile.Vx

    The following components can be built:
    Record Support
    For each new record type, the following definitions must be added to the makefile
        LIBOBJS += <rectype>Record.o
    and the record support files:
        <Record>Record.c
    must exist.
    Device, Driver, other C modules
    For each such module, add a definition:
        LIBOBJS += <name>.o
    Each file will be placed in the library specified by LIBNAME.
    It is also possible to generate object files not placed in LIBNAME via the definitions:
        PROD += <name>.o
    or
    TARGETS += <name>.o
    Both will cause the specified file to be generated, PROD will also install the generated file into <top>/bin/<target_arch>.
     
    LIBNAME
    A file containing all LIBOBJS is installed into <top>/bin/<arch> with the name specified by LIBNAME. If Makefile.Vx appears in xxxApp/src, the definition should be:
        LIBNAME = xxxLib
    LIBNAME_CXX = xxxLib
    The first is for c libraries and the second for c++ libraries.
    State Notation Programs
    For each state notation program, add the definition:
        LIBOBJS += <name>.o
    The state notation programs must be named <name>.st.
    Scripts, etc.
    A definition of the form:
        SCRIPTS += <name>
    results in file <name> being installed from the src directory to the <top>/bin/<arch> directory.
    vxWorks, vxWorks.sym, iocCore, and seq
    In order to have vxWorks, vxWorks.sym, iocCore, and seq in the bin directory, the following must appear:
        INSTALLS += vxWorks vxWorks.sym iocCore seq
    NOTE: INSTALLS only needs to appear in one application.
    Other definitions 
    USR_CFLAGS      C compiler flags
USR_CXXFLAGS    C++ compiler flags
USR_INCLUDES    Include directory (e.g. -I$(EPICS_EXTENSIONS_BIN) )
USR_LDFLAGS     linker options

INC             include-files to install
MAN1,MAN2,...   Man files to be installed 
BIN_INSTALLS    Files in any directory to install to $(INSTALL_BIN)
DOCS            Text files to install into  $(INSTALL_DIR)/doc


YACCOPT         yacc options
LEXOPT          lex options
CPPFLAGS        cpp options
SNCFLAGS        snc options

<target>_CFLAGS         target specific C compiler flags
<target>_CXXFLAGS       target specific C++ compiler flags
<target>_CPPFLAGS       target specific cpp flags
<target>_SNCFLAGS       target specific state notation language flags
<target>_LDFLAGS        target specific ld flags

VX_WARN         Compiler warning messages desired (YES or NO) (default NO)
VX_OPT          Optimization level  (default is no optimization)


INSTALL_DIR     Installation directory (defaults to $(TOP))

    <top>/xxxApp/xxxDb/Makefile.Host

    This makefile creates and installs databases and related files.

    Databases

    Supported are: For template generated databases either the fully inflated database or the template and substitutions files may be installed (so the IOC may load the database using dbLoadRecords() or dbLoadTemplate()).

    For all these types of databases, the names of the files to install have to be specified. Make will figure out how to generate these files:

    will generate xxx.db depending on which source files exist. If xxx.db is template generated, the inflated database will be installed. will generate and install these files, i.e. the database will be inflated when it is loaded by the IOC using dbLoadTemplate().
    All template files that are used, but not installed (i.e. those not specified in DB), must be specified: If specified with a path (full or relative), the templates will be soft linked (UNIX) or copied (WIN) into the O.<arch> directory. After the first make run, template dependencies will be generated automatically.

    If there is no *.substitutions source for a needed substitutions file, but a variable defining a script name (like CREATESUBSTITUTIONS=CreateSubst.pl), this script will be called with the prefix of the substitution file name to be generated.

    NOTE: If (and only if) there are script generated substitutions files, the prefix of any inflated database's name may not equal the prefix of the name of any template used within the directory.

    Other definitions: 

    E2DB_FLAGS      e2db options
SCH2EDIF_FLAGS  sch2edif options

    Related Files

    Expanded Database Definition File
    where:
  • DBDEXPAND - A file containing database definitions.
  • DBDNAME - The name of the file containing expanded definitions to be created and installed into <top>/dbd.
  • USER_DBDFLAGS - Flags for dbExpand. Currently only an include path and macro substitution are supported.
  • DBDINSTALL - Installs the file into <top>/dbd.
    • Breakpoint Tables
    For each breakpoint table add the following definition
            BPTS += <table name>.dbd

    <top>/iocBoot/Makefile

    This executes make in each subdirectory.

    <top>/iocBoot/iocxxx/Makefile

    This makefile has a rule to generate cdCommands. Make sure that the definition: refers to the correct architecture for your IOC processor.

    Since cdCommands is generated the user generated and/or modified files are independent of location even though cdCommands contains full path names.

    CVS

    The CVS utility is used to put all user editable files under source/release control. This section gives a brief description of the commands normally used by application developers. Consult the CVS manual for more details.

    CVSROOT

    Your environment variable CVSROOT should point to the CVS repository for IOC Applications. The following command displays the location of CVSROOT: 
        echo $CVSROOT
    For example, at APS/ASD the command should show: 
        /usr/local/iocapps/cvsroot
    At APS all <top> applications are stored under $CVSROOT/iocsys. Other sites may use a different convention.

    Commands

    This section gives a brief description of the CVS commands. Wherever <filename> is shown a list of filenames is allowed. If <filename> is not specified then most commands apply to the entire directory and all subdirectories.

    A useful option for cvs is: 

        cvs -n <command>
    This will execute the command without making any changes.
    help
    Typing
        cvs help
    gives overall cvs help.
     
    Checkout Entire <top> Area
    To check out an entire <top> area issue the commands:
    cd <anywhere>
cvs checkout iocsys/<top>
    iocsys/<top> appears under <anywhere>
    watch
    Files (or complete directory trees including and entire <top> area) can have a watch placed on them. When a watch is placed on a directory cvs creates working copies read only. Users must execute a cvs edit command to obtain a read/write file. Facilities are provided to list all people editing a file and to be sent an e-mail message whenever someone executes the cve edit or commit commands for a watched file. Please read the cvs manual for details.
    edit
    If you want to edit a file and it is read only because a watch is in effect then execute the command:
            cvs edit <filename>
    unedit
    If you have started editing a file and decide to abandon your changes or not make any changes issue the command:
            cvs unedit <filename>
    add
    The command:
        cvs add <filename>
    places a directory or file under CVS control. This command must be given for each directory and file to be added to the repository.
    remove
    The command:
        cvs rm <filename>
    removes the specified file from the repository. The file is not actually deleted but is moved to the "attic". Thus previous versions can still be retrieved.
    diff
    The command:
        cvs diff <filename>
    compares the working copy of the file with the version that was checked out out or updated from the repository.

    The diff command has options that allow you to see the differences between any two versions committed to the repository.

    update
    The command:
        cvs update -d -A <filename>
    brings the development area into sync with the latest versions committed to the repository. A message is given for each file or directory that is modified. A message starting with the letter 
        C
    means that a conflict exists. Conflicts must be resolved manually.

    The two specified options (add new directories and reset sticky tags) should normally be specified.

    commit
    The command:
    cvs commit <filename>
    commits changes to the repository. You are asked for comments via your favorite editor.
    status
    The command:
    cvs status <filename>
    Shows the status of the file. The -v option shows all tag information for the file.
    log
    The command:
    cvs log <filename>
    displays a list of all commits to the specified file..
    .cvsignore
    Any directory can contain a file with the name .cvsignore. It contains a list of file and directory names that should be ignored by CVS. For example all generated directories and files should be listed in .cvsignore.
    tags
    The command:
    tag <official release name>
    is used by the Application System Manager to tag official application releases.
    import
    This command is used to put an existing tree of files into the cvs repository. Assume that a developer has created a new directory tree for a new <top> application in a directory newapp. It can be imported into the repository via the command:
    cvs import -m "Creating" iocsys/newapp newapp start