2288 lines
87 KiB
HTML
2288 lines
87 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (X11; U; SunOS 5.5.1 sun4u) [Netscape]">
|
|
<TITLE>EPICS: IOC Applications: Building and Source Release Control</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<CENTER>
|
|
<H1>
|
|
EPICS IOC Applications<BR>
|
|
Building <BR>
|
|
and <BR>
|
|
Source Release Control</H1></CENTER>
|
|
|
|
<CENTER>
|
|
<H2>
|
|
Marty Kraimer, Janet Anderson , and Ralph Lange<BR>
|
|
June 15, 1998 <BR>
|
|
EPICS Release 3.13.0.beta12</H2></CENTER>
|
|
|
|
<CENTER>
|
|
<H2>
|
|
Changes since beta11</H2></CENTER>
|
|
Between release 3.13.0.beta11 and 3.13.0.beta12 makeBaseApp was changed
|
|
from one very long perl script to a four page perl script plus template
|
|
files. It supports templates in addition to those supplied with EPICS base.
|
|
Other improvements were made including support for capfast. The primary
|
|
developer of the new version of makeBaseApp was Ralph Lange (BESSY). Rozelle
|
|
Wright (LANL) and Thomas Birke (BESSY) contributed to this development.
|
|
In addition no soft links are required so that makeBaseApp works on winXX
|
|
hosts.
|
|
<CENTER>
|
|
<H2>
|
|
Quick Start</H2></CENTER>
|
|
If you are new to EPICS or are trying a new release, then follow the instructions
|
|
in section <A HREF="#QuickStart">Quick Start</A>. Look at all the files
|
|
that are generated. They give examples of how to manage each of the IOC
|
|
components.
|
|
<BR>
|
|
<CENTER>
|
|
<H2>
|
|
Index</H2></CENTER>
|
|
|
|
<UL>
|
|
<LI>
|
|
<A HREF="#Overview">Overview</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#QuickStart">Quick Start</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#Introduction">Introduction</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#DirectoryStructure">Directory Structure</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#makeBaseApp">makeBaseApp</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#Templates Supplied with base">Application Templates Supplied
|
|
with base</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#ST.CMD">st.cmd</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#SwitchNewRelease">Switching to a new Release</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#MAKE">Make</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#makeFiles">Description of Makefiles</A></LI>
|
|
|
|
<LI>
|
|
<A HREF="#CVS">CVS</A></LI>
|
|
</UL>
|
|
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="Overview"></A>Overview</H2></CENTER>
|
|
Several EPICS Application Source/Release systems are available. Your site
|
|
may have adapted one of them. Consult your EPICS system manager. This manual
|
|
describes procedures that can be used for simple or complicated applications.
|
|
<BR>
|
|
|
|
<P>This document describes how to create and build IOC applications. This
|
|
includes:
|
|
<UL>
|
|
<LI>
|
|
IOC databases.</LI>
|
|
|
|
<LI>
|
|
vxWorks startup files.</LI>
|
|
|
|
<LI>
|
|
State Notation Programs.</LI>
|
|
|
|
<LI>
|
|
New record types, device support, drivers.</LI>
|
|
|
|
<LI>
|
|
Access security configuration files.</LI>
|
|
|
|
<LI>
|
|
Other code to be executed in an IOC.</LI>
|
|
|
|
<LI>
|
|
Special Host code.</LI>
|
|
</UL>
|
|
In addition procedures are described for managing large applications. The
|
|
principle features are:
|
|
<UL>
|
|
<LI>
|
|
All editable files are placed under CVS control.</LI>
|
|
|
|
<LI>
|
|
The complete set of operational IOC software can be stored under a single
|
|
operations directory structure.</LI>
|
|
|
|
<LI>
|
|
The IOC software is divided into <<TT>top</TT>> areas. Each <<TT>top</TT>>
|
|
is maintained separately. Different <<TT>top</TT>> areas can be on different
|
|
releases of external software such as EPICS base releases.</LI>
|
|
|
|
<LI>
|
|
Support such as special record/device/driver support can be shared across
|
|
<<TT>top</TT>> areas. This is done by having a special <<TT>top</TT>>
|
|
called <TT>share</TT>. <TT>share</TT> is built and made into releases.
|
|
Other <<TT>top</TT>> areas attach to releases of <TT>share</TT>.</LI>
|
|
|
|
<LI>
|
|
Access security configuration files can be shared across <<TT>top</TT>>
|
|
areas. This is done by having a special <<TT>top</TT>> area called <TT>ascf</TT>.
|
|
Normally this would not be made into releases since it must be easily modified
|
|
by operations. The ascf directory <B>MUST</B> reside in the same directory
|
|
as the <<TT>top</TT>> areas that use it.</LI>
|
|
|
|
<LI>
|
|
Each application developer makes changes in a private copy of one or more
|
|
<<TT>top</TT>> areas.</LI>
|
|
|
|
<LI>
|
|
<TT>cvs</TT> and <TT>gnumake</TT> are the only tools users execute to build
|
|
applications.</LI>
|
|
|
|
<LI>
|
|
Templates are provided for creating new application directories. EPICS
|
|
base provides two sets of templates: simple and example. Additional templates
|
|
can be created.</LI>
|
|
</UL>
|
|
|
|
<H3>
|
|
User Prerequisites</H3>
|
|
This manual assumes that the reader:
|
|
<UL>
|
|
<LI>
|
|
Understands the C language</LI>
|
|
|
|
<LI>
|
|
Knows how to use a text editor</LI>
|
|
|
|
<LI>
|
|
Has at least a superficial knowledge of the make utility</LI>
|
|
</UL>
|
|
|
|
<H3>
|
|
System Prerequisites</H3>
|
|
Before you can generate EPICS IOC applications your host and/or EPICS system
|
|
manager must have done the following:
|
|
<UL>
|
|
<LI>
|
|
Installed vxWorks and a board support package. Consult the vxWorks documentation
|
|
for details.</LI>
|
|
|
|
<LI>
|
|
Installed EPICS base. This can be a specific EPICS release or the master
|
|
EPICS tree.</LI>
|
|
</UL>
|
|
|
|
<H3>
|
|
Make vs. Gnumake</H3>
|
|
EPICS provides an extensive set of make rules. These rules only work with
|
|
the GNU version of make, gnumake, which is supplied by the Free Software
|
|
Foundation. Thus, on most Unix systems, the native make will not work.
|
|
On some systems, e.g. Linux, GNU make may be the default. This manual always
|
|
uses gnumake in the examples.
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="QuickStart"></A>Quick Start</H2></CENTER>
|
|
This section explains how to quickly create an example IOC application
|
|
in a directory <B><top></B> and named <B>example</B>.
|
|
<H3>
|
|
Check Environment</H3>
|
|
Execute the command:
|
|
<PRE>echo $HOST_ARCH</PRE>
|
|
This should display your workstation architecture.
|
|
<H3>
|
|
Create example Application</H3>
|
|
Execute the commands:
|
|
<PRE>mkdir <top>
|
|
cd <top>
|
|
<base>/bin/<arch>/makeBaseApp.pl -t example example
|
|
<base>/bin/<arch>/makeBaseApp.pl -i -t example example</PRE>
|
|
where:
|
|
|
|
<P><TT><top> </TT>- Any directory name you chose.
|
|
<BR><TT><base></TT> - Full path name to EPICS base.
|
|
<BR><TT><arch></TT> - Your host architecture.
|
|
|
|
<P>For example at ANL/APS the following commands create an application:
|
|
<PRE>cd
|
|
mkdir myapp
|
|
cd myapp
|
|
/usr/local/epics/baseR3.13.0.beta12/bin/solaris/makeBaseApp.pl -t example example
|
|
/usr/local/epics/baseR3.13.0.beta12/bin/solaris/makeBaseApp.pl -i -t example example</PRE>
|
|
|
|
<H3>
|
|
Inspect Files</H3>
|
|
Spend some time looking at the files that appear under <TT><top>.</TT>
|
|
Do this <B>BEFORE</B> building.
|
|
<H3>
|
|
Build</H3>
|
|
In directory <top> execute the command:
|
|
<PRE>gnumake</PRE>
|
|
|
|
<H3>
|
|
Inspect Files</H3>
|
|
Again look at all the files that appear under <TT><top></TT>.
|
|
<H3>
|
|
Boot Parameters</H3>
|
|
The next step is to set the IOC boot parameters via the console serial
|
|
port on your IOC. Life is much easier if you find out how to connect the
|
|
serial port to a window on your workstation. See your EPICS system manager
|
|
for details.
|
|
|
|
<P>The vxWorks boot parameters look something like the following:
|
|
<PRE>boot device : xxx
|
|
<TT>processor number : 0
|
|
host name : xxx
|
|
file name : <top>/bin/<target_arch>/vxWorks
|
|
inet on ethernet (e) : xxx.xxx.xxx.xxx:<netmask>
|
|
inet on backplane (b):
|
|
host inet (h) : xxx.xxx.xxx.xxx
|
|
gateway inet (g) :
|
|
user (u) : xxx
|
|
ftp password (pw) (blank = use rsh): xxx
|
|
flags (f) : 0x0
|
|
target name (tn) : <hostid for channel access security>
|
|
startup script (s) : <top>/iocBoot/iocexample/st.cmd
|
|
other (o) :</TT></PRE>
|
|
The actual values for each field are site and IOC dependent. Consult your
|
|
EPICS system manager for help. Two fields that you can change at will are
|
|
the vxWorks boot image and the location of the startup script.
|
|
<H3>
|
|
Boot</H3>
|
|
You are now ready to boot your IOC. If your boot parameters are defined
|
|
properly, just press the reset button on your IOC. You will find it VERY
|
|
convenient to have the console port of the IOC attached to a scrolling
|
|
window on your workstation.
|
|
<H3>
|
|
Test</H3>
|
|
See the description of the example given in section <A HREF="#Templates Supplied with base">Templates
|
|
Supplied with base</A>. Also try some of the vxWorks shell commands described
|
|
in chapter "IOC Test Facilities" of the Application Developer's Guide.
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="Introduction"></A>Introduction</H2></CENTER>
|
|
|
|
<H3>
|
|
Background</H3>
|
|
Before EPICS base release 3.13, APS/ASD used an Application Source Release
|
|
control system called appSR. appSR uses sccs for source file control. Since
|
|
appSR was written several things that impact S/R control have changed.
|
|
<UL>
|
|
<LI>
|
|
With release 3.13 the method of configuring record/device/driver support
|
|
changed.</LI>
|
|
|
|
<LI>
|
|
Both EPICS base and extensions have switched from sccs to <TT>cvs</TT>.</LI>
|
|
|
|
<LI>
|
|
<TT>base/config</TT>, i.e. definitions and rules for GNU make, has evolved
|
|
so that is now possible to create makefiles that are much simpler, more
|
|
powerful, and extendable.</LI>
|
|
</UL>
|
|
For the above reasons we decided to redo the APS/ASD IOC Applications S/R
|
|
control system. Our goals were:
|
|
<UL>
|
|
<LI>
|
|
SCCS will go away.</LI>
|
|
|
|
<LI>
|
|
All functionality performed by appSR will be done via <TT>cvs</TT> and
|
|
GNU make.</LI>
|
|
</UL>
|
|
A major decision is <I>What Directory Structure should we use</I>. Before
|
|
the original appSR was written a <B>lot</B> of discussion went into this
|
|
topic. There were several meetings between the Application Developers and
|
|
Bob Zieman, who implemented appSR. This directory structure was used to
|
|
implement the entire APS/ASD contol system software. Thus a lot of correct
|
|
decisions were made. The only major problem is that it was not easy to
|
|
share code, mainly record/device/driver support, across <<TT>top</TT>>
|
|
areas. This resulted in sharing by copying source modules from one <<TT>top</TT>>
|
|
area to another. When one developer would make changes to a source module,
|
|
the other developers would often not even be aware of the changes. Thus
|
|
over time the source modules evolved in different directions.
|
|
|
|
<P>Since the overall directory layout appears to be correct, it is kept
|
|
in the new system. A brief description of the APS/ASD environment may help
|
|
explain why the directory layout works.
|
|
<UL>
|
|
<LI>
|
|
APS accelerator.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
The APS accelerator complex is composed of four major subsystems: Linac,
|
|
PAR (Positron Accumulator Ring), Booster Syncrotron, and Storage Ring.
|
|
Each subsystem is controlled by a separate set of IOCs. Thus it is entirely
|
|
appropriate to have separate <<TT>top</TT>> areas for each subsystem.</LI>
|
|
|
|
<LI>
|
|
Each subsystem can be viewed as a separate set of applications, e.g. RF,
|
|
Magnet Power Supplies, Diagnostics, etc.</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
IOC responsibilities.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
A particular application may be spread over multiple IOCs. For example
|
|
the control for storage ring applications is normally spread over many
|
|
IOCs just because of the size of the storage ring.</LI>
|
|
|
|
<LI>
|
|
A particular IOC may contain parts of multiple applications. For example
|
|
vacuum and power supplies normally share IOCs.</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
Application Developers.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
For the Linac, a single Application Developer has final responsibility
|
|
for all controls applications, i.e. RF, vacuum, Diagnostics, etc.</LI>
|
|
|
|
<LI>
|
|
For the par, booster, and sr, Application Developers are assigned application
|
|
areas. For example the same person is responsible for almost all diagnostic
|
|
controls for the par, booster, and storage ring.</LI>
|
|
</UL>
|
|
</UL>
|
|
One other topic to discuss before describing the overall directory structure
|
|
is the <I>idealized</I> Application Development Cycle. It consists of the
|
|
following steps:
|
|
<OL>
|
|
<LI>
|
|
Define I/O requirements.</LI>
|
|
|
|
<BR>This involves meeting with the user, in this case the engineers who
|
|
are responsible for the application in order to decide the types and number
|
|
of I/O modules needed.
|
|
<LI>
|
|
Assemble control hardware and software.</LI>
|
|
|
|
<BR>This includes IOCs, I/O modules, software device/driver support, etc.
|
|
If EPICS software support is not already available, it has to be written
|
|
and tested.
|
|
<LI>
|
|
Build databases, sequence programs, etc.</LI>
|
|
</OL>
|
|
In reality there is overlap between these steps. In addition as new needs
|
|
arise the three steps again have to be performed. However, an application
|
|
developer tends to spend a large part of his/her attention on each step
|
|
before moving on to the next step.
|
|
|
|
<P>The application structure described in the next section is designed
|
|
to meet these needs.
|
|
<H3>
|
|
Overview of Application Source Release Control</H3>
|
|
The application directory structure appears as follows:
|
|
<PRE> <top>/
|
|
config/
|
|
xxxApp/
|
|
src/
|
|
xxxSrc/
|
|
...
|
|
Db/
|
|
xxxDb/
|
|
...
|
|
xxxApp/
|
|
...
|
|
iocBoot/
|
|
iocxxx/
|
|
...
|
|
bin/
|
|
<host_arch>
|
|
<target_arch>
|
|
...</PRE>
|
|
Each <<TT>top</TT>> area is a separately managed set of applications.
|
|
Separately managed means that each <<TT>top</TT>> can be using it's
|
|
own release of software obtained from outside the application, e.g. a release
|
|
of EPICS base.
|
|
|
|
<P>Within a <<TT>top</TT>> area, multiple xxxApp subdirectories and
|
|
a single iocBoot directory appear. The xxxApp areas are created by application
|
|
developers as needed. The iocBoot directory contains a subdirectory for
|
|
each IOC that belongs to that <<TT>top</TT>> area. No IOC belongs to
|
|
more than one <<TT>top</TT>> area. All software components needed by
|
|
IOCs are built in the xxxApp directories. Each IOC is booted from <TT>bin/<target_arch>
|
|
</TT>(actually from any directory containing a vxWorks and vxWorks.sym
|
|
compatible with the version of vxWorks against which the target was built)
|
|
and uses a startup file from a subdirectory under iocBoot. The only important
|
|
source file in a boot directory is the <TT>st.cmd</TT> file which is executed
|
|
after vxWorks is started on an IOC. The <TT>st.cmd </TT>file loads various
|
|
files built in the xxxApp directories.
|
|
|
|
<P>Application developers decide what constitutes a <<TT>top</TT>>.
|
|
For example, at APS, the Linac is completely contained in a single <<TT>top</TT>>
|
|
area, while the RF is spread over three <<TT>top</TT>> areas: parrf,
|
|
boosterrf, and srrf. No <<TT>top</TT>> area, however, contains iocxxx
|
|
directories from multiple subsystems.
|
|
|
|
<P>Now lets describe how the application developers use the above structure.
|
|
|
|
<P>Under xxxApp are source and database directories. A source directory
|
|
contains source files for building executables and database description
|
|
files. Makefiles specify what to build. These makefiles can specify components
|
|
obtained from outside the <<TT>top</TT>> area, such as EPICS base. After
|
|
modifing files in this directory the command:
|
|
<PRE> gnumake</PRE>
|
|
will rebuild components that depend on the modified files. (It will be
|
|
seen below that the generated components are actually copied to an install
|
|
directory)
|
|
|
|
<P>The database directories contain IOC database files and/or template
|
|
and substitution files used to generate database files. If templates are
|
|
used then whenever a template or substitution file is modified the command
|
|
<TT>gnumake</TT> will recreate the database file(s).
|
|
|
|
<P>After changes are made in any xxxApp directory, the affected IOCs can
|
|
be rebooted from the appropriate iocBoot subdirectory. If new components
|
|
are added, it may be necessary to modify st.cmd files.
|
|
<H3>
|
|
share</H3>
|
|
As mentioned above the one major defect with the old appSR system is that
|
|
there was no easy way to share code across <<TT>top</TT>> areas. To
|
|
solve this problem a new <<TT>top</TT>> area called <TT>share</TT> is
|
|
present. It is structured somewhat differently than other <<TT>top</TT>>
|
|
areas, but development in it is done just like in any other <<TT>top</TT>>.
|
|
Releases of <TT>share</TT> are created. A release contains built and installed
|
|
object modules. Other <<TT>top</TT>> areas take things from releases
|
|
of <TT>share</TT> rather then from <TT>share</TT> itself.
|
|
|
|
<P>At aps the releases of <TT>share</TT>, which are dependent on releases
|
|
of EPICS base, are named:
|
|
<PRE> baseXXXshareYYY</PRE>
|
|
where XXX is the EPICS base release and YYY is a release of <TT>share</TT>
|
|
for that base release. At aps the <TT>share</TT> releases are stored at
|
|
locations:
|
|
<PRE> /usr/local/iocapps/iocsys/baseXXXshareYYY</PRE>
|
|
If it is necessary to obtain a bug fix or enhancement to a single module
|
|
from EPICS base or a <TT>share</TT> release, the application developer
|
|
has at least two choices. The first is to build a new release of base or
|
|
<TT>share</TT>. A second choice is to copy the source module to an appropriate
|
|
<TT>src</TT> directory and build it there. In this case the developer must
|
|
remember to use the version from <TT>share</TT> after <TT>share</TT> is
|
|
rebuilt.
|
|
|
|
<P><B>Note: </B>Other software packages can be handled like <TT>share</TT>.
|
|
<H2>
|
|
templates</H2>
|
|
The makeBaseApp.pl utility creates new application areas. It does this
|
|
by copying and transforming directory trees from a template area. EPICS
|
|
base provides templates for a simple application and for an example application.
|
|
Each site can, however, create their own set of templates.
|
|
<H3>
|
|
Tools</H3>
|
|
The following tools are used:
|
|
<UL>
|
|
<LI>
|
|
<TT>cvs</TT></LI>
|
|
|
|
<LI>
|
|
<TT>gnumake</TT> - GNU make plus EPICS supplied configuration definitions,
|
|
make rules, and script files.</LI>
|
|
</UL>
|
|
|
|
<H3>
|
|
Classes of Users</H3>
|
|
|
|
<DL>
|
|
<DT>
|
|
<B>Application System Manager </B>:</DT>
|
|
|
|
<DD>
|
|
The Application System Manager is responsible for the Operations Area.</DD>
|
|
|
|
<DT>
|
|
<B>Application Developer </B>:</DT>
|
|
|
|
<DD>
|
|
Anyone who tests, modifies, or extends an application's software. If multiple
|
|
developers are working on the same system each should develop in a private
|
|
development area.</DD>
|
|
</DL>
|
|
|
|
<H3>
|
|
References</H3>
|
|
Version Management with CVS for CVS 1.9, Per Cederqvist et al.
|
|
|
|
<P>GNU Make, Edition .51 for make Version 3.75 Beta, May 1996, Richard
|
|
M. Stallman and Ronald McGrath
|
|
|
|
<P>EPICS: Application Developer's Guide R3.13, Marty Kraimer
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="DirectoryStructure"></A>Directory Structure</H2></CENTER>
|
|
|
|
<H3>
|
|
Structure</H3>
|
|
|
|
<PRE> <top>/
|
|
Makefile
|
|
config/
|
|
* CONFIG
|
|
* CONFIG_APP
|
|
* 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
|
|
src/ or xxxSrc or xxxsrc
|
|
Makefile
|
|
* Makefile.Host
|
|
* Makefile.Vx
|
|
* base.dbd
|
|
* baseLIBOBJS
|
|
* <app>Include.dbd
|
|
* <source code>
|
|
* <state programs>
|
|
* < menu, recordtype, device, driver database defs>
|
|
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/</PRE>
|
|
Files marked with an "*" are user created and/or edited. Each such file
|
|
is discussed in this section.
|
|
|
|
<P>Files marked with "**" are directories created by gnumake. Since <TT>gnumake
|
|
uninstall</TT> removes all files in these directories, no permanent files
|
|
should be created in these directories.
|
|
<H3>
|
|
Directories</H3>
|
|
The directories are:
|
|
<DL>
|
|
<DT>
|
|
<TT>config</TT></DT>
|
|
|
|
<DD>
|
|
Directory containing configuration files for gnumake.</DD>
|
|
|
|
<DT>
|
|
<TT>xxxApp or xxxapp</TT></DT>
|
|
|
|
<DD>
|
|
Directory containing source files and database files. An arbitrary number
|
|
of <TT>xxxApp</TT> directories are allowed. Each must have <TT>App</TT>
|
|
or <TT>app </TT>appended to the name because Makefile looks for it.</DD>
|
|
|
|
<DL>
|
|
<DT>
|
|
<TT>xxxsrc</TT> or <TT>xxxSrc</TT></DT>
|
|
|
|
<DD>
|
|
Directory containing source files. An arbitrary number of source directories
|
|
can appear under each xxxApp. The names must have the suffix <TT>src</TT>
|
|
or <TT>Src</TT>. A source directory is where C code, sequence programs,
|
|
scripts, etc. are created and built.</DD>
|
|
|
|
<DT>
|
|
<TT>xxxdb </TT>or<TT> xxxDb</TT></DT>
|
|
|
|
<DD>
|
|
Directory containing record instance files. An arbitrary number of Db directories
|
|
can exist under each xxxApp. The name must have the suffix <TT>db </TT>or
|
|
<TT>Db</TT>. Each Db directory can contain record instance, template, and
|
|
substitution files or the equivalent CapFast schematics.</DD>
|
|
</DL>
|
|
|
|
<DT>
|
|
<TT>iocBoot or iocboot</TT></DT>
|
|
|
|
<DD>
|
|
Directory containing a subdirectory for each IOC.</DD>
|
|
|
|
<DL>
|
|
<DT>
|
|
<TT>iocxxx</TT></DT>
|
|
|
|
<DD>
|
|
Directory from which IOC <TT>iocxxx </TT>is booted. Each must have <TT>ioc</TT>
|
|
prepended to the name because <TT>iocBoot/Makefile</TT> looks for it.</DD>
|
|
</DL>
|
|
|
|
<DT>
|
|
<TT>dbd</TT></DT>
|
|
|
|
<DD>
|
|
Installed Database Definitions Directory.</DD>
|
|
|
|
<DT>
|
|
<TT>include</TT></DT>
|
|
|
|
<DD>
|
|
Include Directory. The directory in which include files generated from
|
|
menu and record type definitions are installed.</DD>
|
|
|
|
<DT>
|
|
<TT>bin</TT></DT>
|
|
|
|
<DD>
|
|
Bin Directory. This directory contains a subdirectory for the host architecture
|
|
and for each target architectiure. These are the directories in which executables,
|
|
binaries, etc. are installed.</DD>
|
|
|
|
<DT>
|
|
<TT>lib</TT></DT>
|
|
|
|
<DD>
|
|
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.</DD>
|
|
|
|
<DT>
|
|
<TT>db</TT></DT>
|
|
|
|
<DD>
|
|
Installed Databases Directory. The directory into which record instance,
|
|
template and substitutions files are installed.</DD>
|
|
</DL>
|
|
|
|
<H3>
|
|
Makefiles</H3>
|
|
The makefiles are described in section <A HREF="#makeFiles">Description
|
|
of Makefiles</A> below.
|
|
<H3>
|
|
<top>/config/*</H3>
|
|
These files contain definitions included in the various makefiles.
|
|
<DL>
|
|
<DT>
|
|
<TT>CONFIG</TT></DT>
|
|
|
|
<DD>
|
|
This is the file in which you add to or modify make variables in EPICS
|
|
base. A useful definition to override is:</DD>
|
|
|
|
<PRE> CROSS_COMPILER_TARGET_ARCHS =</PRE>
|
|
|
|
<DD>
|
|
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 variables saves build time.</DD>
|
|
|
|
<DD>
|
|
If you are using capfast you may want to add the definition:</DD>
|
|
|
|
<DL>
|
|
<PRE>DB_OPT = YES</PRE>
|
|
</DL>
|
|
|
|
<DT>
|
|
<TT>CONFIG_APP</TT></DT>
|
|
|
|
<DD>
|
|
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 <TT>epics_base </TT>and <TT>share</TT>. Follow the
|
|
models already in the file.</DD>
|
|
|
|
<DT>
|
|
<TT>RELEASE</TT></DT>
|
|
|
|
<DD>
|
|
This file specifies the location of external products such as EPICS base.
|
|
The procedures for going to a new release of an external product are described
|
|
later in this chapter. One step in the procedures is to edit this file.
|
|
The config files created by makeBaseApp provide support for the following
|
|
variables:</DD>
|
|
|
|
<DL
|
|
<DT><TT>EPICS_BASE</TT>
|
|
<DD>
|
|
This variable must be defined.</DD>
|
|
|
|
<DT>
|
|
<TT>SHARE</TT></DT>
|
|
|
|
<DD>
|
|
This variable, which is optional, specifies the location of a release of
|
|
a <TT><top></TT> area containing code that can be shared by other applications.</DD>
|
|
|
|
<DT>
|
|
<TT>TEMPLATE_TOP</TT></DT>
|
|
|
|
<DD>
|
|
This variable specifies the location of the template top area for makeBaseApp.</DD>
|
|
</DL>
|
|
<B>IMPORTANT: </B>Each of the above variables must be specified with a
|
|
full path name.
|
|
<DT>
|
|
<TT>RULES.Db</TT></DT>
|
|
|
|
<DD>
|
|
This file contains rules for building and installing database files. Databases
|
|
generated from templates and/or CapFast schematics are supported.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES.Host</TT></DT>
|
|
|
|
<DD>
|
|
The template file includes the <TT>RULES.Host</TT> from base. If you want
|
|
to add rules that apply to all <TT>Makefile.Host</TT> files then this is
|
|
the place to add the rules.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES.Vx</TT></DT>
|
|
|
|
<DD>
|
|
The template file includes the <TT>RULES.Vx</TT> from base. If you want
|
|
to add rules that apply to all <TT>Makefile.Vx</TT> files then this is
|
|
the place to add the rules.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES.ioc</TT></DT>
|
|
|
|
<DD>
|
|
This is a file containing rules for the Makefiles in the directories from
|
|
which IOCs are booted.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES.iocBoot</TT></DT>
|
|
|
|
<DD>
|
|
This is a file containing rules for the Makefiles in the iocBoot directory.
|
|
It should not be necessary to modify this file.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES_ARCHS</TT></DT>
|
|
|
|
<DD>
|
|
This file includes the <TT>RULES_ARCHS</TT> from base. It is seldom necessary
|
|
to modify this file.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES_DIRS</TT></DT>
|
|
|
|
<DD>
|
|
This file includes the <TT>RULES_DIRS</TT> from base. It is seldom necessary
|
|
to modify this file.</DD>
|
|
|
|
<DT>
|
|
<TT>RULES_TOP</TT></DT>
|
|
|
|
<DD>
|
|
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.</DD>
|
|
|
|
<DT>
|
|
<TT>makeIocCdCommands.pl</TT></DT>
|
|
|
|
<DD>
|
|
This is a perl script that generates a <TT>cdCommands</TT> file for use
|
|
by IOCs.</DD>
|
|
|
|
<DT>
|
|
<TT>makeDbDepends.pl</TT></DT>
|
|
|
|
<DD>
|
|
This is a perl script that generates make dependencies from substitutions
|
|
files.</DD>
|
|
|
|
<DT>
|
|
<TT>replaceVAR.pl</TT></DT>
|
|
|
|
<DD>
|
|
This is a perl script that changes <TT>VAR(xxx)</TT> style macros in CapFast
|
|
generated databases into the <TT>$(xxx)</TT> notation used in EPICS databases.</DD>
|
|
</DL>
|
|
|
|
<H3>
|
|
base.dbd and <app>Include.dbd</H3>
|
|
NOTE: A version of <TT>base.dbd</TT> can be obtained from
|
|
<BLOCKQUOTE><TT><epics_base>/templates/makeBaseApp/top/exampleApp/src.</TT></BLOCKQUOTE>
|
|
These files are used to configure database definitions for the following:
|
|
<UL>
|
|
<LI>
|
|
menus</LI>
|
|
|
|
<LI>
|
|
record types</LI>
|
|
|
|
<LI>
|
|
device support</LI>
|
|
|
|
<LI>
|
|
driver support</LI>
|
|
|
|
<LI>
|
|
breakpoint tables</LI>
|
|
</UL>
|
|
When <TT>gnumake</TT> is executed, an expanded file, i.e. a file with all
|
|
include statements expanded, is installed into:
|
|
<PRE> <top>/dbd/</PRE>
|
|
with the name specified by <TT>DBDNAME</TT> in <TT>Makefile.Host</TT>.
|
|
|
|
<P><TT>base.dbd </TT>contains definitions obtained from the base release.
|
|
It contains definitions like:
|
|
<PRE> 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)
|
|
...</PRE>
|
|
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 desired support.
|
|
|
|
<P>File <TT><app>Include.dbd</TT>, which contains definitions like:
|
|
<PRE> include "base.dbd"
|
|
#local menu, record, device, driver, breakpoint definitions</PRE>
|
|
is the place where you define locally built support.
|
|
<H3>
|
|
baseLIBOBJS</H3>
|
|
NOTE: A version of baseLIBOBJS can be obtained from
|
|
<BLOCKQUOTE><TT><epics_base>/templates/makeBaseApp/top/exampleApp/src.</TT></BLOCKQUOTE>
|
|
This file defines all the object modules for record, device, and driver
|
|
support supplied by EPICS. Since the file is intimately related to base.dbd,
|
|
if <TT>base.dbd</TT> (is, is not) used in a particular <TT>xxxApp/src</TT>
|
|
directory, then <TT>baseLIBOBJS</TT> should (be, not be) used in that directory.
|
|
|
|
<P><TT>baseLIBOBJS</TT> contains definitions as follows:
|
|
<PRE> #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
|
|
...</PRE>
|
|
Thus it has a definition for all record, device and driver support 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 front of the appropriate lines. <TT>Makefile.Vx</TT> contains rules
|
|
that will combine all support into a single module called xxxSupport.
|
|
|
|
<P><B>APOLOGY</B>: It would be nice if this file could be automatically
|
|
generated. This is not possible because there is no naming convention for
|
|
device support source files.
|
|
<H3>
|
|
st.cmd</H3>
|
|
The vxWorks startup file is described in a later section.
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="makeBaseApp"></A>makeBaseApp</H2></CENTER>
|
|
makeBaseApp is a perl script that creates application areas. It can create
|
|
the following:
|
|
<UL>
|
|
<LI>
|
|
<top>/Makefile</LI>
|
|
|
|
<LI>
|
|
<top>/config - A subdirectory and associated files</LI>
|
|
|
|
<LI>
|
|
<top>/xxxApp - A set of directories and associated files for a new <top>
|
|
level application.</LI>
|
|
|
|
<LI>
|
|
<top>/iocBoot - A subdirectory and associated files.</LI>
|
|
|
|
<LI>
|
|
<top>/iocBoot/iocxxx - A subdirectory and associated files.</LI>
|
|
</UL>
|
|
makeBaseApp creates directories and then copies template files with replacements
|
|
into the newly created directories. EPICS base supports two sets of template
|
|
files: simple and example. These are meant for simple applications. Each
|
|
site, however, can provide its own set of template files which may provide
|
|
additional functionality. This section will describe the functionality
|
|
of makeBaseApp itself and the next section will describe details about
|
|
the simple and example templates.
|
|
|
|
<P>makeBaseApp has the following usage:
|
|
<PRE><base>/bin/<arch>/makeBaseApp.pl -l</PRE>
|
|
|
|
<PRE><base>/bin/<arch>/makeBaseApp.pl -t type [options] app ...
|
|
create application directories
|
|
<base>/bin/<arch>/makeBaseApp.pl -i -t type [options] ioc ...
|
|
create ioc boot directories
|
|
where
|
|
app Application name (the created directory will have "App" appended to name)
|
|
ioc IOC name (the created directory will have "ioc" prepended to name)
|
|
|
|
-t type Set the application type (-l for a list of valid types)
|
|
If not specified, type is taken from environment
|
|
If not found in environment, "default" is used
|
|
-T top Set the template top directory (where the application templates are)
|
|
If not specified, top path is taken from config/RELEASE
|
|
If config does not exist, top path is taken from environment
|
|
If not found in environment, the templates from EPICS base are used
|
|
-l List valid application types for this installation
|
|
If this is specified the other options are not used
|
|
-a arch Set the IOC architecture (e.g. mv167)
|
|
If not specified, you will be prompted
|
|
-b base Set the location of EPICS base (full path)
|
|
If not specified, base path is taken from config/RELEASE
|
|
If config does not exist, base path is taken from command
|
|
-d Verbose output (useful for debugging)
|
|
|
|
Environment Variables:
|
|
EPICS_MBA_DEF_APP_TYPE Application type you want to use as default
|
|
EPICS_MBA_TEMPLATE_TOP Template top directory</PRE>
|
|
|
|
<BR>To create a new <top> issue the commands:
|
|
<PRE> mkdir <top> # If <top> does not exist
|
|
cd <top>
|
|
<base>/bin/<arch>/makeBaseApp -t <apptype> <app> ...
|
|
<base>/bin/<arch>/makeBaseApp -i -t <apptype> <ioc> ...</PRE>
|
|
makeBaseApp does the following:
|
|
<UL>
|
|
<LI>
|
|
<TT>EPICS_BASE</TT> is located</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
If the <TT>-b</TT> option is specified it is used.</LI>
|
|
|
|
<LI>
|
|
If <TT><top>/config/RELEASE</TT> exists and defines <TT>EPICS_BASE</TT>
|
|
it is used.</LI>
|
|
|
|
<LI>
|
|
It is obtained from the invocation of makeBaseApp. For this to work makeBaseApp
|
|
must be executed via a full path name (including the revision number) to
|
|
the makeBaseApp in the EPICS base release you are using.</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
<TT>TEMPLATE_TOP</TT> is located</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
If the <TT>-T </TT>option is specified it is used.</LI>
|
|
|
|
<LI>
|
|
If <TT><top>/config/RELEASE</TT> exists and defines <TT>TEMPLATE_TOP</TT>
|
|
it is used.</LI>
|
|
|
|
<LI>
|
|
If <TT>EPICS_MBA_TEMPLATE_TOP</TT> is defined it is used.</LI>
|
|
|
|
<LI>
|
|
It is set equal to <TT><epics_base>/templates/makeBaseApp/top</TT></LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
If <TT>-l</TT> is specified the list of application types is listed and
|
|
makeBaseApp terminates.</LI>
|
|
|
|
<LI>
|
|
If <TT>-i</TT> is specified and <TT>-a</TT> is not then the user is prompted
|
|
for the IOC architecture.</LI>
|
|
|
|
<LI>
|
|
The application type is determined.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
If <TT>-t </TT>is specified it is used.</LI>
|
|
|
|
<LI>
|
|
If <TT>EPICS_MBA_DEF_APP_TYPE </TT>is defined it is used.</LI>
|
|
|
|
<LI>
|
|
If template <TT>defaultApp </TT>exists, the application type is set equal
|
|
to <TT>default</TT>.</LI>
|
|
|
|
<LI>
|
|
If template <TT>exampleApp </TT>exists, the application type is set equal
|
|
to <TT>example</TT>.</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
If <TT>-i </TT>is specified <TT>Boot</TT> is appended to the application
|
|
type, otherwise <TT>App</TT> is appended.</LI>
|
|
|
|
<LI>
|
|
If the application type is not in <TT>TEMPLATE_TOP,</TT> makeBaseApp issues
|
|
an error and terminates.</LI>
|
|
|
|
<LI>
|
|
Two perl subroutines are defined</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
ReplaceFilename - This substitutes for the following in names of any file
|
|
taken from the templates.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
<TT>_APPNAME_</TT></LI>
|
|
|
|
<LI>
|
|
_<TT>APPTYPE</TT>_</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
ReplaceLine - This substitutes for the following in each line of each file
|
|
taken from the templates.</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
_<TT>USER</TT>_</LI>
|
|
|
|
<LI>
|
|
<TT>_EPICS_BASE_</TT></LI>
|
|
|
|
<LI>
|
|
_<TT>ARCH</TT>_</LI>
|
|
|
|
<LI>
|
|
_<TT>APPNAME</TT>_</LI>
|
|
|
|
<LI>
|
|
_<TT>APPTYPE</TT>_</LI>
|
|
|
|
<LI>
|
|
<TT>_TEMPLATE_TOP_</TT></LI>
|
|
|
|
<LI>
|
|
_<TT>IOC</TT>_</LI>
|
|
</UL>
|
|
</UL>
|
|
|
|
<LI>
|
|
If the application type directory has a file named <TT>Replace.pl,</TT>
|
|
it can:</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
replace the two perl subroutines</LI>
|
|
|
|
<LI>
|
|
add a subroutine <TT>ReplaceFilenameHook($file)</TT> which is called at
|
|
the end of <TT>ReplaceFilename</TT>.</LI>
|
|
|
|
<LI>
|
|
add a subroutine <TT>ReplaceLineHook($line)</TT> which is called at the
|
|
end of <TT>ReplaceLine</TT>.</LI>
|
|
|
|
<LI>
|
|
contain code which is run after the command line options are interpreted.</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
If <TT>Makefile</TT> does not exist, it is created.</LI>
|
|
|
|
<LI>
|
|
If directory <TT>config</TT> does not exist, it is created and populated
|
|
with all the config files.</LI>
|
|
|
|
<LI>
|
|
If <TT>-i</TT> is specified</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
If directory <TT>iocBoot</TT> does not exist, it is created and the files
|
|
from the template boot directory are copied into it.</LI>
|
|
|
|
<LI>
|
|
For each <TT><ioc></TT> specified on the command line a directory <TT>iocBoot/ioc<ioc></TT>
|
|
is created and populated with the files from the template (with <TT>ReplaceLine()</TT>
|
|
tag replacement).</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
If <TT>-i</TT> is NOT specified</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
For each <TT><app></TT> specified on the command line a directory <TT><app>App</TT>
|
|
is created and populated with the directory tree from the template (with
|
|
<TT>ReplaceLine()</TT> tag replacement).</LI>
|
|
|
|
<UL>
|
|
<UL>
|
|
<H2>
|
|
<A NAME="Templates Supplied with base"></A>Application Templates Supplied
|
|
with base</H2>
|
|
</UL>
|
|
</UL>
|
|
</UL>
|
|
</UL>
|
|
EPICS base supplies the following sets of template files
|
|
<UL>
|
|
<LI>
|
|
exampleApp</LI>
|
|
|
|
<LI>
|
|
exampleBoot</LI>
|
|
|
|
<LI>
|
|
simpleApp</LI>
|
|
|
|
<LI>
|
|
simpleBoot</LI>
|
|
</UL>
|
|
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.
|
|
|
|
<P>exampleApp and exampleBoot create a complete example application. It
|
|
contains the following files.
|
|
<UL>
|
|
<PRE> <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</PRE>
|
|
|
|
<PRE> iocBoot
|
|
Makefile
|
|
nfsCommands
|
|
ioc<app>
|
|
Makefile
|
|
st.cmd</PRE>
|
|
</UL>
|
|
|
|
<DL>
|
|
<DT>
|
|
<B>caExample.c</B></DT>
|
|
|
|
<DD>
|
|
A Host application that interfaces to Channel Access. It is executed from
|
|
a Unix shell by issuing the command:</DD>
|
|
|
|
<PRE> caExample "pvname"</PRE>
|
|
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:
|
|
<UL>
|
|
<LI>
|
|
On the IOC console type the command:</LI>
|
|
|
|
<PRE> dbl</PRE>
|
|
This produces a list of all the records the IOC contains.
|
|
<LI>
|
|
On the host system change to the directory: <top>/bin/<host_arch>/</LI>
|
|
|
|
<LI>
|
|
Execute the command:</LI>
|
|
|
|
<PRE> caExample "pvname"</PRE>
|
|
where pvname is one of the record names shown by dbl</UL>
|
|
|
|
<DT>
|
|
<B>dbExample1.db</B></DT>
|
|
|
|
<DD>
|
|
This is an example of record instances. Each name is proceeded by <TT><userid></TT>,
|
|
which is the userid of the person who executed makeBaseApp. The records
|
|
are:</DD>
|
|
|
|
<DL>
|
|
<DT>
|
|
<B><userid>aiExample</B></DT>
|
|
|
|
<DD>
|
|
This is a passive ai (analog input) record which obtains its input from
|
|
record calcExample,</DD>
|
|
|
|
<DT>
|
|
<B><userid>calcExample</B></DT>
|
|
|
|
<DD>
|
|
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 aiExample. Since aiExample is passive it will also scan once a
|
|
second.</DD>
|
|
|
|
<DT>
|
|
<B><userid>xxxExample</B></DT>
|
|
|
|
<DD>
|
|
This is a sample record of type xxx, as described below. It is a passive
|
|
record. You can change its VAL field via a Channel Access client or via
|
|
the dbpf IOC command.</DD>
|
|
</DL>
|
|
|
|
<DT>
|
|
<B>dbExample2.template / dbExample2.substitutions</B></DT>
|
|
|
|
<DD>
|
|
This is another example of record instances. The database is generated
|
|
from a template database, which is instantiated using the entries in the
|
|
substitutions file. Each name is proceeded by <TT><userid></TT>, which
|
|
is the userid of the person who executed makeBaseApp. Each line in the
|
|
substitutions file creates a two record database, whose records are described
|
|
above (aiExample and calcExample).</DD>
|
|
|
|
<DT>
|
|
<B>sncExample.st</B></DT>
|
|
|
|
<DD>
|
|
This is a sequencer, i.e. state notation language, example. It prints a
|
|
message on the IOC console every time the VAL field of record <userid>xxxExample
|
|
becomes > 5.0 and also every time it becomes <=5.0..</DD>
|
|
|
|
<DT>
|
|
<B>xxxRecord.dbd xxxRecord.c</B></DT>
|
|
|
|
<DD>
|
|
A skeleton record support module. The record support module is the one
|
|
described in the Application Developer's Guide.</DD>
|
|
|
|
<DT>
|
|
<B>devXxxSoft.c</B></DT>
|
|
|
|
<DD>
|
|
A device support module for xxxRecord. The device support module provides
|
|
synchronous support for the record support.</DD>
|
|
</DL>
|
|
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="ST.CMD"></A>st.cmd</H2></CENTER>
|
|
NOTE: The commands dbLoadDatabase, dbExpand, dbLoadRecords, and dbLoadTemplate
|
|
are described in chapter , "Database Definition" of the Application Developer's
|
|
Guide.
|
|
|
|
<P>This file is the vxWorks startup file. The version created by makeBaseApp
|
|
is:
|
|
<UL>
|
|
<PRE> # Example vxWorks startup file
|
|
#Following must be added for many board support packages
|
|
#cd <full path to target bin directory>
|
|
< cdCommands</PRE>
|
|
|
|
<PRE> #< nfsCommands</PRE>
|
|
|
|
<PRE> cd appbin
|
|
ld < iocCore
|
|
ld < xxxLib
|
|
#ld < seq
|
|
|
|
cd startup
|
|
dbLoadDatabase("../../dbd/xxxApp.dbd")
|
|
dbLoadRecords("../../db/xxx.db","user=USER")
|
|
dbLoadTemplate("../../db/xxx.substitutions")
|
|
|
|
iocInit
|
|
|
|
#start sequence programs
|
|
#seq &sncxxx</PRE>
|
|
</UL>
|
|
The <TT>cdCommands </TT>file defines vxWorks variables so that <TT>cd </TT>commands
|
|
may be used later in the startup file. Definitions are provided for
|
|
<UL>
|
|
<LI>
|
|
<TT>appbin</TT> - A full path name to <TT><top>/bin/<target_arch></TT></LI>
|
|
|
|
<LI>
|
|
<TT>startup</TT> - A full path name to <TT><top>/iocBoot/iocxxx</TT></LI>
|
|
|
|
<LI>
|
|
<TT>share</TT> - A full path name to share if <TT>SHARE</TT> is defined
|
|
in <TT><top>/config/RELEASE</TT></LI>
|
|
</UL>
|
|
The first <TT>ld</TT> command loads the core EPICS components. File <TT>xxxLib</TT>
|
|
is installed when gnumake is run in the <TT><top>/xxxApp/src</TT> directory.
|
|
It 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.
|
|
|
|
<P>The <TT>dbLoadDatabase</TT> 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 <TT>dbd</TT>. 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.
|
|
|
|
<P>The command:
|
|
<PRE> dbLoadRecords("../../db/xxx.db","user=USER")</PRE>
|
|
is an example command for loading record instances. One of these commands
|
|
is supplied for each record instance file.
|
|
|
|
<P>The command:
|
|
<PRE> dbLoadTemplate("../../db/xxx.substitutions")</PRE>
|
|
is an example command for loading record templates. One of these commands
|
|
is supplied for each substitutions file.
|
|
|
|
<P>The <TT>iocInit</TT> command initializes the EPICS system.
|
|
|
|
<P>The remaining commands in the file show how to load and start sequence
|
|
programs.
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="SwitchNewRelease"></A>Switching to a new Release</H2></CENTER>
|
|
The file <TT><top>/config/RELEASE</TT> contains definitions for components
|
|
obtained form outside <TT><top></TT>. If you want to link to a new release
|
|
of anything defined in the file do the following:
|
|
<PRE>cd <top>
|
|
gnumake clean uninstall
|
|
vi <top>/config/RELEASE
|
|
cd <top>
|
|
gnumake</PRE>
|
|
Note that all definitions in <TT><top>/config/RELEASE</TT> must be complete
|
|
path definitions, i.e. relative path names are not permitted. If your site
|
|
keeps releases of base and/or share, the path definitions should contain
|
|
the release number (e.g. <TT>EPICS_BASE=/usr/local/epics/baseR3.13.0.beta12</TT>).
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="MAKE"></A>Make</H2></CENTER>
|
|
|
|
<H3>
|
|
Where make can be Executed</H3>
|
|
Make can be executed in any subdirectory where a Makefile appears, which
|
|
is almost every subdirectory.
|
|
<DL>
|
|
<DT>
|
|
<TT><top></TT></DT>
|
|
|
|
<DD>
|
|
The most useful commands at the top level directory are:</DD>
|
|
|
|
<UL>
|
|
<LI>
|
|
<TT>gnumake clean uninstall</TT></LI>
|
|
|
|
<BR>This command removes everything created or installed by make.
|
|
<LI>
|
|
<TT>gnumake</TT></LI>
|
|
|
|
<BR>This rebuilds and installs everything which is not up to date.
|
|
<BR>NOTE: executing gnumake without arguments is the same as "gnumake install"
|
|
<LI>
|
|
<TT>gnumake rebuild</TT></LI>
|
|
|
|
<BR>This is the same as
|
|
<PRE> gnumake clean install</PRE>
|
|
NOTE: If you are confused about the state of the generated files, just
|
|
execute "<TT>gnumake rebuild</TT> ".
|
|
<LI>
|
|
<TT>gnumake tar</TT></LI>
|
|
|
|
<BR>This command makes a tar image of the entire <top> directory with
|
|
the CVS directories excluded.</UL>
|
|
|
|
<DT>
|
|
<TT>xxxApp</TT></DT>
|
|
|
|
<DD>
|
|
Two useful commands at this level are</DD>
|
|
|
|
<DD>
|
|
</DD>
|
|
|
|
<DL>
|
|
<DL>
|
|
<PRE>gnumake</PRE>
|
|
|
|
<PRE>or</PRE>
|
|
|
|
<PRE>gnumake rebuild</PRE>
|
|
</DL>
|
|
</DL>
|
|
|
|
<DD>
|
|
which is the same as issuing the command in each subdirectory of <TT>xxxApp</TT>.</DD>
|
|
|
|
<BR>
|
|
<DT>
|
|
<TT>xxxApp/src</TT> or <TT>xxxApp/xxxSrc</TT></DT>
|
|
|
|
<DD>
|
|
Running the command:</DD>
|
|
|
|
<PRE> gnumake</PRE>
|
|
|
|
<DD>
|
|
which is the same as executing "<TT>gnumake install</TT>" builds
|
|
and installs all out of date Host and IOC components described by the files
|
|
<TT>Makefile.Host</TT> and <TT>Makefile.Vx</TT>. The builds are performed
|
|
in subdirectories <TT>O.<arch></TT>.</DD>
|
|
|
|
<BR>
|
|
<DD>
|
|
It is possible to build for a single architecture via the command:</DD>
|
|
|
|
<DL>
|
|
<PRE> gnumake <arch></PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
For example, if your IOC is an MV167 system, then the directory is <TT>O.mv167</TT>,
|
|
and the make command is:</DD>
|
|
|
|
<DL>
|
|
<PRE> gnumake mv167</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
Another useful command is:</DD>
|
|
|
|
<DL>
|
|
<PRE> gnumake clean</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
This removes the host and target architecture directories created by make.
|
|
".<arch>" can be appended to invoke clean for a particular architecture.</DD>
|
|
|
|
<DD>
|
|
</DD>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<DL>
|
|
<DL>
|
|
<PRE>gnumake rebuild</PRE>
|
|
</DL>
|
|
</DL>
|
|
|
|
<DD>
|
|
is the same as "<TT>gnumake clean install</TT>".</DD>
|
|
|
|
<DD>
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>xxxApp/xxxDb</TT></DT>
|
|
|
|
<DD>
|
|
Executing gnumake in this directory generates and installs database instance
|
|
files, template and substitution files plain sources or CapFast schematics.</DD>
|
|
|
|
<DD>
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>iocBoot</TT></DT>
|
|
|
|
<DD>
|
|
Executing</DD>
|
|
|
|
<PRE> gnumake</PRE>
|
|
|
|
<DD>
|
|
is the same as issuing "gnumake" in each subdirectory of <TT>iocBoot</TT>.</DD>
|
|
|
|
<DD>
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>iocBoot/iocxxx</TT></DT>
|
|
|
|
<DD>
|
|
Executing <TT>gnumake</TT> in this directory creates the <TT>cdCommands</TT>
|
|
file.</DD>
|
|
</DL>
|
|
|
|
<H3>
|
|
make targets</H3>
|
|
The following is a summary of targets that can be specified for gnumake:
|
|
<UL>
|
|
<LI>
|
|
<TT><action></TT></LI>
|
|
|
|
<LI>
|
|
<TT><arch></TT></LI>
|
|
|
|
<LI>
|
|
<TT><action>.<arch></TT></LI>
|
|
|
|
<LI>
|
|
<TT><dir></TT></LI>
|
|
|
|
<LI>
|
|
<TT><dir>.<action></TT></LI>
|
|
|
|
<LI>
|
|
<TT><dir>.<arch></TT></LI>
|
|
|
|
<LI>
|
|
<TT><dir>.<action>.<arch></TT></LI>
|
|
</UL>
|
|
where:
|
|
<DL>
|
|
<DT>
|
|
<TT><arch></TT></DT>
|
|
|
|
<DD>
|
|
<TT>sun4, solaris, hp700, mv167, etc.</TT></DD>
|
|
|
|
<BR><TT>or</TT>
|
|
<BR><TT>host - Builds for host architecture only.</TT>
|
|
<BR><TT>or</TT>
|
|
<BR><TT>cross - builds for vxWorks architecture(s) only.</TT>
|
|
<DT>
|
|
<TT><action></TT></DT>
|
|
|
|
<DD>
|
|
<TT>clean, inc, install, build, rebuild, buildInstall, uninstall, or tar</TT></DD>
|
|
|
|
<BR><TT>NOTE: uninstall and tar can only be specified at <top></TT>
|
|
<DT>
|
|
<TT><dir></TT></DT>
|
|
|
|
<DD>
|
|
subdirectory name</DD>
|
|
</DL>
|
|
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="makeFiles"></A>Description of Makefiles</H2></CENTER>
|
|
|
|
<H3>
|
|
<top>/Makefile</H3>
|
|
This makefile performs a make in the xxxApp and iocBoot subdirectories.
|
|
In addition it allows the top level make options uninstall and tar described
|
|
in the previous section. There is seldom need to modify this file.
|
|
<H3>
|
|
<top>/xxxApp/Makefile</H3>
|
|
This makefile just executes make in each <TT>*src*</TT>,<TT> *Src*</TT>,<TT>
|
|
*db*</TT> and <TT>*Db* </TT>subdirectory.
|
|
<H3>
|
|
<B><top>/xxxApp/src/Makefile.Host</B></H3>
|
|
The following IOC related components can be built:
|
|
<DL>
|
|
<DT>
|
|
Breakpoint Tables</DT>
|
|
|
|
<DD>
|
|
For each breakpoint table add the following definition</DD>
|
|
|
|
<PRE> BPTS += <table name>.dbd</PRE>
|
|
|
|
<DT>
|
|
Record Support</DT>
|
|
|
|
<DD>
|
|
For each new record type, the following definitions must be added to the
|
|
makefile:</DD>
|
|
|
|
<DL>
|
|
<PRE> RECTYPES += <rectype>Record.h</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
and the record support files:</DD>
|
|
|
|
<DL>
|
|
<PRE> <Record>Record.dbd</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
must exist.</DD>
|
|
|
|
<DD>
|
|
If a <TT>menuXXX.dbd</TT> file is present, then add the following definition:</DD>
|
|
|
|
<DL>
|
|
<PRE> MENUS += menu<name>.h</PRE>
|
|
</DL>
|
|
|
|
<DT>
|
|
Expanded Database Definition File</DT>
|
|
|
|
<DL>Files containing database definition files are expanded by utility
|
|
dbExpand and installed into <top>/dbd. The following variables are available.
|
|
<PRE> DBDEXPAND += xxxInclude.dbd
|
|
DBDNAME = xxxApp.dbd
|
|
USER_DBDFLAGS += -I <include path>
|
|
USER_DBDFLAGS += -S <macro substitutions>
|
|
|
|
DBDINSTALL += xxx.dbd</PRE>
|
|
where:
|
|
<DL>
|
|
<LI>
|
|
<TT>DBDEXPAND</TT> - A file containing database definitions.</LI>
|
|
|
|
<LI>
|
|
<TT>DBDNAME</TT> - The name of the file containing expanded definitions
|
|
to be created and installed into <TT><top>/dbd</TT>.</LI>
|
|
|
|
<LI>
|
|
<TT>USER_DBDFLAGS</TT> - Flags for dbExpand. Currently only an include
|
|
path and macro substitution are supported.</LI>
|
|
|
|
<BR><TT>DBDINSTALL</TT> - Installs the file into <TT><top>/dbd</TT>.
|
|
<BR> </DL>
|
|
</DL>
|
|
<TT>Makefile.Host </TT>has many facilities for building host components..
|
|
Replace <arch_class> in the following by the specific architecture class.</DL>
|
|
|
|
<PRE>USR_CFLAGS C compiler flags for all systems
|
|
USR_CFLAGS_<arch_class> os-specific C compiler flags
|
|
USR_CFLAGS_DEFAULT C compiler flags for systems with no
|
|
USR_CFLAGS_<arch_class> specified
|
|
|
|
USR_CXXFLAGS C++ compiler flags for all systems
|
|
USR_CXXFLAGS_<arch_class> os-specific C++ compiler flags
|
|
USR_CXXFLAGS_DEFAULT C++ compiler flags for systems with no
|
|
USR_CXXFLAGS_<arch_class> specified
|
|
|
|
INC include-files to install for all systems
|
|
INC_<arch_class> os-specific includes go to the
|
|
include/os-directory:
|
|
INC_DEFAULT include-files to install for systems
|
|
with no INC_<arch_class> specified
|
|
|
|
LIBSRCS source files for building library,
|
|
specified as LIBSRCS += xxx.c yyy.c zzz.c
|
|
LIBSRCS_<arch_class> os-specific library source files
|
|
LIBSRCS_DEFAULT library source files for systems with no
|
|
LIBSRCS_<arch_class> specified
|
|
|
|
PROD Product names (without execution suffix)
|
|
to build and install (e.g. PROD=myprod)
|
|
PROD_<arch_class> os-specific products to build and install
|
|
PROD_DEFAULT products to build and install for systems
|
|
with no PROD_<arch_class> specified</PRE>
|
|
|
|
<PRE>SRCS Source files needed to build every PROD
|
|
(e.g. SRCS=a.c b.c c.c )</PRE>
|
|
|
|
<PRE>PROD_LIBS libs needed to link every PROD for all systems
|
|
PROD_LIBS_<arch_class> os-specific libs needed to link every PROD
|
|
PROD_LIBS_DEFAULT libs needed to link every PROD for systems with
|
|
no PROD_LIBS_<arch_class> specified</PRE>
|
|
|
|
<PRE><lib>_DIR Directory to search for the specified lib. (For libs
|
|
in PROD_LIBS, <PROD>_LIBS, <target>_LIBS, and USR_LIBS)</PRE>
|
|
|
|
<PRE>SYS_PROD_LIBS system libs needed to link every PROD for all systems
|
|
SYS_PROD_LIBS_<arch_class> os-specific system libs needed to link every PROD
|
|
SYS_PROD_LIBS_DEFAULT system libs needed to link every PROD for systems with
|
|
no SYS_PROD_LIBS_<arch_class> specified</PRE>
|
|
|
|
<PRE><prod>_SRCS Source files needed to build a specific PROD
|
|
(e.g. myprod_SRCS=a.c b.c c.c )
|
|
<prod>_SRCS_<arch_class> os specific source files to build a specific PROD
|
|
<prod>_ARCS_DEFAULT source files needed to build a specific PROD for systems
|
|
with no <prod>_SRCS_<arch_class> specified</PRE>
|
|
|
|
<PRE><prod>_CFLAGS prod specific C compiler flags (e.g. xxxRecord_CFLAGS )
|
|
<prod>_CXXFLAGS prod specific C++ compiler flags
|
|
<prod>_CPPFLAGS prod specific cpp flags
|
|
<prod>_LDFLAGS prod specific ld flags
|
|
<prod>_LIBS prod specific ld libraries (e.g. X11 Xt )
|
|
<prod>_SYS_LIBS prod specific system ld libraries (e.g. m)</PRE>
|
|
|
|
<PRE>SCRIPTS scripts to install
|
|
SCRIPTS_<arch_class> os-specific scripts to install
|
|
SCRIPTS_DEFAULT scripts to install for systems with no
|
|
SCRIPTS_<arch_class> specifieD
|
|
|
|
SHARED_LIBRARIES Build shared libraries? Must be YES or NO
|
|
SHARED_LIBRARIES_<arch_class> Build os specific shared libraries? Must be YES or NO
|
|
SHARED_LIBRARIES_DEFAULT Build shared libraries for os systems with
|
|
no SHARED_LIBRARIES_<arch_class> specified</PRE>
|
|
|
|
<PRE>SHRLIB_VERSION Shared library version number
|
|
|
|
USER_VPATH List of directories that gnumake should
|
|
search for files not in current dir.
|
|
|
|
LIBRARY Name of library to build. The name should
|
|
NOT include a prefix or extension, i.e.
|
|
specify Ca NOT libCa.a
|
|
|
|
TESTPROD Product names (without execution suffix)
|
|
to build but not install. Built from
|
|
source file having same name.</PRE>
|
|
|
|
<PRE>TESTPROD_SRCS Source files needed to build every TESTPROD
|
|
|
|
INSTALL_DIR Location of install directory (default $(TOP))
|
|
|
|
MAN1,MAN2,MAN3... Name of man files to be installed
|
|
into $(INSTALL_DIR)/man/mani directory
|
|
|
|
DOCS Name of text files to be installed into
|
|
the $(INSTALL_DIR)/doc directory
|
|
|
|
TEMPLATES_DIR Template directory to be created,
|
|
$(INSTALL_DIR)/templates/$(TEMPLATE_DIR)
|
|
TEMPLATES List of template files to be installed
|
|
into $(TEMPLATE_DIR)
|
|
|
|
|
|
USR_CPPFLAGS cpp flags (for all makefile compiles)
|
|
USR_INCLUDES Directories to search for include files
|
|
(e.g. -I$(EPICS_EXTENSIONS_BIN) )
|
|
USR_LDFLAGS linker options (for all makefile links)</PRE>
|
|
|
|
<PRE>USR_LDFLAGS_<arch_class> os specific linker options (for all makefile links)</PRE>
|
|
|
|
<PRE>USR_LIBS load libraries (e.g. -lXt -lX11) (for all makefile links)</PRE>
|
|
|
|
<PRE>USR_LIBS_<arch_class> os specific load libraries (for all makefile links)
|
|
|
|
YACCOPT yacc options
|
|
LEXOPT lex options
|
|
SNCFLAGS snc options
|
|
E2DB_FLAGS e2db options
|
|
SCH2EDIF_FLAGS sch2edif options
|
|
RANLIBFLAGS ranlib options
|
|
|
|
<target>_CFLAGS target specific C compiler flags (e.g. xxxRecord_CFLAGS)
|
|
<target>_CXXFLAGS target specific C++ compiler flags
|
|
<target>_CPPFLAGS target specific cpp flags
|
|
<target>_LDFLAGS target specific ld flags
|
|
<target>_LIBS target specific ld libraries (e.g. X11 Xt )</PRE>
|
|
|
|
<PRE><target>_INCLUDES Directories to search for include files for a
|
|
specific target (e.g. -I$(MOTIF_INC))
|
|
|
|
HOST_WARN Are compiler warning messages desired
|
|
(YES or NO) (default is NO)
|
|
HOST_OPT Optimization level (default is no optimization)
|
|
|
|
STATIC_BUILD Is static build desired (YES or NO)
|
|
(default is NO)</PRE>
|
|
|
|
<PRE>CLASSES Names of Java classes to be built and installed
|
|
TESTCLASSES Names of Java classes to be built
|
|
PACKAGE Names of Java package to be installed
|
|
JAR Name of Jar file to be built
|
|
JAR_INPUT Names of files to be included in JAR
|
|
MANIFEST Name of manifest file for JAR</PRE>
|
|
|
|
<PRE>RCS Resource files needed to build every PROD
|
|
<prod>_RCS Resource files needed to build a specific PROD
|
|
<prod>_RCS_<arch_class> os specific resource files to build a specific PROD</PRE>
|
|
|
|
<H3>
|
|
<B><top>/xxxApp/src/Makefile.Vx</B></H3>
|
|
The following components can be built:
|
|
<DL>
|
|
<DT>
|
|
Record Support</DT>
|
|
|
|
<DD>
|
|
For each new record type, the following definitions must be added to the
|
|
makefile</DD>
|
|
|
|
<DL>
|
|
<PRE><TT> LIBOBJS += <rectype>Record.o</TT></PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
and the record support files:</DD>
|
|
|
|
<DL>
|
|
<PRE> <Record>Record.c</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
must exist.</DD>
|
|
|
|
<DT>
|
|
Device, Driver, other C modules</DT>
|
|
|
|
<DD>
|
|
For each such module, add a definition:</DD>
|
|
|
|
<DL>
|
|
<PRE> LIBOBJS += <name>.o</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
Each file will be placed in the library specified by LIBNAME.</DD>
|
|
|
|
<DD>
|
|
It is also possible to generate object files not placed in LIBNAME via
|
|
the definitions:</DD>
|
|
|
|
<DL>
|
|
<PRE> PROD += <name>.o
|
|
or
|
|
TARGETS += <name>.o</PRE>
|
|
Both will cause the specified file to be generated, PROD will also install
|
|
the generated file into <top>/bin/<target_arch>.
|
|
<BR> </DL>
|
|
|
|
<DT>
|
|
LIBNAME</DT>
|
|
|
|
<DD>
|
|
A file containing all LIBOBJS is installed into <top>/bin/<arch>
|
|
with the name specified by LIBNAME. If <TT>Makefile.Vx</TT> appears in
|
|
<TT>xxxApp/src</TT>, the definition should be:</DD>
|
|
|
|
<DL>
|
|
<PRE> LIBNAME = xxxLib
|
|
LIBNAME_CXX = xxxLib</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
The first is for c libraries and the second for c++ libraries.</DD>
|
|
|
|
<DT>
|
|
State Notation Programs</DT>
|
|
|
|
<DD>
|
|
For each state notation program, add the definition:</DD>
|
|
|
|
<DL>
|
|
<PRE> LIBOBJS += <name>.o</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
The state notation programs must be named <TT><name>.st</TT>.</DD>
|
|
|
|
<DT>
|
|
Scripts, etc.</DT>
|
|
|
|
<DD>
|
|
A definition of the form:</DD>
|
|
|
|
<DL>
|
|
<PRE> SCRIPTS += <name></PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
results in file <TT><name></TT> being installed from the src directory
|
|
to the <TT><top>/bin/<arch></TT> directory.</DD>
|
|
|
|
<DT>
|
|
<TT>vxWorks, vxWorks.sym, iocCore, and seq</TT></DT>
|
|
|
|
<DD>
|
|
In order to have vxWorks, vxWorks.sym, iocCore, and seq in the bin directory,
|
|
the following must appear:</DD>
|
|
|
|
<DL>
|
|
<PRE> INSTALLS += vxWorks vxWorks.sym iocCore seq</PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
<B>NOTE:</B> <TT>INSTALLS </TT>only needs to appear in one application.</DD>
|
|
</DL>
|
|
|
|
<DL>Other definitions
|
|
<PRE>USR_CFLAGS C compiler flags
|
|
USR_CXXFLAGS C++ compiler flags
|
|
USR_INCLUDES Include directory (e.g. -I$(EPICS_EXTENSIONS_BIN) )
|
|
USR_LDFLAGS linker options
|
|
|
|
INC include-files to install
|
|
MAN1,MAN2,... Man files to be installed
|
|
BIN_INSTALLS Files in any directory to install to $(INSTALL_BIN)
|
|
DOCS Text files to install into $(INSTALL_DIR)/doc
|
|
|
|
|
|
YACCOPT yacc options
|
|
LEXOPT lex options
|
|
CPPFLAGS cpp options
|
|
SNCFLAGS snc options
|
|
|
|
<target>_CFLAGS target specific C compiler flags
|
|
<target>_CXXFLAGS target specific C++ compiler flags
|
|
<target>_CPPFLAGS target specific cpp flags
|
|
<target>_SNCFLAGS target specific state notation language flags
|
|
<target>_LDFLAGS target specific ld flags
|
|
|
|
VX_WARN Compiler warning messages desired (YES or NO) (default NO)
|
|
VX_OPT Optimization level (default is no optimization)
|
|
|
|
|
|
INSTALL_DIR Installation directory (defaults to $(TOP))</PRE>
|
|
</DL>
|
|
|
|
<H3>
|
|
<B><top>/xxxApp/xxxDb/Makefile.Host</B></H3>
|
|
This makefile creates and installs databases and related files.
|
|
<H4>
|
|
Databases</H4>
|
|
Supported are:
|
|
<UL>
|
|
<LI>
|
|
Plain databases</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
from dct/gdct/editor generated source files (<TT>*.db</TT>)</LI>
|
|
|
|
<LI>
|
|
from CapFast schematics (<TT>*.sch</TT>)</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
Template generated databases</LI>
|
|
|
|
<UL>
|
|
<LI>
|
|
template database from dct/gdct/editor generated source file (<TT>*.template</TT>)</LI>
|
|
|
|
<LI>
|
|
template database from CapFast schematic (<TT>*.sch</TT>)</LI>
|
|
|
|
<LI>
|
|
substitutions file from editor generated source (<TT>*.substitutions</TT>)</LI>
|
|
|
|
<LI>
|
|
substitutions file generated by a script (e.g. querying a relational database)</LI>
|
|
</UL>
|
|
|
|
<LI>
|
|
Database optimization using the <TT>dbst</TT> tool (i.e. removing all fields
|
|
with default values)</LI>
|
|
</UL>
|
|
For template generated databases either the fully inflated database or
|
|
the template and substitutions files may be installed (so the IOC may load
|
|
the database using <TT>dbLoadRecords()</TT> or <TT>dbLoadTemplate()</TT>).
|
|
|
|
<P>For all these types of databases, the names of the files to install
|
|
have to be specified. Make will figure out how to generate these files:
|
|
<UL>
|
|
<PRE> DB += xxx.db</PRE>
|
|
</UL>
|
|
will generate xxx.db depending on which source files exist. If xxx.db is
|
|
template generated, the inflated database will be installed.
|
|
<UL>
|
|
<PRE> DB += xxx.template xxx.substitutions</PRE>
|
|
</UL>
|
|
will generate and install these files, i.e. the database will be inflated
|
|
when it is loaded by the IOC using <TT>dbLoadTemplate()</TT>.
|
|
<BR>All template files that are used, but not installed (i.e. those not
|
|
specified in <TT>DB</TT>), must be specified:
|
|
<UL>
|
|
<PRE> USES_TEMPLATE += yyy.template
|
|
USES_TEMPLATE += $(SHARE)/installDb/zzz.template</PRE>
|
|
</UL>
|
|
If specified with a path (full or relative), the templates will be soft
|
|
linked (UNIX) or copied (WIN) into the <TT>O.<arch></TT> directory.
|
|
After the first make run, template dependencies will be generated automatically.
|
|
|
|
<P>If there is no *.substitutions source for a needed substitutions file,
|
|
but a variable defining a script name (like <TT>CREATESUBSTITUTIONS=CreateSubst.pl</TT>),
|
|
this script will be called with the prefix of the substitution file name
|
|
to be generated.
|
|
|
|
<P>NOTE: If (and only if) there are script generated substitutions files,
|
|
the prefix of any inflated database's name may not equal the prefix of
|
|
the name of any template used within the directory.
|
|
|
|
<P>Other definitions:
|
|
<PRE>E2DB_FLAGS e2db options
|
|
SCH2EDIF_FLAGS sch2edif options</PRE>
|
|
|
|
<H4>
|
|
Related Files</H4>
|
|
|
|
<DT>
|
|
Expanded Database Definition File</DT>
|
|
|
|
<UL>
|
|
<DT>
|
|
Files containing database definition files are expanded by utility dbExpand
|
|
and installed into <top>/dbd. The following variables are available.</DT>
|
|
</UL>
|
|
|
|
<UL>
|
|
<UL>
|
|
<PRE>DBDEXPAND += xxxInclude.dbd
|
|
DBDNAME = xxxApp.dbd
|
|
USER_DBDFLAGS += -I <include path>
|
|
USER_DBDFLAGS += -S <macro substitutions>
|
|
|
|
DBDINSTALL += xxx.dbd</PRE>
|
|
</UL>
|
|
</UL>
|
|
|
|
<DL>
|
|
<DD>
|
|
where:</DD>
|
|
|
|
<DL>
|
|
<DL>
|
|
<LI>
|
|
<TT>DBDEXPAND</TT> - A file containing database definitions.</LI>
|
|
|
|
<LI>
|
|
<TT>DBDNAME</TT> - The name of the file containing expanded definitions
|
|
to be created and installed into <TT><top>/dbd</TT>.</LI>
|
|
|
|
<LI>
|
|
<TT>USER_DBDFLAGS</TT> - Flags for dbExpand. Currently only an include
|
|
path and macro substitution are supported.</LI>
|
|
|
|
<LI>
|
|
<TT>DBDINSTALL</TT> - Installs the file into <TT><top>/dbd</TT>.</LI>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT>
|
|
Breakpoint Tables</DT>
|
|
|
|
<DD>
|
|
For each breakpoint table add the following definition</DD>
|
|
|
|
<PRE> BPTS += <table name>.dbd</PRE>
|
|
|
|
<H3>
|
|
<B><top>/iocBoot/Makefile</B></H3>
|
|
This executes make in each subdirectory.
|
|
<H3>
|
|
<B><top>/iocBoot/iocxxx/Makefile</B></H3>
|
|
This makefile has a rule to generate cdCommands. Make sure that the definition:
|
|
<UL>
|
|
<PRE> ARCH = <arch></PRE>
|
|
</UL>
|
|
refers to the correct architecture for your IOC processor.
|
|
|
|
<P>Since cdCommands is generated the user generated and/or modified files
|
|
are independent of location even though cdCommands contains full path names.
|
|
<CENTER>
|
|
<H2>
|
|
<A NAME="CVS"></A>CVS</H2></CENTER>
|
|
The CVS utility is used to put all user editable files under source/release
|
|
control. This section gives a brief description of the commands normally
|
|
used by application developers. Consult the CVS manual for more details.
|
|
<H3>
|
|
CVSROOT</H3>
|
|
Your environment variable CVSROOT should point to the CVS repository for
|
|
IOC Applications. The following command displays the location of CVSROOT:
|
|
<PRE> echo $CVSROOT</PRE>
|
|
For example, at APS/ASD the command should show:
|
|
<PRE> /usr/local/iocapps/cvsroot</PRE>
|
|
At APS all <TT><top></TT> applications are stored under <TT>$CVSROOT/iocsys</TT>.
|
|
Other sites may use a different convention.
|
|
<H3>
|
|
Commands</H3>
|
|
This section gives a brief description of the CVS commands. Wherever <filename>
|
|
is shown a list of filenames is allowed. If <filename> is not specified
|
|
then most commands apply to the entire directory and all subdirectories.
|
|
|
|
<P>A useful option for <TT>cvs</TT> is:
|
|
<PRE> cvs -n <command></PRE>
|
|
This will execute the command without making any changes.
|
|
<DL>
|
|
<DT>
|
|
<B>help</B></DT>
|
|
|
|
<DD>
|
|
Typing</DD>
|
|
|
|
<PRE> cvs help</PRE>
|
|
gives overall cvs help.
|
|
<BR>
|
|
<DT>
|
|
<B>Checkout Entire <TT><top></TT> Area</B></DT>
|
|
|
|
<DD>
|
|
To check out an entire <TT><top></TT> area issue the commands:</DD>
|
|
|
|
<PRE>cd <anywhere>
|
|
cvs checkout iocsys/<top></PRE>
|
|
|
|
<DD>
|
|
<TT>iocsys/<top></TT> appears under <TT><anywhere></TT></DD>
|
|
|
|
<DD>
|
|
<TT></TT></DD>
|
|
|
|
<DT>
|
|
<B>watch</B></DT>
|
|
|
|
<DD>
|
|
Files (or complete directory trees including and entire <top> area)
|
|
can have a watch placed on them. When a watch is placed on a directory
|
|
<TT>cvs</TT> creates working copies read only. Users must execute a cvs
|
|
edit command to obtain a read/write file. Facilities are provided to list
|
|
all people editing a file and to be sent an e-mail message whenever someone
|
|
executes the cve edit or commit commands for a watched file. Please read
|
|
the <TT>cvs</TT> manual for details.</DD>
|
|
|
|
<DT>
|
|
<B>edit</B></DT>
|
|
|
|
<DD>
|
|
If you want to edit a file and it is read only because a watch is in effect
|
|
then execute the command:</DD>
|
|
|
|
<PRE> cvs edit <filename></PRE>
|
|
|
|
<DT>
|
|
<B>unedit</B></DT>
|
|
|
|
<DD>
|
|
If you have started editing a file and decide to abandon your changes or
|
|
not make any changes issue the command:</DD>
|
|
|
|
<PRE> cvs unedit <filename></PRE>
|
|
|
|
<DT>
|
|
<B>add</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE> cvs add <filename></PRE>
|
|
places a directory or file under CVS control. This command must be given
|
|
for each directory and file to be added to the repository.
|
|
<DT>
|
|
<B>remove</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE> cvs rm <filename></PRE>
|
|
removes the specified file from the repository. The file is not actually
|
|
deleted but is moved to the "attic". Thus previous versions can still be
|
|
retrieved.
|
|
<DT>
|
|
<B>diff</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE> cvs diff <filename></PRE>
|
|
compares the working copy of the file with the version that was checked
|
|
out out or updated from the repository.
|
|
|
|
<P>The diff command has options that allow you to see the differences between
|
|
any two versions committed to the repository.
|
|
<DT>
|
|
<B>update</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE> cvs update -d -A <filename></PRE>
|
|
brings the development area into sync with the latest versions committed
|
|
to the repository. A message is given for each file or directory that is
|
|
modified. A message starting with the letter
|
|
<PRE> C</PRE>
|
|
means that a conflict exists. Conflicts must be resolved manually.
|
|
|
|
<P>The two specified options (add new directories and reset sticky tags)
|
|
should normally be specified.
|
|
<DT>
|
|
<B>commit</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE>cvs commit <filename></PRE>
|
|
commits changes to the repository. You are asked for comments via your
|
|
favorite editor.
|
|
<DT>
|
|
<B>status</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE>cvs status <filename></PRE>
|
|
Shows the status of the file. The -v option shows all tag information for
|
|
the file.
|
|
<DT>
|
|
<B>log</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<PRE>cvs log <filename></PRE>
|
|
displays a list of all commits to the specified file..
|
|
<DT>
|
|
<B>.cvsignore</B></DT>
|
|
|
|
<DD>
|
|
Any directory can contain a file with the name <TT>.cvsignore</TT>. It
|
|
contains a list of file and directory names that should be ignored by CVS.
|
|
For example all generated directories and files should be listed in .cvsignore.</DD>
|
|
|
|
<DT>
|
|
<B>tags</B></DT>
|
|
|
|
<DD>
|
|
The command:</DD>
|
|
|
|
<DL>
|
|
<PRE>tag <official release name></PRE>
|
|
</DL>
|
|
|
|
<DD>
|
|
is used by the Application System Manager to tag official application releases.</DD>
|
|
|
|
<DT>
|
|
<B>import</B></DT>
|
|
|
|
<DD>
|
|
This command is used to put an existing tree of files into the <TT>cvs</TT>
|
|
repository. Assume that a developer has created a new directory tree for
|
|
a new <TT><top></TT> application in a directory <TT>newapp</TT>. It
|
|
can be imported into the repository via the command:</DD>
|
|
|
|
<DL>
|
|
<DL>
|
|
<PRE>cvs import -m "Creating" iocsys/newapp newapp start</PRE>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
|
|
</BODY>
|
|
</HTML>
|