diff --git a/src/makeBaseApp/README b/src/makeBaseApp/README new file mode 100644 index 000000000..3f7e8cd8e --- /dev/null +++ b/src/makeBaseApp/README @@ -0,0 +1,45 @@ +Booting IOCs and startup files + +For Systems that do not support soft links the following is necessary + +The boot parameters must contain: + +file name : +startup script: + +For example + +file name :home/phoebus/MRK/examplePerl/bin/mv167/vxWorks +startup script:home/phoebus/MRK/examplePerl/iocBoot/iocexample/st.cmd + +The st.cmd file must be of the form: + +cd "" +... + +dbLoadDatabase("../../dbd/App.dbd") +dbLoadRecords("../../xxxApp/Db/xxx.db") +... + +For systems that do support soft links the following is possible + +The boot parameters can be: + +file name :/home/phoebus/MRK/examplePerl/iocBoot/iocexample/vxWorks +startup script:st.cmd + +The st.cmd file can be of the form: + +cd "" +... + +dbLoadDatabase("dbd/App.dbd") +dbLoadRecords("xxxApp/Db/xxx.db") + + +In addition if the APS board support mods are in effect the cd command +is not necessary. + +If NFS is desired then: + +Marty explain. diff --git a/src/makeBaseApp/iocAppBuildSRcontrol.html b/src/makeBaseApp/iocAppBuildSRcontrol.html new file mode 100644 index 000000000..32e9e2d13 --- /dev/null +++ b/src/makeBaseApp/iocAppBuildSRcontrol.html @@ -0,0 +1,1901 @@ + + + + + EPICS: IOC Applications: Building and Source Release Control + + + +
+

+EPICS IOC Applications
+Building 
+and 
+Source Release Control

+ +
+

+Marty Kraimer and Janet Anderson 
+Argonne National Laboratory, Advanced Photon Source 
+Oct 10, 1997 
+EPICS Release 3.13.0.beta12

+ +
+

+Acknowledgements

+Between release 3.13.0.beta11 and 3.13.0.beta12 makeBase App was changed +from one very long perl script to a four page perl script plus template +files. In addition other improvements were made including support for capfast. +The following people contributed to this effort: Rozelle Wright (LANL, +Ralph Lange (BESSY), and Thomas Birke (BESSY). +
+

+Quick Start

+If you are new to EPICS or are trying a new release, then follow the instructions +in section Quick Start. Look at all the files +that are generated. They give examples of how to manage each of the IOC +components. +
+

+FUTURE WORK

+The procedures described in this document use soft links in two places. +Since soft links are not supported on winXX some changes will be necessary +to use the procedures on winXX. + +

This document discusses template files. In the future these will no +longer be used. Our intention is to let makeBaseApp evolve such that template +files are no longer necessary. For now the template files can be obtained +via the WWW APS software distribution system. + +

Currently two versions of makeBaseApp exist: A bourne shell version +and a perl version. For beta11, the bourne shell version is the primary +version. In the next release of base only the perl version will be supported. +Starting soon the perl version will be made available via the WWW as a +separate product. Thus new versions can be distributed without waiting +for new versions of base. +

+

+Index

+ + + +
+

+Overview

+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. +
  + +

This document describes how to create and build IOC applications. This +includes: +

    +
  • +IOC databases.
    • + +
  • +vxWorks startup files.
    • + +
  • +State Notation Programs.
    • + +
  • +New record types, device support, drivers.
    • + +
  • +Access security configuration files
    • + +
  • +Other code to be executed in an IOC.
    • + +
  • +Special Host code.
    • +
+In addition procedures are described for managing large applications. The +principle features are: +
    +
  • +All editable files are placed under CVS control.
    • + +
  • +The complete set of operational IOC software can be stored under a single +operations directory structure.
    • + +
  • +The IOC software is divided into <top> areas. Each <top> +is maintained separately. Different <top> areas can be on different +releases of external software such as epics base releases.
    • + +
  • +Support such as special record/device/driver support can be shared across +<top> areas. This is done by having a special <top> +called share. share is built and made into releases. +Other <top> areas attach to releases of share.
    • + +
  • +Access security configuration files can be shared across <top> +areas. This is done by having a special <top> area called ascf. +Normally this would not be made into releases since it must be easily modified +by operations. The ascf directory MUST reside in the same directory +as the <top> areas that use it.
    • + +
  • +Each application developer makes changes in a private copy of a subset +of the directories, normally located in the developer's home directory.
    • + +
  • +cvs and gnumake are the only tools users execute to build +applications.
    • + +
  • +Template makefiles are provided for creating new application directories.
    • +
+ +

+User Prerequisites

+This manual assumes that the reader: +
    +
  • +Understands the C language
    • + +
  • +Knows how to use a text editor
    • + +
  • +Has at least a superficial knowledge of the make utility
    • +
+ +

+System Prerequisites

+Before you can generate EPICS IOC applications your HOSTand/or EPICS System +Manager must have done the following: +
    +
  • +Installed vxWorks and a board support package. Consult the vxWorks documentation +for details.
    • + +
  • +Installed EPICS base. This can be a specific EPICS release or the master +EPICS tree.
    • +
+ +

+Make vs. Gnumake

+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. +
+

+Quick Start

+This section explains how to quickly create an example IOC application +in a directory <top> and named example. +

+Check Environment

+Execute the command: +
echo $HOST_ARCH
+This should display your workstation architecture. +

+Create example Application

+Execute the commands: +
mkdir <top>
+cd <top>
+<base>/bin/<arch>/makeBaseApp.pl -e
+where: + +

<top> - Is any directory name you chose +
<base> - Full path name to EPICS base. +
<arch> - Your host architecture. + +

For example at ANL/APS the following commands create an application: +

cd
+mkdir myapp
+cd myapp
+/usr/local/epics/baseR3.13.0.beta11/bin/solaris/makeBaseApp.pl -e
+ +

+Inspect Files

+Spend some time looking at the files that appear under <top>. +Do this BEFORE building. +

+Build

+In directory <top> execute the command: +
gnumake
+ +

+Inspect Files

+Again look at all the files that appear under <top>. +

+boot Parameters

+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. + +

The vxWorks boot parameters look something like the following: +

boot device          : xxx
+processor number     : 0
+host name            : xxx
+file name            : <top>/iocBoot/iocexample/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)   : st.cmd
+other (o)            :
+NOTE: For a winXX host the following are needed: +
file name            : <top>/bin/<target_arch>/vxWorks
+ +
...
+ +
startup script (s)   : <top>/iocBoot/iocexample/st.cmd
+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. +

+boot

+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. +

+Test

+See the description of the example given in section makeBaseApp below. +Also try some of the vxWorks shell commands described in chapter "IOC Test +facilities" of the Application Developer's Guide. +
+

+Introduction

+ +

+Background

+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. +
    +
  • +With release 3.13 the method of configuring record/device/driver support +changed.
    • + +
  • +Both epics base and extensions have switched from sccs to cvs.
    • + +
  • +base/config, 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.
    • +
+For the above reasons we decided to redo the APS/ASD IOC Applications S/R +control system. Our goals were: +
    +
  • +SCCS will go away.
    • + +
  • +All functionality performed by appSR will be done via cvs and +GNU make.
    • +
+A major decision is What Directory Structure should we use. Before +the original appSR was written a lot 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 <top> +areas. This resulted in sharing by copying source modules from one <top> +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. + +

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. +

    +
  • +APS accelerator.
    • + +
      +
    • +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 <top> areas for each subsystem.
      • + +
    • +Each subsystem can be viewed as a separate set of applications, e.g. RF, +Magnet Power Supplies, Diagnostics, etc.
      • +
    + +
  • +IOC responsibilities.
    • + +
      +
    • +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.
      • + +
    • +A particular ioc may contain parts of multiple applications. For example +vacuum and power supplies normally share iocs.
      • +
    + +
  • +Application Developers.
    • + +
      +
    • +For the Linac, a single Application Developer has final responsibility +for all controls applications, i.e. RF, vacuum, Diagnostics, etc.
      • + +
    • +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.
      • +
    +
+One other topic to discuss before describing the overall directory structure +is the idealized Application Development Cycle. It consists of the +following steps: +
    +
  1. +Define I/O requirements.
    2. + +
    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. +
  2. +Assemble control hardware and software.
    3. + +
    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. +
  3. +Build databases, sequence programs, etc.
    4. +
+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. + +

The application structure described in the next section is designed +to meet these needs. +

+Overview of Application Source Release Control

+The application directory structure appears as follows: +
    iocsys/
+        <top>/
+            config/
+            xxxApp/
+                src/
+                xxxDb/
+            xxxApp/
+            ...
+            iocBoot/
+                iocxxx/
+                iocxxx/
+Each <top> area is a separately managed set of applications. +Separately managed means that each <top> can be using it's +own release of software obtained from outside the application, e.g. a release +of EPICS base. + +

Within a <top> 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 <top> area. No IOC belongs to +more than one <top> area. All software components needed by +IOCs are built in the xxxApp directories. Each IOC is booted from it's +subdirectory under iocBoot. The only important source file in a boot directory +is the st.cmd file which is executed after vxWorks is started on an ioc. +The st.cmd file merely loads various files built in the xxxApp directories. + +

Application developers decide what constitutes a <top>. +For example, at APS, the Linac is completely contained in a single <top> +area, while the RF is spread over three <top> areas: parrf, +boosterrf, and srrf. No <top> area, however, contains iocxxx +directories from multiple subsystems. + +

Now lets describe how the application developers use the above structure. + +

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 <top> area, such as EPICS base. After +modifing files in this directory the command: +

    gnumake
+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) + +

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 +gnumake will recreate the database file(s). + +

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. +

+share

+As mentioned above the one major defect with the old appSR system is that +there was no easy way to share code across <top> areas. To +solve this problem a new <top> area called share is +present. It is structured somewhat differently than other <top> +areas but development in it is done just like in any other <top>. +Releases of share are created. A release contains built and installed +object modules. Other <top> areas take things from releases +of share rather then from share itself. + +

The releases of share, which are dependent on releases of epics +base, are named: +

    baseXXXshareYYY
+where XXX is the epics base release and YYY is a release of share +for that base release. The share releases are stored at locations: +
    /usr/local/iocapps/iocsys/baseXXXshareYYY
+If it is necessary to obtain a bug fix or enhancement to a single module +from EPICS base or a share release, the application developer +has at least two choices. The first is to build a new release of base or +share. A second choice is to copy the source module to an appropriate +src directory and build it there. In this case you should do something +so that you remember to use the version from share after share +is rebuilt. + +

Note: Other software packages can be handled like share. +For example at APS/ASD our applications use releases of sharerf, +epicsHideos, and hideos. +

+Tools

+The following tools are used: +
    +
  • +cvs
    • + +
  • +gnumake - GNU make plus EPICS supplied configuration definitions, make +rules, and script files.
    • +
+ +

+Classes of Users

+ +
+
+Application System Manager :
+ +
+The Application System Manager is responsible for the Operations Area.
+ +
+Application Developer :
+ +
+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.
+
+ +

+References

+Version Management with CVS for CVS 1.9, Per Cederqvist et al. + +

GNU Make, Edition .51 for make Version 3.75 Beta, May 1996, Richard +M. Stallman and Ronald McGrath + +

EPICS: Application Developer's Guide R3.13, Marty Kraimer +

+

+Directory Structure

+ +

+Structure

+ +
    <top>/
+        Makefile
+        config/
+*           CONFIG
+*           CONFIG_APP
+*           RELEASE
+            RULES.Db
+*           RULES.Host
+*           RULES.Vx
+            RULES.ioc
+            RULES.iocBoot
+            RULES_ARCHS
+            RULES_DIRS
+            RULES_TOP
+        xxxApp/
+            src/ or xxxSrc
+                Makefile
+*               Makefile.Host
+*               Makefile.Vx
+*               base.dbd
+*               baseLIBOBJS
+*               <app>Include.dbd
+*               <example and/or user supplied code>
+*               <example and/or user supplied state programs>
+*               <user menu, recordtype, device, driver database defs>
+            Db/ or xxxDb
+                Makefile
+*               <record instance files>
+*               <record template and substitution files>
+            privately managed directories
+        iocBoot/
+            Makefile
+            nfsCommands
+            iocxxx/
+*               Makefile
+*               st.cmd
+**      dbd/
+            <installed database description files>
+**      include/
+            <installed include files>
+**      bin/
+            <host_arch>
+                < installed Host executables >
+            <ioc_arch>
+                <installed ioc products>
+            ...
+**      lib/
+**      man/
+Files marked with an "*" are user created and/or edited. Each such file +is discussed in this chapter. + +

Files marked with "**" are directories created by gnumake. Since gnumake +uninstall removes all files in these directories, no permanent files +should be created in these directories. +

+Directories

+The directories are: +
+
+config
+ +
+Directory containing configuration files for gnumake.
+ +
+xxxApp
+ +
+Directory containing source files and database files. An arbitrary number +of xxxApp directories are allowed. Each must have App +appended to the name because Makefile looks for it.
+ +
+
+src or xxxSrc
+ +
+Directory containing source files. An arbitrary number of source directories +can appear under each xxxApp. The names must be src or end in +Src. A source directory is where C code, sequence programs, scripts, +etc. are created and built.
+ +
+xxxDb
+ +
+Directory containing record instance files. An arbitrary number of Db directories +can exist under each xxxApp, but each must have Db appended to the name +because the Makefile looks for it. Each Db directory can contain record +instance, template, and substitution files. The name Db, without any suffix, +is also permitted.
+
+ +
+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.
+
+ +
+dbd
+ +
+Installed Database Definitions Directory.
+ +
+include
+ +
+Include Directory. The directory in which include files generated from +menu and record type definitions are installed.
+ +
+bin
+ +
+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.
+ +
+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.
+ +
+man
+ +
+Man pages Directory. This directory contains a subdirectory for each section +of the Unix style man pages. This is where man pages are installed.
+
+ +

+Makefiles

+The makefiles are described below in section Description +of Makefiles below. +

+<top>/config/*

+These files contain definitions included in the various makefiles. +
+
+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 variables saves build time. +
+CONFIG_APP
+ +
+You should not edit this file unless you are using external products besides +epics_base,and  share. If you are using additional +external products follow the model used by the template file share/config/CONFIG_APP.
+ +
+RELEASE
+ +
+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:
+ +
EPICS_BASE +
+This variable must be defined.
+ +
+SHARE
+ +
+This variable which is optional, specifies the location of a release of +a <top> area containing code that can be shared by other applications.
+
+IMPORTANT:Each of the above variables must be specified with a full +path name. +
+RULES.Db
+ +
+This file contains rules for building database files from templates.
+ +
+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. It makes the soft links needed to boot an ioc. It +should not be necessary to modify this file.
+ +
+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
+ +
+All applications except SHARE just include SHARE/config/RULES_TOP.
+
+ +

+base.dbd and <app>Include.dbd

+These files are used to configure database definitions for the following: +
    +
  • +menus
    • + +
  • +record types
    • + +
  • +device support
    • + +
  • +driver support
    • + +
  • +breakpoint tables
    • +
+When gnumake is executed, an expanded file, i.e. a file with all +include statements expanded, is installed into: +
    <top>/dbd/
+with the name specified by DBDNAME in Makefile.Vx. + +

base.dbd contains definitions obtained from the base release. +It contains definitions 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 desired support. + +

File <app>Include.dbd, which contains definitions like: +

    include "base.dbd"
+    #local menu, record, device, driver, breakpoint definitions
+is the place where you define locally built support. +

+baseLIBOBJS

+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 base.dbd (is, is not) used in a particular xxxApp/src directory, then +baseLIBOBJS should (be, not be) used in that directory. + +

baseLIBOBJS contains 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
+    ...
+Thus it has a definition for all record, device, 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 front of the appropriate lines. Makefile.Vx contains rules that will +combine all support into a single module called xxxSupport. + +

APOLOGY: 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. +

+st.cmd

+The vxWorks startup file is described in a later section. +
+

+makeBaseApp

+NOTE: two versions of makeBaseApp exist. makeBaseApp is a bourne +script and makeBaseApp.pl is a perl script. They produce nearly identical +results. + +

makeBaseApp is executed by issuing the commands: +

    mkdir <top>    # If <top> does not exist
+    cd <top>
+    <base>/bin/<arch>/makeBaseApp [-e] <app> ...
+
+makeBaseApp does the following:
+ +
    +
  • +If the user is in his/her home directory, makeBaseApp fails. This prevents +the user from accidently cluttering up their home directory.
    • + +
  • +EPICS_BASE is obtained from the command itself. This is why makeBaseApp +must be executed via a full path name to the makeBaseApp in the epics base +release you are using.
    • + +
  • +If Makefile does not exist, it is created.
    • + +
  • +If directory config does not exist, then it and all the config +files are created.
    • + +
  • +For each <app> that does not exist, it creates a directory and populates +it as follows:
    • + +
            <app>App
+            src/
+                Makefile
+    *           Makefile.Host
+    *           Makefile.Vx
+    *           <app>Include.dbd
+    *           base.dbd
+    *           baseLIBOBJS
+            Db/
+                Makefile
    +The user can rename Db to <anything>Db; +
  • +If iocBoot or iocBoot/ioc<app> do not exist, they are created and populated +as follows:
    • + +
            iocBoot
+            Makefile
+            ioc<app>
+    *           Makefile
+    *           st.cmd
    +The user can rename ioc<app> to ioc<anything>Db; +
  • +If the -e option is specified the following files are created.
    • + +
            <app>App
+            Db/
+                dbExample.db
+            src/
+                caExample.c
+                sncExample.st
+                xxxRecord.dbd
+                xxxRecord.c
+                devXxxSoft.c
    +
+The user is expected to edit (or possibly remove) the files marked with +an "*". The directory Db can be renamed as long as the last two characters +remain Db. Additional xxxDb directories can be created manually. After +each xxxDb directory is created, the Makefile can be copied from another +Db directory. + +

The directory src can be renamed as long as the new name ends +in Src. Additional source directories can be manually created. +After each directory is created makefiles can be copied from another source +directory and edited. + +

IMPORTANT: After creating new applications with makeBaseApp, +<app>/iocBoot/ioc<app>/Makefile must be edited to specify the ioc +architecture. + +

The remainder of this section gives a brief description of the files +generated if makeBaseApp is executed with the -e option. +

+
+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
+ +
+dbExample.db
+ +
+This is an example of record instances. Each name is proceeded by <userid>, +which is the userid of the person who executed makeBaseApp. The records +are:
+ +
+
+<userid>aiExample
+ +
+This is a passive ai (analog input) record which obtains its input from +record calcExample,
+ +
+<userid>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 aiExample. Since aiExample is passive it will also scan once a +second.
+ +
+<userid>xxxExample
+ +
+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.
+
+ +
+sncExample.st
+ +
+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..
+ +
+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.
+
+ +
+

+ST.CMD

+NOTE: The commands dbLoadDatabase, dbExpand, and dbLoadRecords are described +in Chapter 4, "Database Definition" of the Application Developer's Guide. + +

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

    +
        # Example vxWorks startup file
+    #Following must be added for many board support packages
+    #cd <full path to target bin directory>
    + +
        ld < bin/iocCore
+    ld < bin/xxxLib
+    #ld < bin/seq
+
+    dbLoadDatabase("dbd/xxxApp.dbd")
+    dbLoadRecords("xxxApp/xxxDb/xxx.db","user=USER")
+
+    iocInit
+
+    #start sequence programs
+    #seq &sncxxx
    +
+The first ld command loads the core EPICS components. File xxxLib +is installed when gnumake is run in the <top>/xxxApp/src 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. + +

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("xxxApp/xxxDb/xxx.db","user=USER")
+is an example command for loading record instances. One of these commands +is supplied for each record instance file. + +

The iocInit command initializes the EPICS system. + +

The remaining commands in the file show how to load and start sequence +programs. +

+

+SWITCHING TO A NEW RELEASE

+The file <top>/config/RELEASE contains definitions for components +obtained form 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 <top>/config/RELEASE
+cd <top>
+gnumake
+Note that all definitions in <top>/config/RELEASE must be complete +path definitions, i.e. relative path names are not permitted. +
+

+MAKE

+ +

+Where Executed

+Make can be executed in any subdirectory where a Makefile appears, which +is almost every subdirectory. +
+
+<top>
+ +
+The most useful commands at the top level directory are:
+ +
    +
  • +gnumake clean uninstall
    • + +
    This command removes everything created by make. +
  • +gnumake
    • + +
    This rebuilds and installs everything which is not up to date. +
    NOTE: executing gnumake without arguments is the same as "gnumake install" +
  • +gnumake rebuild
    • + +
    This is the same as +
        gnumake clean install
    +NOTE: If you are confused about the state of the generated files, just +execute "gnumake rebuild ". +
  • +gnumake tar
    • + +
    This command makes a tar image of the entire <top> directory with +the CVS directories excluded.
+ +
+xxxApp
+ +
+The most useful command at this level is
+ +
    gnumake rebuild
+which is the same as issuing "gnumake rebuild" in each subdirectory of +xxxApp. +
+xxxApp/src or xxxApp/xxxSrc
+ +
+Running the command:
+ +
    gnumake
+ +
+in a src directory builds all out of date Host and IOC components +described by the files Makefile.Host and Makefile.Vx. +The builds are performed in subdirectories O.<arch>.
+ + +

It is possible to build for a single architecture via the command: +

    gnumake <arch>
+For example, if your IOC is an MV167 system, then the directory is O.mv167, +and the make command is: +
    gnumake mv167
+Another useful command is: +
    gnumake clean
+This removes everything generated in the O. directories. ".<arch>" can +be appended to invoke clean for a particular architecture. +
+xxxApp/xxxDb
+ +
+Executing gnumake in this directory creates the link for dbd and also generates +database instance files from templates.
+ +
+iocBoot
+ +
+The most useful command at this level is
+ +
    gnumake
+which is the same as issuing "gnumake" in each subdirectory of iocBoot. + +

If the Makefile includes RULES.iocBoot then a file nfsCommands +must exist in the iocBoot directory. Running make generates a +file nfs.cmd, which contains everthing in the nfsCommands file +in addition to a command to cd to the iocBoot directory. The st.cmd +file in the iocxxx directory can then start with the commands: +

    < ../nfs.cmd
+    cd "iocxxx"
+This provides an easy way to use NFS for all file access from the ioc. +See the template files for examples. +
+iocBoot/iocxxx
+ +
+Executing gnumake in this directory creates soft links for use by the st.cmd +file.
+
+ +

+make targets

+The following is a summary of targets that can be specified for gnumake: +
    +
  • +<action>
    • + +
  • +<arch>
    • + +
  • +<action>.<arch>
    • + +
  • +<dir>
    • + +
  • +<dir>.<action>
    • + +
  • +<dir>.<arch>
    • + +
  • +<dir>.<action>.<arch>
    • +
+where: +
+
+<arch>
+ +
+sun4, solaris, hp700, mv167, etc.
+ +
or +
host - Builds for host architecture only. +
or +
cross - builds for vxWorks architecture(s) only. +
+<action>
+ +
+clean, inc, install, build, rebuild, buildInstall, uninstall, or tar
+ +
NOTE: uninstall and tar can only be specified at <top> +
+<dir>
+ +
+subdirectory name
+
+ +
+

+Description of Makefiles

+ +

+<top>/Makefile

+This makefile performs a make in the xxxApp and iocBoot subdirectories. +In addition it allows other top level make options described below. There +is seldom need to modify this file. +

+<top>/xxxApp/Makefile

+This makefile just executes make in src and each *Db subdirectory. +

+<top>/xxxApp/src/Makefile.Host

+This file specifies Host components, which can be defined in Makefile.Host. +Replace <arch_class> in the following by the specific architecture class. +
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 OIBSRCS := xxx.c yyy.c zzz.c
+LIBSRCS_<arch_class>            os-specific library source files 
+LIBSRCS_DEFAULT                 library source files for systems with no
+                                USR_CFLAGS_<arch_class> specified
+
+PROD_LIBS                       libs needed to link PROD for all systems
+PROD_LIBS_<arch_class>          os-specific libs needed to link PROD
+PROD_LIBS_DEFAULT               libs needed to link PROD for systems with
+                                no PROD_LIBS_<arch_class> specified
+
+PROD                            Product names (without execution suffix)
+                                to build and install
+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
+
+SCRIPTS                         scripts to install
+SCRIPTS_<arch_class>            os-specific scripts to install
+SCRIPTS_DEFAULT                 scripts to install for systems with no
+                                PROD_<arch_class> specifieD
+
+LIBTYPE:=SHARED                 Library type. IF shared library is
+                                desired LIBTYPE must be defined 
+
+SRCS                            Source files needed to build PROD
+                                (e.g. SRCS=a.c b.c c.c )
+
+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
+
+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
+USR_INCLUDES                    Directories to search for include files
+                                (e.g. -I$(EPICS_EXTENSIONS_BIN) )
+USR_LDFLAGS                     linker options
+USR_LDLIBS                      load libraries (e.g. -lXt -lX11 )
+
+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>_LDLIBS                 target specific ld libraries (e.g. -lX11 -lXt )
+
+
+UNIX_WARN                       Are compiler warning messages desired
+                                (YES or NO) (default is NO)
+UNIX_OPT                        Optimization level  (default is no optimization)
+
+STATIC_BUILD                    Is static build desired (YES or NO)
+                                (default is NO)
+ +

+<top>/xxxApp/src/Makefile.Vx

+The following components can be built: +
+
+Breakpoint Tables
+ +
+For each breakpoint table add the following definition
+ +
        BPTS += <table name>.dbd
+ +
+Record Support
+ +
+For each new record type, the following definitions must be added to the +makefile:
+ +
+
    RECTYPES += <rectype>Record.h
+    LIBOBJS += <rectype>Record.o
+
+ +
+and the record support files:
+ +
+
+
<Record>Record.dbd
+<Record>Record.c
+
+
+ +
+must exist.
+ +
+If a menuXXX.dbd file is present, then add the following definition.
+ +
+
    MENUS += menu<name>.h
+
+ +
+Device, Driver, other C modules
+ +
+For each such module, add a definition:
+ +
+
    LIBOBJS += <name>.o
+
+ +
+Each file will be placed in the library specified by LIBNAME.
+ +
It is also possible to generate object files not placed in LIBNAME +via the definitions: +
    PROD += <name>.o
+    or
+    TARGETS += <name>.o
+ +
Both will cause the specified file to be generated, PROD will also +install the generated file into <top>/bin/<target_arch>.
+ +
+LIBNAME
+ +
+A file containing all LIBOBJS is installed into <top>/bin/<arch> +with the name specified by LIBNAME. If Makefile.Vx appears in +xxxApp/src, the definition should be:
+ +
+
    LIBNAME = xxxLib
+    LIBNAME_CXX = xxxLib
+The first is for c libraries and the second for c++ libraries.
+ +
+Expanded Database Definition File
+ +
Files containing database definition files are expanded by utility +dbExpand and installed into <top>/dbd. The following variables are available. +
    DBDEXPAND += xxxInclude.dbd
+    DBDNAME = xxxApp.dbd
+    USER_DBDFLAGS += -I <include path>
+    USER_DBDFLAGS += -S <macro substitutions>
+
+    DBDINSTALL += xxx.dbd
+where: +
+
  • +DBDEXPAND - A file containing database definitions.
    • + +
  • +DBDNAME - The name of the file containing expanded definitions +to be created and installed into <top>/dbd.
    • + +
  • +USER_DBDFLAGS - Flags for dbExpand. Currently only an include +path and macro substitution are supported.
    • + +
  • +DBDINSTALL - Installs the file into <top>/dbd.
    • +
    +
    + +
    +State Notation Programs
    + +
    +For each state notation program, add the definition:
    + +
    +
        LIBOBJS += <name>.o
    +
    + +
    +The state notation programs must be named <name>.st.
    + +
    +Scripts, etc.
    + +
    +A definition of the form:
    + +
    +
        SCRIPTS += <name>
    +
    + +
    +results in file <name> being installed from the src directory +to the <top>/bin/<arch> directory.
    + +
    +vxWorks, vxWorks.sym, iocCore, and seq
    + +
    +In order to have vxWorks, vxWorks.sym, iocCore, and seq in the bin directory, +the following must appear:
    + +
    +
    INSTALLS += vxWorks vxWorks.sym iocCore seq
    +
    + +
    +NOTE: INSTALLS only needs to appear in one application.
    +
    + +
    Other definitions +
    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
+E2DB_FLAGS      e2db options
+SCH2EDIF_FLAGS  sch2edif 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))
    +
    + +

    +<top>/xxxApp/xxxDb/Makefile

    +This makefile performs the following functions: +
      +
    • +Creates a soft link to the <top>/dbd directory.
      • + +
      This is useful for running database configuration tools in this directory. +
    • +creates xxx.db given xxx.template and xxx.substitutions
      • + +
      Thus given a template and a substitutions file, it creates a db file. +For each such file the following rule must be added by the user: +
              DBFROMTEMPLATE += xxx.db
      + +
    • +creates xxxi.db given xxx.template and xxxi.substitutions
      • + +
      Thus given a template and a a set of related substitutions files, it +creates a db file. For each such file the following rule must be added +by the user: +
              INDDBFROMTEMPLATE += xxxi.db
      + +
              NOTE: i is a positive integer
      +Note that the name of the substitutions file must be the same as the template +except that "i" is appended to the file name.
    + +

    +<top>/iocBoot/Makefile

    +This executes make in each subdirectory. +

    +<top>iocBoot/iocxxx/Makefile

    +This makefile creates soft links used in the st.cmd file. make +sure that the definition: +
            ARCH = <arch>
    +refers to the correct architecture for your ioc processor. +
    +

    +CVS

    +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. +

    +CVSROOT

    +Your environment variable CVSROOT should point to the CVS repository for +IOC Applications. The following command displays the location of CVSROOT: +
        echo $CVSROOT
    +At APS/ASD the command should show: +
        /usr/local/iocapps/cvsroot
    + +

    +Commands

    +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. + +

    A useful option for cvs is: +

        cvs -n <command>
    +This will execute the command without making any changes. +
    +
    +help
    + +
    +Typing
    + +
        cvs help
    +gives overall cvs help. +
    +Initial Checkout
    + +
    +Each user performs application development in his/her private area. The +developer must checkout iocsys/ascf. Then entire <top> +areas can be checked out or else just a subset of a <top> area.
    + + +

    The first step is to checkout ascf. The easiest way is to create the +application area with a high level directory called iocsys. The following +commands are issued: +

        cd <anywhere>
+    cvs checkout iocsys/ascf
    +iocsys will appear as a subdirectory of <anywhere>. +If <anywhere> is null then iocsys appears in the user's home +directory. +
    +Checkout Entire <top> Area
    + +
    +To check out an entire <top> area issue the commands:
    + +
        cd <anywhere>
+    cvs checkout iocsys/<top>
    + +
    +iocsys/<top> appears under <anywhere>
    + +
    +Checkout Subset of <top> Area
    + +
    +It is possible to checkout a subset of the the xxxApps and a subset +of the iocBoot directories. The commands to accomplish this are:
    + +
        cd <anywhere>
+    cvs checkout iocsys/<top>/Makefile
+    cvs checkout iocsys/<top>/config
+    cvs checkout iocsys/<top>/xxxApp
+    ...
    +The entire iocBoot directory can be checked out via the command: +
        cvs checkout iocsys/<top>/iocBoot
    +A subset of the iocBoot directory can be checked out via the commands: +
        cvs checkout iocsys/<top>/iocBoot/Makefile
+    cvs checkout iocsys/<top>/iocBoot/iocxxx
+    ...
    + +
    +watch
    + +
    +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 +cvs 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 cvs manual for details.
    + +
    +edit
    + +
    +If you want to edit a file and it is read only because a watch is in effect +then execute the command:
    + +
            cvs edit <filename>
    + +
    +unedit
    + +
    +If you have started editing a file and decide to abandon your changes or +not make any changes issue the command:
    + +
            cvs unedit <filename>
    + +
    +add
    + +
    +The command:
    + +
        cvs add <filename>
    +places a directory or file under CVS control. This command must be given +for each directory and file to be added to the repository. +
    +remove
    + +
    +The command:
    + +
        cvs rm <filename>
    +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. +
    +diff
    + +
    +The command:
    + +
        cvs diff <filename>
    +compares the working copy of the file with the version that was checked +out out or updated from the repository. + +

    The diff command has options that allow you to see the differences between +any two versions committed to the repository. +

    +update
    + +
    +The command:
    + +
        cvs update -d -A <filename>
    +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 +
        C
    +means that a conflict exists. Conflicts must be resolved manually. + +

    The two specified options (add new directories and reset sticky tags) +should normally be specified. +

    +commit
    + +
    +The command:
    + +
    cvs commit <filename>
    +commits changes to the repository. You are asked for comments via your +favorite editor. +
    +status
    + +
    +The command:
    + +
    cvs status <filename>
    +Shows the status of the file. The -v option shows all tag information for +the file. +
    +log
    + +
    +The command:
    + +
    cvs log <filename>
    +displays a list of all commits to the specified file.. +
    +.cvsignore
    + +
    +Any directory can contain a file with the name .cvsignore. 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.
    + +
    +tags
    + +
    +The command:
    + +
    +
    tag <official release name>
    +
    + +
    +is used by the Application System Manager to tag official application releases.
    + +
    +import
    + +
    +This command is used to put an existing tree of files into the cvs +repository. Assume that a developer has created a new directory tree for +a new <top> application in a directory newapp. It +can be imported into the repository via the command:
    + +
    +
    +
    cvs import -m "Creating" iocsys/newapp newapp start
    +
    +
    +
    + +
    +

    +TEMPLATES

    +The following directory structure contains templates for Makefiles and +for rules: +
        iocsys/
+        template/
+            share/
+                Makefile
+                config/
+                    CONFIG
+                    CONFIG_APP
+                    RELEASE
+                    RULES.Db
+                    RULES.Host
+                    RULES.Vx
+                    RULES.ioc 
+                    RULES_ARCHS
+                    RULES_DIRS
+                    RULES_TOP
+                    makeSoftLinks
+                db/
+                    Makefile
+                    xxiocstatus.db
+                xxxApp/
+
+            top/
+                Makefile
+                config/
+                    CONFIG
+                    CONFIG_APP
+                    RELEASE
+                    RULES.Db
+                    RULES.Host
+                    RULES.Vx
+                    RULES.ioc 
+                    RULES_ARCHS
+                    RULES_DIRS
+                    RULES_TOP
+                xxxApp/
+                    Makefile
+                    src/
+                        Makefile
+                        Makefile.Host
+                        Makefile.Vx
+                        base.dbd
+                        baseLIBOBJS
+                    xxxDb/
+                        Makefile
+                iocBoot/
+                    Makefile
+                    nfsCommands
+                    iocxxx/
+                        Makefile
+                        st.cmd
    +A set of template files can be obtained via the WWW epics software distribution +facility at APS. +
    +

    +Multiple Top Level Applications

    +APS/ASD manages its entire set of <top> level applications +under a single directory structure: +
        /usr/local/iocapps/
+        CVSROOT/
+        iocsys/
+            <share releases>
+            ascf/
+            share/
+            sharerf/
+            linac/
+            booster/                
+            par/
+            parrf/
+            boosterrf/                      
+            srrf/
+            srbpm/
+            srfb/
+            time/
+            sitesys/
+            sr/
    +where +
      +
    • +ascf - directory for access configuration files.
      • + +
    • +share- This, which is organized like a <top>, contains +files that are shared between other <top> areas. The other +areas actually uses releases of share just like they use releases of EPICS +base.
      • + +
    • +sharerf - Like share except for use by parrf, boosterrf, and srrf.
      • + +
    • +linac, ..., sr are each <top> directories.
      • +
    + + +