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.
The procedures described in this document use soft links in two places. Since soft links are not supported on winXX some changes will be necessary to use the procedures on winXX.
This document discusses template files. In the future these will no longer be used. Our intention is to let makeBaseApp evolve such that template files are no longer necessary. For now the template files can be obtained via the WWW APS software distribution system.
Currently two versions of makeBaseApp exist: A bourne shell version and a perl version. For beta11, the bourne shell version is the primary version. In the next release of base only the perl version will be supported. Starting soon the perl version will be made available via the WWW as a separate product. Thus new versions can be distributed without waiting for new versions of base.
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:
This manual assumes that the reader:
Before you can generate EPICS IOC applications your HOSTand/or EPICS System Manager must have done the following:
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.
This section explains how to quickly create an example IOC application in a directory <top> and named example.
Execute the command:
This should display your workstation architecture.
Note: Two versions of makeBaseApp are available: makeBaseApp, which is a bourne shell script, and makeBaseApp.pl, which is a perl script.
Execute the commands:
mkdir <top> cd <top> <base>/bin/<arch>/makeBaseApp -e example
<top> - Is 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.beta11/bin/solaris/makeBaseApp \ -e example
File <top>/iocBoot/iocexample/Makefile must be edited. This file has a line:
ARCH = ???
Change this to your target architecture. e.g. mv167.
Note: makeBaseApp.pl does this automatically
Spend some time looking at the files that appear under <top>. Do this BEFORE building.
In directory <top> execute the command:
Again look at all the files that appear under <top>.
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>/iocBoot/iocexample/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) : 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.
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.
See the description of the example given in section makeBaseApp below. Also try some of the vxWorks shell commands described in chapter "IOC Test facilities" of the Application Developer's Guide.
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:
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.
The application directory structure appears as follows:
iocsys/ <top>/ config/ xxxApp/ src/ xxxDb/ xxxApp/ ... iocBoot/ iocxxx/ iocxxx/
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 it's 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 merely 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:
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.
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.
The releases of share, which are dependent on releases of epics base, are named:
where XXX is the epics base release and YYY is a release of share for that base release. The share releases are stored at locations:
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 you should do something so that you remember to use the version from share after share is rebuilt.
Note: Other software packages can be handled like share. For example at APS/ASD our applications use releases of sharerf, epicsHideos, and hideos.
The following tools are used:
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
<top>/ Makefile config/ * CONFIG * CONFIG_APP * RELEASE RULES.Db * RULES.Host * RULES.Vx RULES.ioc RULES.iocBoot RULES_ARCHS RULES_DIRS RULES_TOP xxxApp/ src/ or xxxSrc Makefile * Makefile.Host * Makefile.Vx * base.dbd * baseLIBOBJS * <app>Include.dbd * <example and/or user supplied code> * <example and/or user supplied state programs> * <user menu, recordtype, device, driver database defs> Db/ or xxxDb Makefile * <record instance files> * <record template and substitution files> privately managed directories iocBoot/ Makefile nfsCommands iocxxx/ * Makefile * st.cmd ** dbd/ <installed database description files> ** include/ <installed include files> ** bin/ <host_arch> < installed Host executables > <ioc_arch> <installed ioc products> ... ** lib/ ** man/
Files marked with an "*" are user created and/or edited. Each such file is discussed in this chapter.
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.
The directories are:
The makefiles are described below in section Description of Makefiles below.
These files contain definitions included in the various makefiles.
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.
IMPORTANT:Each of the above variables must be specified with a full path name.
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:
with the name specified by DBDNAME in Makefile.Vx.
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.
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 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 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.
The vxWorks startup file is described in a later section.
NOTE: two versions of makeBaseApp exist. makeBaseApp is a bourne script and makeBaseApp.pl is a perl script. They produce nearly identical results.
makeBaseApp is executed by issuing the commands:
mkdir <top> # If <top> does not exist cd <top> <base>/bin/<arch>/makeBaseApp [-e] <app> ... makeBaseApp does the following:
<app>App src/ Makefile * Makefile.Host * Makefile.Vx * <app>Include.dbd * base.dbd * baseLIBOBJS Db/ Makefile
The user can rename Db to <anything>Db;
iocBoot Makefile ioc<app> * Makefile * st.cmd
The user can rename ioc<app> to ioc<anything>Db;
<app>App Db/ dbExample.db src/ caExample.c sncExample.st xxxRecord.dbd xxxRecord.c devXxxSoft.c
The user is expected to edit (or possibly remove) the files marked with an "*". The directory Db can be renamed as long as the last two characters remain Db. Additional xxxDb directories can be created manually. After each xxxDb directory is created, the Makefile can be copied from another Db directory.
The directory src can be renamed as long as the new name ends in Src. Additional source directories can be manually created. After each directory is created makefiles can be copied from another source directory and edited.
IMPORTANT: After creating new applications with makeBaseApp, <app>/iocBoot/ioc<app>/Makefile must be edited to specify the ioc architecture.
The remainder of this section gives a brief description of the files generated if makeBaseApp is executed with the -e option.
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:
This produces a list of all the records the ioc contains.
where pvname is one of the record names shown by dbl
NOTE: The commands dbLoadDatabase, dbExpand, and dbLoadRecords are described in Chapter 4, "Database Definition" of the Application Developer's Guide.
This file is the vxWorks startup file. The version created by makeBaseApp is:
# Example vxWorks startup file #Following must be added for many board support packages #cd <full path to target bin directory>
ld < bin/iocCore ld < bin/xxxLib #ld < bin/seq dbLoadDatabase("dbd/xxxApp.dbd") dbLoadRecords("xxxApp/xxxDb/xxx.db","user=USER") iocInit #start sequence programs #seq &sncxxx
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.
is an example command for loading record instances. One of these commands is supplied for each record instance file.
The iocInit command initializes the EPICS system.
The remaining commands in the file show how to load and start sequence programs.
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.
Make can be executed in any subdirectory where a Makefile appears, which is almost every subdirectory.
gnumake clean install
NOTE: If you are confused about the state of the generated files, just execute "gnumake rebuild ".
which is the same as issuing "gnumake rebuild" in each subdirectory of xxxApp.
It is possible to build for a single architecture via the command:
For example, if your IOC is an MV167 system, then the directory is O.mv167, and the make command is:
Another useful command is:
This removes everything generated in the O. directories. ".<arch>" can be appended to invoke clean for a particular architecture.
which is the same as issuing "gnumake" in each subdirectory of iocBoot.
If the Makefile includes RULES.iocBoot then a file nfsCommands must exist in the iocBoot directory. Running make generates a file nfs.cmd, which contains everthing in the nfsCommands file in addition to a command to cd to the iocBoot directory. The st.cmd file in the iocxxx directory can then start with the commands:
< ../nfs.cmd cd "iocxxx"
This provides an easy way to use NFS for all file access from the ioc. See the template files for examples.
The following is a summary of targets that can be specified for gnumake:
This makefile performs a make in the xxxApp and iocBoot subdirectories. In addition it allows other top level make options described below. There is seldom need to modify this file.
This makefile just executes make in src and each *Db subdirectory.
This file specifies Host components, which can be defined in Makefile.Host. 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 OIBSRCS := xxx.c yyy.c zzz.c LIBSRCS_<arch_class> os-specific library source files LIBSRCS_DEFAULT library source files for systems with no USR_CFLAGS_<arch_class> specified PROD_LIBS libs needed to link PROD for all systems PROD_LIBS_<arch_class> os-specific libs needed to link PROD PROD_LIBS_DEFAULT libs needed to link PROD for systems with no PROD_LIBS_<arch_class> specified PROD Product names (without execution suffix) to build and install 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 SCRIPTS scripts to install SCRIPTS_<arch_class> os-specific scripts to install SCRIPTS_DEFAULT scripts to install for systems with no PROD_<arch_class> specifieD LIBTYPE:=SHARED Library type. IF shared library is desired LIBTYPE must be defined SRCS Source files needed to build PROD (e.g. SRCS=a.c b.c c.c ) 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 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 USR_INCLUDES Directories to search for include files (e.g. -I$(EPICS_EXTENSIONS_BIN) ) USR_LDFLAGS linker options USR_LDLIBS load libraries (e.g. -lXt -lX11 ) 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>_LDLIBS target specific ld libraries (e.g. -lX11 -lXt ) UNIX_WARN Are compiler warning messages desired (YES or NO) (default is NO) UNIX_OPT Optimization level (default is no optimization) STATIC_BUILD Is static build desired (YES or NO) (default is NO)
The following components can be built:
BPTS += <table name>.dbd
RECTYPES += <rectype>Record.h LIBOBJS += <rectype>Record.o
MENUS += menu<name>.h
LIBOBJS += <name>.o
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 = xxxLib LIBNAME_CXX = xxxLib
The first is for c libraries and the second for c++ libraries.
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
LIBOBJS += <name>.o
SCRIPTS += <name>
INSTALLS += vxWorks vxWorks.sym iocCore seq
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 E2DB_FLAGS e2db options SCH2EDIF_FLAGS sch2edif 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))
This makefile performs the following functions:
DBFROMTEMPLATE += xxx.db
INDDBFROMTEMPLATE += xxxi.db
Note that the name of the substitutions file must be the same as the
template except that "i" is appended to the file name.
This executes make in each subdirectory.
This makefile creates soft links used in the st.cmd file. make sure that the definition:
ARCH = <arch>
refers to the correct architecture for your ioc processor.
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.
Your environment variable CVSROOT should point to the CVS repository for IOC Applications. The following command displays the location of CVSROOT:
At APS/ASD the command should show:
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.
gives overall cvs help.
The first step is to checkout ascf. The easiest way is to create the application area with a high level directory called iocsys. The following commands are issued:
cd <anywhere> cvs checkout iocsys/ascf
iocsys will appear as a subdirectory of <anywhere>. If <anywhere> is null then iocsys appears in the user's home directory.
cd <anywhere> cvs checkout iocsys/<top>
cd <anywhere> cvs checkout iocsys/<top>/Makefile cvs checkout iocsys/<top>/config cvs checkout iocsys/<top>/xxxApp ...
The entire iocBoot directory can be checked out via the command:
cvs checkout iocsys/<top>/iocBoot
A subset of the iocBoot directory can be checked out via the commands:
cvs checkout iocsys/<top>/iocBoot/Makefile cvs checkout iocsys/<top>/iocBoot/iocxxx ...
cvs edit <filename>
cvs unedit <filename>
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.
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.
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.
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
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.
cvs commit <filename>
commits changes to the repository. You are asked for comments via your favorite editor.
cvs status <filename>
Shows the status of the file. The -v option shows all tag information for the file.
cvs log <filename>
displays a list of all commits to the specified file..
tag <official release name>
cvs import -m "Creating" iocsys/newapp newapp start
The following directory structure contains templates for Makefiles and for rules:
iocsys/ template/ share/ Makefile config/ CONFIG CONFIG_APP RELEASE RULES.Db RULES.Host RULES.Vx RULES.ioc RULES_ARCHS RULES_DIRS RULES_TOP makeSoftLinks db/ Makefile xxiocstatus.db xxxApp/ top/ Makefile config/ CONFIG CONFIG_APP RELEASE RULES.Db RULES.Host RULES.Vx RULES.ioc RULES_ARCHS RULES_DIRS RULES_TOP xxxApp/ Makefile src/ Makefile Makefile.Host Makefile.Vx base.dbd baseLIBOBJS xxxDb/ Makefile iocBoot/ Makefile nfsCommands iocxxx/ Makefile st.cmd
A set of template files can be obtained via the WWW epics software distribution facility at APS.
APS/ASD manages its entire set of <top> level applications under a single directory structure:
/usr/local/iocapps/ CVSROOT/ iocsys/ <share releases> ascf/ share/ sharerf/ linac/ booster/ par/ parrf/ boosterrf/ srrf/ srbpm/ srfb/ time/ sitesys/ sr/