Author: jba

## Converting an EPICS R3.13 application to R3.14

This document describes how to convert a R3.13 vxWorks application so that it builds with release R3.14. 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

We will remove junkApp later.

>     mkdir top
>     cd top
>     /path/to/base-3.14/bin/host_arch/makeBaseApp.pl -t example junk

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

>     cd oldtop
>     find *App iocBoot -print | cpio -pvmd /path/to/new/top

### Modify top/configure/RELEASE

Copy definitions of external modules excluding `EPICS_BASE` and `TEMPLATE_TOP` from your old application config/RELEASE file. In many cases the modules you actually use under R3.14 will be different to the R3.13 modules, but the old module names here give you a starting-point for what there replacements will be.

If any sequence programs (*.st or *.stt files) exist in your application, add the SNCSEQ location definition for the R3.14 sncseq external module.

>     SNCSEQ = /path/to/sncseq

The R3.14 sncseq module must exist and be built with the same EPICS base R3.14 release.

### 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 the `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.

This is the hardest step. The definitions in Makefile.Host and Makefile.Vx must be manually converted to the new configure definitions.

First replace Makefile with the Makefile from junkApp/src.

>     rm Makefile
>     cp ../../junkApp/src/Makefile .

We can remove the junkApp now (unless you have other App/src directories still to convert):

>     rm -rf ../../junkApp

This new Makefile has comments explaining how to build the various host and IOC products. Lets consider some examples

- Host programs

  Makefile.Host contains definitions like:

  >     PROD += caExample
  >     caExample_SRCS += caExample.c
  >     PROD_LIBS +=  ca Db Com
  >     ca_DIR  = $(EPICS_BASE_LIB)
  >     Db_DIR  = $(EPICS_BASE_LIB)
  >     Com_DIR = $(EPICS_BASE_LIB)

  In Makefile these are:

  >     PROD_HOST += caExample
  >     caExample_SRCS += caExample.c
  >     caExample_LIBS += $(EPICS_BASE_HOST_LIBS)

- Record Support - generate xxxRecord.h file

  Makefile.Host (or perhaps Makefile.Vx) contains:

  >     RECTYPES += xxxRecord.h

  In Makefile this is:

  >     DBDINC += xxxRecord

- Generating the .dbd file for all record/device/driver support

  Makefile.Host (or perhaps Makefile.Vx) contains:

  >     DBDEXPAND = exampleInclude.dbd
  >     DBDNAME = exampleApp.dbd

  In Makefile this is:

  >     DBD += example.dbd

  NOTES: Change exampleApp.dbd to example.dbd in all st.cmd files. Also this definition assumes that file exampleInclude.dbd exists.

- Create the IOC application:

  Makefile.Vx contains statements like:

  >     SRCS.c += ../xxxRecord.c
  >     SRCS.c += ../devXxxSoft.c

  >     LIBOBJS += xxxRecord.o
  >     LIBOBJS += devXxxSoft.o
  >     LIBOBJS += sncExample.o

  >     include ../baseLIBOBJS

  >     LIBNAME = exampleLib
  >     INSTALLS += iocCore seq

  In Makefile these become:

  >     LIBRARY_vxWorks += exampleIoc
  >     exampleIoc_SRCS += xxxRecord.c
  >     exampleIoc_SRCS += devXxxSoft.c
  >     exampleIoc_LIBS += $(EPICS_BASE_IOC_LIBS)

  >     PROD_IOC_vxWorks = example
  >     example_SRCS += sncExample.st
  >     example_LIBS += exampleIoc
  >     example_LIBS += seq pv
  >     example_LIBS += $(EPICS_BASE_IOC_LIBS)

  >     # example_registerRecordDeviceDriver.cpp will be created from example.dbd
  >     example_SRCS += example_registerRecordDeviceDriver.cpp

  >     #The following adds support from base/src/vxWorks
  >     example_OBJS_vxWorks += $(EPICS_BASE_BIN)/vxComLibrary

After these changes are made the following files are no longer needed: baseLIBOBJS, Makefile.Host, and Makefile.Vx

### File base.dbd no longer needed

You now can add the line

>     include "base.dbd"

to your appnameInclude.dbd file and remove the file nameApp/src/base.dbd from your src directory. The base.dbd file from $(EPICS_BASE)/dbd will be used instead. If you only want to load a subset of the record definitions from base you can keep a local edited copy of the base.dbd file but you should copy it from $(EPICS_BASE)/dbd and edit that rather than trying to re-use the R3.13 version from your old application area.

### Record support

Add the following header file inclusion after all other `#include` statements:

>     #include "epicsExport.h"

The `struct rset` is now available as a typedef so change

>     struct rset recordnameRSET = { ... };

to

>     rset recordnameRSET = { ... };

and add the following line immediately after that definition:

>     epicsExportAddress(rset, recordnameRSET);

### Device support

Add the following header file inclusion after all other `#include` statements:

>     #include "epicsExport.h"

and add the following line after every dset definition `struct { ... } devname = { ... };` in the file.

>     epicsExportAddress(dset, devname);

### Driver support

Add the following header file inclusion after all other `#include` statements:

>     #include "epicsExport.h"

and add the following line after the `drvet drvname` definition:

>     epicsExportAddress(drvet, drvname);

### Registration code changed

Registration code for application specific functions, e.g. subroutine record init and process functions, must be changed as follows

1. Add the following header file inclusions after all other `#include` statements:

   >     #include "registryFunction.h"
   >     #include "epicsExport.h"

2. Mark the application specific functions as `static`, e.g.

   >     static long mySubInit(subRecord *precord)
   >     static long mySubProcess(subRecord *precord)

3. Add an `epicsRegisterFunction` statement for each of the functions to be registered, e.g.

   >     epicsRegisterFunction(mySubInit);
   >     epicsRegisterFunction(mySubProcess);

4. Add a function statement for each of the functions to be registered in a .dbd file that is included in the application, e.g.

   >     function("mySubInit")
   >     function("mySubProcess")

### Additional Headers

It may be necessary to add one or more of the following header file inclusions to any C source file if you get warnings or errors from the compilation process. The most likely file missing is errlog.h.

- `#include <stdarg.h>`
- `#include "errlog.h"`
- `#include "errMdef.h"`
- `#include "ellLib.h"`
- `#include "epicsTypes.h"`

### Modify the Makefiles in top/iocBoot directory.

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

If they do not already exist, add the lines

>     DIRS += $(wildcard *ioc*)
>     DIRS += $(wildcard as*)

Change `include $(TOP)/config/RULES.iocBoot` to `include $(TOP)/configure/RULES_DIRS`.

### Modify the Makefiles in top/iocBoot/ioc* directories.

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

Change

>     ARCH = <old arch specification e.g. mv167>

to

>     ARCH = <new arch specification e.g. vxWorks-68040>

Change `include $(TOP)/config/RULES.ioc` to `include $(TOP)/configure/RULES.ioc`

If it exists remove the line

>     buildInstall: cdCommands

Add the line

>     TARGETS = cdCommands

before the include for RULES.ioc line.

### Modify st.cmd in top/iocBoot/ioc* directories.

Remove the lines

>     ld < seq
>     ld < iocCore

The `ld` command in vxWorks 5.5.2 doesn't clean up its standard input stream properly, so we now recommend passing the filename to it as an argument instead. Change `ld < nameLib` to

>     ld 0,0, "name.munch"

Change `cd appbin` to `cd topbin`

Change the statement:

>     dbLoadDatabase("../../dbd/nameApp.dbd")

to

>     dbLoadDatabase("../../dbd/name.dbd")
>     name_registerRecordDeviceDriver(pdbbase)

where name is replaced with the name of your dbd file.

### recGbl calls

If any source file makes calls to recGbl routines make sure it includes `recGbl.h`. If it doesn't the compiler will issue warning messages and the IOC may not compile properly, or on vxWorks you could see the load-time error: undefined symbol: _recGblSetSevr.

### Record support changes

The steppermotor, scan, and pid records are no longer in base. If these record types are used at your site, their unbundled modules should be downloaded from the EPICS website and built with base R3.14 by your EPICS administrator. To use these record types in your application you must add them to the application just like any other external support module. Most modules provide instructions on how to use them in an IOC application.

Consider changing any existing old steppermotor records to the EPICS motor record module supported by the Beamline Controls and Data Acquisition group at APS.

### RecDynLink.o and devPtSoft changes

recDynLink.o and devPtSoft.o are no longer in EPICS base and now exist as separate unbundled EPICS modules. As with the three record types described above these must now be built separately and added as support modules to any applications that need them.

### 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. If these are not used by your application, remove any references to them from your dbd files.

Hardware support now exists as separate EPICS modules. The hardware support modules used at your site should be downloaded and built with base R3.14 by your EPICS administrator. To use them, add the appropriate module full path definitions to your application configure/RELEASE file, and make the documented changes to your Makefile to link their binaries into the your IOC executable.

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 configure/RELEASE file.

### dbLoadtemplate tool changes

The host tool dbLoadTemplate has been replace by a new EPICS extension called msi, which should be downloaded and built with base R3.14 by your EPICS administrator. dbLoadTemplate is still supported on IOCs. If the msi executable is not in your default search path and in your application db files are created from template and substitution files, you should add the definition

>     MSI = <full path name to msi executable>

to your application's configure/RELEASE file.

### Optional top/configure/CONFIG_SITE changes

Review and optionally modify site build settings.