6. Creating `<top>` Applications

6.1. makeBaseApp

makeBaseApp is a perl script that creates application areas. It can create the following:

<top>/Makefile
<top>/config - Build configuration subdirectory and associated files
<top>/xxxApp - A set of directories and associated files for a major sub-module.
<top>/iocBoot - A subdirectory and associated files.
<top>/iocBoot/iocxxx - A subdirectory and files for a single ioc.

makeBaseApp creates directories and then copies template files into the newly created directories while expanding macros in the template files. EPICS base provides two sets of template files: simple and example. These are meant for simple applications. Each site, however, can create its own set of template files which may provide additional functionality. This section describes the functionality of makeBaseApp itself, the next section provides details about the simple and example templates.

Usage

makeBaseApp has three possible forms of command line:

<base>/bin/<arch>/makeBaseApp.pl -l [options]: List the application templates available. This invocation does not alter the current directory.
<base>/bin/<arch>/makeBaseApp.pl [-t type] [options] app ...: Create application directories.
<base>/bin/<arch>/makeBaseApp.pl -i [options] ioc ...: Create ioc boot directories.

Options for all command forms:

-b base: Provides the full path to EPICS base. If not specified, the value is taken from the EPICS_BASE entry in config/RELEASE. If the config directory does not exist, the path is taken from the command-line that was used to invoke makeBaseApp.
-T template: Set the template top directory (where the application templates are). If not specified, the template path is taken from the TEMPLATE_TOP entry in config/RELEASE. If the config directory does not exist the path is taken from the environment variable EPICS_MBA_TEMPLATE_TOP, or if this is not set the templates from EPICS base are used.
-d: Verbose output (useful for debugging)

Arguments unique to makeBaseApp.pl [-t type] [options] app ... :

app: One or more application names (the created directories will have "App" appended to this name)
-t type: Set the template type (use the -l invocation to get a list of valid types). If this option is not used, type is taken from the environment variable EPICS_MBA_DEF_APP_TYPE, or if that is not set the values "default" and then "example " are tried.

Arguments unique to makeBaseApp.pl -i [options] ioc ...:

ioc: One or more IOC names (the created directories will have "ioc " prepended to this name)
-a <arch>: Set the IOC architecture (e.g. mv167). If not specified you will be prompted for this information. For use with the -i invocation only.

Environment Variables:

EPICS_MBA_DEF_APP_TYPE: Application type you want to use as default
EPICS_MBA_TEMPLATE_TOP: Template top directory

Description

To create a new <top> issue the commands:

mkdir <top>
cd <top>
<base>/bin/<arch>/makeBaseApp.pl -t <type> <app> ...
<base>/bin/<arch>/makeBaseApp.pl -i -t <type> <ioc> ...

makeBaseApp does the following:

EPICS_BASE is located by checking the following in order:
- If the -b option is specified it is used.
- If a <top>/config/RELEASE file exists and defines a value for EPICS_BASE it is used.
- It is obtained from the invocation of makeBaseApp. For this to work, the full path name to the makeBaseApp.pl script in the EPICS base release you are using must be given.
TEMPLATE_TOP is located in a similar fashion:
- If the -T option is specified it is used.
- If a <top>/config/RELEASE file exists and defines a value for TEMPLATE_TOP it is used.
- If EPICS_MBA_TEMPLATE_TOP is defined it is used.
- It is set equal to <epics_base>/templates/makeBaseApp/top
If -l is specified the list of application types is listed and makeBaseApp terminates.
If -i is specified and -a is not then the user is prompted for the IOC architecture.
The application type is determined by checking the following in order:
- If -t is specified it is used.
- If EPICS_MBA_DEF_APP_TYPE is defined it is used.
- If a template defaultApp exists, the application type is set equal to default.
- If a template exampleApp exists, the application type is set equal to example.
If the application type is not found in TEMPLATE_TOP, makeBaseApp issues an error and terminates.
If Makefile does not exist, it is created.
If directory config does not exist, it is created and populated with all the config files.
If -i is specified:
- If directory iocBoot does not exist, it is created and the files from the template boot directory are copied into it.
- For each <ioc> specified on the command line a directory iocBoot/ioc<ioc> is created and populated with the files from the template (with ReplaceLine() tag replacement, see below).
If -i is NOT specified:
- For each <app> specified on the command line a directory <app>App is created and populated with the directory tree from the template (with ReplaceLine() tag replacement, see below).

Tag Replacement within a Template

When copying certain files from the template to the new application structure, makeBaseApp replaces some predefined tags in the name or text of the files concerned with values that are known at the time. An application template can extend this functionality as follows:

Two perl subroutines are defined within makeBaseApp:
- ReplaceFilename - This substitutes for the following in names of any file taken from the templates.
  - _APPNAME_
  - _APPTYPE_
- ReplaceLine - This substitutes for the following in each line of each file taken from the templates:
  - _USER_
  - _EPICS_BASE_
  - _ARCH_
  - _APPNAME_
  - _APPTYPE_
  - _TEMPLATE_TOP_
  - _IOC_
If the application type directory has a file named Replace.pl , it can:
- Replace one or both of the above subroutines with its own versions.
- Add a subroutine ReplaceFilenameHook($file) which is called at the end of ReplaceFilename.
- Add a subroutine ReplaceLineHook($line) which is called at the end of ReplaceLine.
- Include other code which is run after the command line options are interpreted.

6.2. Application Templates Supplied With Base

EPICS base supplies the following sets of template files

exampleApp
exampleBoot
simpleApp
simpleBoot

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.

6.3. Example Application

exampleApp and exampleBoot create a complete example application. They contain the following files.

<app>App
    src/
        Makefile
        Makefile.Host
        Makefile.Vx
        caExample.c
        sncExample.st
        xxxRecord.dbd
        xxxRecord.c
        devXxxSoft.c
        <app>Include.dbd
        base.dbd
        baseLIBOBJS
    Db/
        Makefile
        Makefile.Host
        dbExample1.db
        dbExample2.template
        dbExample2.substitutions

iocBoot/
    Makefile
    nfsCommands
    ioc<app>
        Makefile
        st.cmd

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:

On the IOC console type the command:
```
dbl
```
This produces a list of all the records the IOC contains.
On the host system change to the directory: <top>/bin/<host_arch>/
Execute the command:
```
caExample "pvname"
```
where pvname is one of the record names shown by dbl

dbExample1.db

This is a file containing some example record instances. Each name starts with $(user), which will be expanded into the login name of the person who executed makeBaseApp at database load time. The records are:

$(user)aiExample

A passive ai (analog input) record which obtains its input from record $(user)calcExample.

$(user)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 $(user)aiExample. Since the latter is passive it will also scan once a second.

$(user)xxxExample

This is a sample record of type xxx, as described below. It is a passive record. You can change its VAL field from a Channel Access client or by using the IOC command dbpf.

dbExample2.template
dbExample2.substitutions

This is another example of record instances. The record instance file is generated from a template, which is instantiated using the entries in the substitutions file. Each record name in the template file starts with $(USER), which is replaced by the login name of the person who executed makeBaseApp when the template is instantiated at build time. Each line in the substitutions file creates a two record database, whose records are described above (aiExample and calcExample).

sncExample.st

This is a state notation language example for compilation by the state notation compiler and execution on the IOC by sequencer. It prints a message on the IOC console every time the VAL field of the record <user>xxxExample transits through the value 5.0. This time the <user> part of this record name is instantiated when the template is created by makeBaseApp.

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.

6.4. st.cmd

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

# Example vxWorks startup file
#Following must be added for many board support packages
#cd <full path to iocxxx>
< cdCommands

#< nfsCommands

cd appbin
ld < iocCore
ld < seq
ld < exampleLib

cd startup
dbLoadDatabase("../../dbd/exampleApp.dbd")
dbLoadRecords("../../db/dbExample1.db","user=<user>")
dbLoadRecords("../../db/dbExample2.db")

iocInit
seq &snctest

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

The cdCommands file is created when gnumake is run, and defines several vxWorks variables for use with cd later on in the startup file. Definitions are provided for:

appbin - A full path name to <top>/bin/<target_arch>
startup - A full path name to <top>/iocBoot/iocxxx
share - A full path name to share if SHARE is defined in <top>/config/RELEASE

NOTE: From release 3.13.2 the name appbin becomes topbin . Other definitions are also created by cdCommands. See the description of <top>/iocBoot/iocxxx/Makefile in section 4.3 for details.

The first ld command loads the core EPICS components. The files iocCore, seq and exampleLib are installed when gnumake is run in the <top>/xxxApp/src directory. exampleLib 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/dbExample1.db","user=<user>")

is an example command for loading record instances using macro substitution at load time. One of these commands is supplied for each record instance file. Note that the <user> parameter in the example will have been replaced by the login name of the person running makeBaseApp.

The iocInit command initializes the EPICS system.

The seq command shows how to start a sequence (state notation language) program.

Contents Previous Next

6. Creating <top> Applications