Converting an EPICS R3.13 application to R3.14.0alpha2

This document describes how to convert a R3.13 vxWorks application so that it builds with release R3.14.0alpha2. It describes procedures such that:

The application uses the configure rules which are new to R3.14.

The OSI (Operating System Independent) features of R3.14 are available, i.e. iocCore products can be build for vxWorks as well as other platforms, e.g. solaris and linux.

Gnumake clean uninstall

First do a gnumake clean uninstall in the application's root directory to remove all files created by earlier builds.

Create a new R3.14 application

mkdir <top>
cd <top>
/home/phoebus/JBA/epics/base/bin/solaris-sparc/makeBaseApp.pl -t example example

Copy all *App and iocBoot directories and files to the new <top> directory

cd <oldtop>
find *App iocBoot -print | cpio -pvmd <fullpath name to new top>

Modify <top>/configure/RELEASE

Copy definitions of external modules excluding EPICS_BASE and TEMPLATES_TOP from old application release file.
If sequence programs (*.st or *.stt files) exist in your application, add the SNCSEQ location definition for the R3.14 seq external module
SNCSEQ =<full path to seq top>
The R3.14 seq module must exist and be built with EPICS base R3.14.0alpha2.

Modify the Makefiles in <top>/*App directories.

Change     include $(TOP)/config/CONFIG_APP
to     include $(TOP)/configure/CONFIG
Change     include $(TOP)/config/RULES_DIRS
to     include $(TOP)/configure/RULES_DIRS

Modify the Makefiles in <top>/App/Db directories.

Remove existing Makefile
Rename Makefile.Host to Makefile
Modify Makefile as follows:
Change     TOP=../../..
to     TOP=../..
Change    include $(TOP)/config/CONFIG_APP
to     include $(TOP)/configure/CONFIG
Change     include $(TOP)/config/RULES.Db
to     include $(TOP)/configure/RULES
Place all definitions between the include lines.
Place any rules after the last include line.

Modify the Makefiles in <top>/*App/src directories.

Remove existing Makefile
Rename Makefile.Host to Makefile
Modify Makefile as follows:
Change TOP=../../..
to     TOP=../..
Change     include $(TOP)/config/CONFIG_APP
to     include $(TOP)/configure/CONFIG
Change     include $(TOP)/config/RULES.Host
to     include $(TOP)/configure/RULES
Change     PROD_LIBS = Db
to     PROD_LIBS = dbStaticHost
Change     Db_DIR = $(EPICS_BASE_LIB)
to     dbStaticHost_DIR = $(EPICS_BASE_LIB)
Change     USER_DBDFLAGS
to     USR_DBDFLAGS
Change     RECTYPES += xxxRecord.h
to     DBDINC += xxxRecord
Change     DBDNAME = <name>.dbd
to     DBD += <name>.dbd
Remove all DBDEXPAND lines.
Add the contents of Makefile.Vx to Makefile removing the include lines and the TOP definition.

Change     LIBNAME = <libname>
to     LIBRARY_vxWorks = <libname>
Add the line   <libname>_OBJS = $(LIBOBJS)
Change     INSTALLS = iocCore seq
to
<libname>_OBJS_vxWorks += $(EPICS_BASE_BIN)/iocCoreLibrary
<libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/seqLibrary
<libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/pvLibrary
<libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/pvCaLibrary
Change     include ../baseLIBOBJS
to     -include ../baseLIBOBJS
Change    SRCS += <srcname>.c
to     <libname>_SRCS += <srcname>.c
Rename your sequence programs from <name>.st to <name>.stt if they do not need c preprocessing before conversion.
Change    LIBOBJS += <seq_program_name>.o      lines
to   <libname>_SRCS += <seq_program_name>.stt
or <libname>_SRCS += <seq_program_name>.st
Place all macro definitions between the include lines.
Place any rules after the last include line.

Modify the Makefiles in <top>/iocBoot directory.

Change include $(TOP)/config/CONFIG_APP
to include $(TOP)/configure/CONFIG
Remove the line DIRS += $(wildcard *ioc*)
Change include $(TOP)/config/RULES.iocBoot
to include $(TOP)/configure/RULES.iocBoot

Modify the Makefiles in <top>/iocBoot/ioc* directories.

Change include $(TOP)/config/CONFIG_APP
to     include $(TOP)/configure/CONFIG
Change include ARCH = <old arch specification e.g. mv167>
to     include ARCH = <new arch specificatio e.g. vxWorks-68040>
Change include $(TOP)/config/RULES.ioc
to     include $(TOP)/configure/RULES.ioc

Modify st.cmd in <top>/iocBoot/ioc* directories.

Remove the lines

ld < seq
ld < iocCore
Change ld < <libname>
to ld < <libname>Library.munch
Change load statements for db and dbd files from
cd startup
dbLoadDatabase("../../dbd/exampleApp.dbd")
dbLoadRecords("../../db/dbExample1.db","user=jba")
dbLoadRecords("../../db/dbExample2.db")
to
cd top
dbLoadDatabase("dbd/example.dbd")
registerRecordDeviceDriver(pdbbase)
dbLoadRecords("db/dbExample1.db","user=jba")
dbLoadRecords("db/dbExample2.db")

Record support changes

The steppermotor, scan, and pid records are no longer in base. If these record types are used at your site, they should be downloaded and built with base R3.14 by your EPICS administrator. To update the R3.14 location of these record types in your application you must add appropriate module definitions to your application's config/RELEASE file and change the LIBOBJS definitions.
For example add

PID=<full path to modules directory>/pid
to config/RELEASE.
Remove

LIBOBJS += $(EPICS_BASE_BIN)/pidRecord.o
from baseLIBOBJS,
and add

LIBOBJS += $(PID_BIN)/pidRecord.o
to your application src/Makefile.

You should consider changing any existing old steppermotor records to the new EPICS motor record module supported by Beamline Controls and Data Acquisition at APS.

RecDynLink.o and devPtSoft changes

recDynLink.o and devPtSoft.o are no longer in EPICS base and now exist as separate EPICS modules.You must now add the appropriate module full path definitions to your application config/RELEASE file, and change LIBOBJS location definition $(EPICS_BASE_BIN) to the module definition bin directory in your application src directory files. See "Hardware support changes" below for instructions.

Hardware support changes

All hardware support (dev, drv and dbd files) except soft support has been unbundled from base R3.14. This support includes the files symb.dbd, drvHp1404a.o, drvEpvxiMsg.o, and drvEpvxi.o.

Hardware support now exists as separate EPICS modules. The hardware support for your site should be downloaded and built with base R3.14 by your EPICS administrator. You must now add the appropriate module full path definitions to your application config/RELEASE file, and change LIBOBJS location from $(EPICS_BASE_BIN) to the module bin directory in your application src directory files.
For example, remove

LIBOBJS+=$(EPICS_BASE_BIN)/symb

from baseLIBOBJS and add

LIBOBJS+=$(SYMB_BIN)/symb

to your application src/Makefile,
and add the line

SYMB=<full path definition for the built module SYMB>

into your application config/RELEASE file .

dbLoadtemplate tool changes

The host tool dbLoadTemplate has been replace by a new EPICS extension, msi, which should be downloaded and built with base R3.14 by your EPICS administrator. dbLoadTemplate is still supported on iocs. If, in your application, db files are created from template and substitution files you should add the definition
EPICS_EXTENSIONS=<full path name to epics extensions directory>
to your application config/RELEASE file.