Previous Chapter Chapter 7: Site Manager Interface

Chapter 7: Site Manager Interface

1. Preliminaries

CVS

Install cvs and create a CVSROOT.

GNU

Install GNU make version 3.71 or later and make sure executing gnumake locates this version. Type the following command to make sure you have your path set properly.

  which gnumake

/usr/local/epics

Create this directory and make sure it belongs to you.

Env/Path

Set your Unix environment and path and provide EPICS users with proper Unix environment..

/usr/local/etc/Cshrc file

The Unix system manager may provide a file that users execute from their .cshrc file to satisfy EPICS (and other) path and environment variable requirements. At APS this file is named:

/usr/local/etc/Cshrc.aps

The EPICS system manager arranges to have the following two EPICS lines added to this file.

# Epics operations
source /usr/local/etc/setup/EPICS

If no such Cshrc file exists, the EPICS system manager may arrange to have EPICS users source /usr/local/etc/setup/EPICS directly from their .cshrc files.

Note that the EPICS manager should prepare similar files for other shells used at the site.

/usr/local/etc/setup/EPICS

The EPICS system manager provides the /usr/local/etc/setup/EPICS file which contains site specific EPICS base and extensions path and environment commands. It must contain at least the following commands (modified for the specific site):

#  site-dependant EPICS setup
setenv PSPRINTER lp
setenv EPICS_TS_MIN_WEST 360
setenv EPICS_AR_PORT 7002
source /usr/local/epics/startup/.cshrc

/usr/local/epics/startup/.cshrc

The EPICS system manager provides this file which contains the non site specific path and environment commands needed to satisfy EPICS user requirements and EPICS Applications Source/Release Control requirements. The /usr/local/epics/startup/.cshrc file contains the following lines:

set path = ( ./appSR/tools ./appSR/bin/`arch`  ./base/tools ./base/bin/`arch` $path)
if ( ! $?EPICS_EXTENSIONS ) then
  setenv EPICS_EXTENSIONS /usr/local/epics/extensions
endif
if ( $?EPICS_EXTENSIONS_PVT ) then
  set path = ( $EPICS_EXTENSIONS_PVT $EPICS_EXTENSIONS/bin/`arch` $path)
else
  set path = ( $EPICS_EXTENSIONS $path)
endif

NOTE: The Unix system manager may have to provide an "arch" script that returns one of the EPICS supported Unix architectures when executed.

2. How to Build EPICS Base in Six Steps.

Make coffee.

Obtain a copy of EPICS, and type the following commands:

    cd epics
    # Use cp or mv to put the EPICS Tar file in this directory.
    # Uncompress if necessary (uncompress RX.XX.X.Tar).
    tar xef RX.XX.X.Tar

You will be left with two directories, config and base.

Edit all files in the config directory containing the string "SITE" that are appropriate to your build. For example, if you are building sun4 executables and IOC clients, you want to edit CONFIG_SITE, CONFIG_SITE.Unix.sun4, and CONFIG_SITE.Vx.68k. See Chaper 3 Section 3 "Config Sub-Tree" on page 12 for a description of these files.

Edit $EPICS/base/src/misc/epicsEnvParams.h. This step is optional as these variables may be overridden in an application directory with a resource.def file. This file contains these options:

      /* Minutes west of Greenwich */
      EPICS_TS_MIN_VALUE= "480";
      /* Address of IOC-log server (a Unix workstation) */
      EPICS_IOC_LOG_VALUE= "128.3.112.85";
      /* Maximum size (in bytes) of log file */
      EPICS_IOC_FILE_VALUE= "400000";
      /* Log file name */
      EPICS_IOC_LOG_FILE_TXT= "/home/epics/iocLog.text";

NOTE: This step must be changed! Base is not doing this correctly.

Select the record/device/driver support you want to use at your site. To do this edit the following files:
- base/src/ascii
  - dbRecType.ascii
  - devSup.ascii
  - drvSup.ascii
  - choiceRec.ascii
- base/src/rec/Makefile.Vx
- base/src/dev/Makefile.Vx
- base/src/drv/Makefile.Vx
  In each case comment out what you do not want rather than deleting.
Build EPICS.
```
    cd ../base
    gmake
```

NOTES:

If you receive EPICS as a statically-built binary distribution, steps 3 through 6 may not be necessary !
If you have already built EPICS or have received a pre-built version, and then decide to change options in CONFIG_SITE, you will have to:
```
    cd epics/base
    gmake clean uninstall
```
This will ensure EPICS is properly cleaned out for a compile with new options.
If your site is going to do EPICS development, it is recommended that 1) you place base under cvs control and 2) header file dependencies be generated.

3. Other Top-Level Commands for EPICS Base

The top-level makefile of EPICS base can be used for functions other than just building. It can be used for cleaning objects, creating releases and building architectures separately.

Removing EPICS Objects

Temporary objects in the O.* directories (and the directories themselves) may be cleaned at the top level by typing:

  gmake clean

All EPICS libraries and executable files within $EPICS/base/bin and $EPICS/base/lib may be deleted from the top level by typing:

  gmake uninstall

Creating Dependencies

EPICS Makefile dependencies are generated using "gmake depends". This command may be executed at the top-level for all directories, or at a low-level for just that directory:

Top-level:

  cd $EPICS/base
  gmake depends

Low-level:

  cd $EPICS/base/src/db
  gmake depends

Building a Release

To build an EPICS release,

Edit base/include/version.h if you need to change the EPICS version number.
In CONFIG_SITE, make sure the STATIC_BUILD option is set to YES if you want static UNIX objects. If you change this or any other options, you will have to fully clean EPICS base with "gmake clean uninstall".
Type:
```
    gmake release
```
This command will recalculate dependencies, build EPICS, and then create a Tar file in the directory above base. This Tar file will not include any binaries. If you want all binaries and libraries to be bundled into the Tar file, type:
```
    gmake built_release
```
instead.

Single Architecture Operations

A particular build command may be invoked for a particular architecture. For example, if you only want to build files for the mv167 architecture and then clean all sun4 objects, type:

  gmake install.mv167 clean.sun4

Notes:

A UNIX build must be completed before EPICS can be built for a vxWorks architecture. That is why HOST_ARCH is always specified first in BUILD_ARCHS within CONFIG_SITE.
The uninstall and release commands do not support single architecture operation.

4. How to Build EPICS Extensions

Make certain a built copy of EPICS base is already available at your site.

Create an extension development directory structure. Type

    mkdir epics epics/config epics/extensions epics/extensions/src

Obtain a tar file of the desired EPICS extension(s), and extract the extension(s) into your epics/extensions/src directory.
Copy the files from your site's epics/config directory into your epics/config directory.
Check definitions in the config directory files. Make certain that EPICS_BASE and/or EPICS_EXTENSIONS are appropriate for your build. If the extension you have obtained depends on another extension's library or header files, make certain that the other extension is available at your site and that EPICS_EXTENSIONS is appropriately defined. You can override definitions in your CONFIG file.
Build the extension. If XXX is the extension then type:
```
    cd epics/extension/src/XXX
    gmake
```
If you are will be doing development on the extension, you should 1) place extensions under cvs control and 2)generate header file dependencies. To generate dependencies Type:
```
    cd epics/extension/src/XXX
    gmake depends
```

5. Top-Level Commands for EPICS Extensions

The top-level makefile of EPICS extensions can perform functions for all the extensions defined in your <epics>/config/CONFIG_EXTENSIONS file. This makefile will be present if you obtained a tar file of the whole EPICS extensions tree structure. It can be used for building, installing, cleaning objects, and building architectures separately. Usually the top-level makefile is used only by the EPICS System Manager at your site.

Removing Objects

Temporary objects in the O.* directories (and the directories themselves) may be cleaned at the top level by typing:

  gmake cleanAll

All EPICS libraries and executable files within $EPICS/extensions/bin and $EPICS/extensions/lib may be deleted from the top level by typing:

  gmake uninstall

Creating Dependencies

EPICS Makefile dependencies are generated using "gmake depends". This command may be executed after all he extensions have been built at the top-level for all directories, or at a low-level for an individual directory:

Top-level:

  cd $EPICS/extensions
  gmake depends

Low-level:

  cd $EPICS/extensions/src/<prod>
  gmake depends

Single Architecture Operations

A particular build command may be invoked for a particular architecture. For example, if you only want to build files for the mv167 architecture and then clean all sun4 objects, type:

  gmake install.mv167 clean.sun4

Notes:

The uninstall command does not support single architecture operation.

6. Optional Method for Installing Extension Products

These are instructions for installing a new version of an extension product without removing the previous version. The method has the following features:

Products are installed with the name <prod>xxxx where xxxx is a version number.
A soft link points to the latest version.
If a user wants to access a previous version he/she can create a soft link to the desired version in the EPICS_EXTENSIONS_PVT/bin/`arch` directory.

Most sites will find that all their users will want updated versions of extension products independent of the version of base they are using in their iocs. This can be done as long as the Channel Access protocol doesn't change. Users normally locate extension products via /usr/local/epics/extensions/bin/`arch`. They can override the version obtained from here by putting a soft link in their EPICS_EXTENSIONS_PVT/bin/`arch` directory. For example if a user finds that a new version doesn't work for his/her application then a soft link to an old version can be created.

In order to support these features, add the following statement at the end of your CONFIG file:

  INSTALL_PRODUCT = $(EPICS_BASE_TOOLS)/InstallVersion

When a "gmake install" is made in one of the extension/src directories the result is the following:

Assume the product is named <prod>. When the previous version was created it was named:
```
    <prod>xxxx
```
and a soft link was also created with the command:
```
    ln -s <prod>xxxx <prod>
```
When the new version is created the previous version is kept and the new version named
```
    <prod>yyyy
```
where yyyy is equal to xxxx + 1
The soft link for <prod> is changed to reference the new version.

You will want to set up operational procedures so that users are properly notified when new versions are installed. These procedures should include information stating the previous and current version numbers.

Table of Contents

Next Chapter