Contents
Previous
Next
- <top>:
- An autonomously managed area which has a structure like that
created by makeBaseApp.
Autonomously managed means that each <top> can follow its
own release schedule.
The locations of software that a <top> uses from outside its
own area are specified in its config/RELEASE file. For example:
#RELEASE Location of external products
SUPPORT=/usr/local/iocapps/R3.13.1/support
TEMPLATE_TOP=$(EPICS_BASE)/templates/makeBaseApp/top
SHARE=$(SUPPORT)/share/1-1
MPF=$(SUPPORT)/mpf/1-1-asd1
EPICS_BASE=$(SUPPORT)/base/3-13-1-asd2
IMAGEFLOW=/net/phoebus/usr3/imageflow2.4/imageflow
MSITOP=/usr/local/epics/extensions
In the above example:
- IMAGEFLOW and MSITOP are obtained from outside the IOC
applications area.
- Release numbers such as 1-1-asd1 are explained later in
this document.
- The order of entries in the file is important when searching
include files. EPICS_BASE should usually be listed last to
allow other support areas to override its entries.
For ioc applications there are two flavors of <top>:
- <ioctop>
- A <top> area in which a set of related iocs are managed
and booted.
- <supporttop>
- A set of software meant to be used by one or more <ioctop>
s, e.g. device and driver support for a particular hardware interface
board, or a commonly used database template. See the
Support Management: Overview section for details.
It is expected that a small set of application engineers will be
responsible for a particular <ioctop>, and that the iocs in an
<ioctop> are responsible for a limited set of functions. If this
is done it is much easier to manage ioc applications.
<top>/
Makefile
config/
* CONFIG
* CONFIG_APP
Makefile
* RELEASE
RULES.Db
RULES.Host
RULES.Vx
RULES.ioc
RULES.iocBoot
RULES_ARCHS
RULES_DIRS
RULES_TOP
makeDbDepends.pl
makeIocCdCommands.pl
replaceVAR.pl
xxxApp/ or xxxapp
Makefile
src/ or xxxSrc/ or xxxsrc/
Makefile
* Makefile.Host
* Makefile.Vx
* base.dbd
* baseLIBOBJS
* <app>Include.dbd
* C and State Notation Language source
* menu, recordtype, device and driver database definitions
Db/ or db/ or xxxDb/ or xxxdb/
Makefile
* record instance files
* record template and substitution files
privately managed directories
iocBoot/ or iocboot/
Makefile
Makefile.Host
nfsCommands
iocxxx/
* Makefile
* st.cmd
$ cdCommands
$ dbd/
installed database description files
$ db/
installed record instance files
$ include/
installed include files
$ bin/
$ <host_arch>
installed Host executables
$ <ioc_arch>
installed IOC products
$ lib/
Files above marked "*" are user created and/or
edited. Each of these file types is discussed in this section.
Entries marked "$" are directories or files created by
gnumake. Since gnumake clean uninstall removes these files and
directories, no permanent data should be stored here.
The user-modifiable directories are:
- config
- Directory containing configuration files for gnumake.
- xxxApp
xxxapp
- Directory containing source files and database files. An arbitrary
number of xxxApp directories are allowed. Each must have
App or app appended to the name because the top-level
Makefile looks for this pattern.
- xxxsrc
xxxSrc
- Directory containing source files. An arbitrary number of source
directories can appear under each xxxApp. The names must have the
suffix src or Src. A source directory is where C
code, sequence programs, scripts, etc. are created and built.
- xxxdb
xxxDb
- Directory containing record instance files. An arbitrary number of
Db directories can exist under each xxxApp. The name must have the
suffix db or Db. Each Db directory can contain record
instance, template, and substitution files or the equivalent CapFast
schematics.
- iocBoot
iocboot
- Directory containing a subdirectory for each IOC.
- iocxxx
- Directory from which IOC iocxxx is booted. Each must have
ioc prepended to the name because iocBoot/Makefile looks
for it.
The following directories are created by gnumake to hold
built objects:
- dbd
- Installed Database Definitions Directory.
- include
- Include Directory. The directory in which include files generated
from menu and record type definitions are installed.
- bin
- Binaries Directory. This directory contains a subdirectory for the
host architecture and for each target architecture. These are the
directories in which executables, binaries, etc. are installed.
- lib
- Library Directory. This directory contains a subdirectory for the
host architecture and for each target architectiure. These are the
directories in which libraries are installed.
- db
- Installed Databases Directory. The directory into which record
instance, template and substitutions files are installed.
The makefiles are described in the section
Description of Makefiles.
These files contain definitions, make rules, and perl scripts used by
the various Makefiles in <top>. Please note that most
developers will only need to modify the files RELEASE and,
until release 3.13.2, CONFIG_APP.
The following describes the files generated by makeBaseApp using
either template simple or example. It is possible to create templates
for makeBaseApp that act differently.
- CONFIG
- This is the file in which you add to or modify make variables in
EPICS base. A useful definition to override is:
CROSS_COMPILER_TARGET_ARCHS =
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 variable with a subset of
the base target architectures will save build time.
If you are using capfast you may want to add the definition:
DB_OPT = YES
- CONFIG_APP
- This file contains definitions for external products such as EPICS
base and share. You should edit this file if you are using external
products besides epics_base and share. Follow the
models already in the file.
NOTE: Beginning with base release 3.13.2 the definitions that
previously had to be manually added to this file to support external
products will automatically be generated from the definitions in
RELEASE. This is done by gnumake which executes a new script
makeConfigAppInclude.pl. From 3.13.2 onwards therefor it will no
longer be necessary to edit this file.
- RELEASE
- This file specifies the location of external products such as
EPICS base. All entries in the RELEASE file must define a full path
name, either directly or using gnumake macro substitutions. The
procedures for going to a new release of an external product are
described later in this chapter. One step in those procedures is to
edit this file. The config files created by makeBaseApp provide support
for the following variables:
- SUPPORT
- This convenience (optional) variable is usually set to the top of
the directory tree holding support applications; succeeding definitions
are usually given relative to this.
- EPICS_BASE
- This variable must be defined, but usually as the last entry.
- TEMPLATE_TOP
- This variable specifies the location of the template top area for
makeBaseApp.
- RULES.Db
- This file contains rules for building and installing database
files. Databases generated from templates and/or CapFast schematics are
supported.
- RULES.Host
- The template file includes the RULES.Host from base. If
you want to add rules that apply to all Makefile.Host files
then this is the place to add the rules.
- RULES.Vx
- The template file includes the RULES.Vx from base. If you
want to add rules that apply to all Makefile.Vx files then
this is the place to add the rules.
- RULES.ioc
- This is a file containing rules for the Makefiles in the
directories from which IOCs are booted.
- RULES.iocBoot
- This is a file containing rules for the Makefiles in the iocBoot
directory. It should not be necessary to modify this file.
- RULES_ARCHS
- This file includes the RULES_ARCHS from base. It is
seldom necessary to modify this file.
- RULES_DIRS
- This file includes the RULES_DIRS from base. It is seldom
necessary to modify this file.
- RULES_TOP
- This file includes RULES_TOP from base. If
MASTER_IOCAPPS is defined it also runs a utility that creates soft
links to the master IOC. This feature only works if the host operating
system supports soft links.
- makeIocCdCommands.pl
- This is a perl script that generates a cdCommands file
for use by IOCs. See the section Component:
Directory Structure : cdCommands in this chapter for details.
- makeDbDepends.pl
- This is a perl script that generates make dependencies from
substitutions files.
- makeConfigAppInclude.pl
- Starting with release 3.13.2 this script will be provided. It
automatically generates the definitions which previously had to be
added to CONFIG_APP. It puts the definitions into a file
CONFIG_APP_INCLUDE.
- replaceVAR.pl
- This is a perl script that changes VAR(xxx) style macros
in CapFast generated databases into the $(xxx) notation used
in EPICS databases.
These files are used to configure database definitions for the
following:
- menus
- record types
- device support
- driver support
- breakpoint tables
base.dbd contains definitions obtained from the base release.
It contains statements 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 relevent lines.
A version of base.dbd appropriate to your version of EPICS
base can be obtained from
<epics_base>/templates/makeBaseApp/top/exampleApp/src.
The file <app>Include.dbd is used to construct a complete
list of definitions needed by the application. It must contain the line
include "base.dbd"
to incorporate all the definitions from base, followed by
any definitions needed for locally built support. The name of this file
is specified in the DBDEXPAND variable in Makefile.Host
. Then when gnumake is executed, a file with the name defined
by DBDNAME in Makefile.Host and having all of the
include statements expanded will be installed into <top>/dbd/.
This file lists all the compiled binary object files needed for the
record, device, and driver support supplied in EPICS base. 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 a series of 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
...
As with the base.dbd file, 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. These edits should match those made in the base.dbd
file, although no harm will usually come from uncommenting entries in
baseLIBOBJS that correspond to commented-out entries in
base.dbd, the effect is just to use up memory unnecessarily. The
reverse is not generally true, and this also assumes that there are no
references to the relevent record or device type in any database loaded
by the IOCs concerned.
Makefile.Vx contains rules that will combine all support
into a single module with a name given by the value of LIBNAME
.
NOTE: A version of baseLIBOBJS can be obtained from
<epics_base>/templates/makeBaseApp/top/exampleApp/src
APOLOGY: It would be nice if this file could be
automatically generated from the information in the expanded dbd file
described above. This is not currently possible because there is no
naming convention for device and driver support source files.
The vxWorks startup file is described in a later section.
This file is automatically generated within each
<top>/iocBoot/iocxxx directory by gnumake executing
makeIocCdCommands.pl. When this cdCommands script is called by
st.cmd it generates a series of vxWorks shell string variables for
use with the vxWorks cd command. For example the subsequent
line in st.cmd
cd startup
will change to the directory containing the st.cmd
file. The perl script used differs between releases 3.13.1 and 3.13.2.
The following describes the variables generated for each release
- startup
- The full path to the directory containing the startup file.
- appbin
- The full path to <top>/bin/<ioc_arch>
- share
- If SHARE is defined in <top>/config/RELEASE this
gives the full path to share
- top
- The full path to <top>
- startup
- The full path to the directory containing the startup file.
- topbin
- The full path to <top>/bin/<ioc_arch>
In addition, for each external <top> listed in
<top>/config/RELEASE via an entry "<PROD>=<path>" the
following variables are also created:
- <prod>
- The full path <path> to the product if the the directory
actually exists
- <prod>bin
- The full path to <path>/bin/<ioc_arch> if this directory
exists.
Thus in 3.13.2 it is easy to get to the <prod> and
<prod>/bin/<ioc_arch> directories of all external products
specified in <top>/config/RELEASE. Once at the top of a
product its db and dbd subdirecties can be accessed
by using relative pathnames.
The structure of <top> is designed to make it easy to link to
other <top> areas, each with it's own release schedule. The
basic methods that make this possible are:
- A <supporttop> installs its public components into
standard subdirectories. For example all executables are stored into
<supporttop>/bin/<arch>.
- To use components from another <supporttop> in any
<top> do the following:
- Add a line to <top>/config/RELEASE defining the external
product's location, eg:
MYPROD = $(SUPPORT)/myprod/1-3
- If using EPICS releases before 3.13.2, add definitions to
<top>/config/CONFIG_APP. For example:
ifdef MYPROD
MYPROD_BIN = $(MYPROD)/bin/$(T_A)
USR_INCLUDES += -I$(MYPROD)/include
USER_DBDFLAGS += -I $(MYPROD)/dbd
endif
From release 3.13.2 onwards, executing gnumake in the
config directory performs an equivalent step.
- In one or more of the <top>'s source and database
directories reference components from the <supporttop> as
required. These references can take the following forms:
- #include statements used in C and C++ source code will
search the <supporttop>/include directory for any installed
header files
- include statements found while expanding an
<app>Include.dbd file will search the <supporttop>/dbd
directory for the installed dbd files named.
- Compiled object files from a <supporttop>/bin/<arch>
directory can be linked into an xxxLib object library by
adding the object filename to the definition of LIBOBJS in
Makefile.Vx using statements like:
LIBOBJS += $(MYPROD_BIN)/myprod.o
- From release 3.13.2 the automatically generated cdCommands
file in each iocBoot/iocxxx directory defines string
constants which can be used in the st.cmd file to cd
to the top and bin/<arch> directories of any <supporttop>
defined in <top>/config/RELEASE. For example:
cd myprod
dbLoadRecords("db/myprod.db","ioc=prod1")
- A full description on how to use an external <supporttop>
module in an application should form part of the module's
documentation, which may over-ride some of the above instructions. If
such documentation is not provided, ask the module maintainer why not.
The file <top>/config/RELEASE contains definitions for
components obtained from 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 config/RELEASE
change the relevent line to point to the new release
gnumake
All definitions in <top>/config/RELEASE must
result in complete path definitions, i.e. relative path names are not
permitted. If your site could have multiple releases of base and other
<supporttop> components installed at once, these path definitions
should contain a release number as one of the components. However as
the RELEASE file is read by gnumake, it is permissible to use
macro substitutions to define these pathnames, for example:
SUPPORT = /usr/local/iocapps/R3.13.1
EPICS_BASE = $(SUPPORT)/base/3-13-1-asd2
Contents
Previous
Next