Contents
Previous
Next
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.
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
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.
- 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.
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.
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.
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