README.htm

Installation Instructions

EPICS base

Release 3.14.0alpha1

What is EPICS base?

The Experimental Physics and Industrial Control Systems (EPICS) is an extensible set of software components and tools with which application developers can create a control system. This control system can be used to control accelerators, detectors, telescopes, or other scientific experimental equipment. EPICS base is the set of core software, i.e. the components of EPICS without which EPICS would not function. EPICS base allows an arbitrary number of target systems, IOCs (input/output controllers), and host systems, OPIs (operator interfaces) of various types.

What is new in this release?

This version of EPICS base contains significant changes and offers major improvements in functionality over previous versions. Please check the RELEASE_NOTES file in the distribution for description of changes and release migration details.

Copyright

Please review the COPYRIGHT* files included in the distribution for legal terms of usage.

Supported platforms

Currently this version of EPICS base has been built on the following hosts and targets. If you are trying to build EPICS base on a different host or for a different target machine you must have the proper host/target cross compiler and header files and you will have to add the appropriate configure files to the base/configure/os/directory. You can start by copying existing configuration files in the configure/os directory and then make changes for your new platforms.

Host target platforms (operating system – architecture - <alternate c++ compiler>)

solaris-sparc

linux-x86

win32-x86

win32-x86-borland

Cross compile target platforms (operating system - architecture)

vxWorks-486

vxWorks-68040

vxWorks-68040lc

vxWorks-68060

vxWorks-ppc604

vxWorks-pentium

RTEMS-gen68360

RTEMS-mvme167

Supported compilers

This version of EPICS base has been built and tested using the host vendor's C and C++ compilers as well as the GNU gcc and g++ compilers. The GNU cross-compilers have been used for all cross-compiled targets. You may need the host vendor's C++ compiler in your search path to do EPICS builds. Check the definitions of ACC and CCC in base/configure/os/CONFIG.<host>.<host> or the definitions for GCC and G++ if ANSI=GCC and CPLUSPLUS=GCC are specified in CONFIG_SITE.

Software requirements

GNU make

You must use GNU make, gnumake, for any EPICS builds. Set your path so that a gnumake version 3.70 or later is available.

Perl

You must have perl version 5.0 or later installed. The configure files do not specify the perl full pathname. You need the perl executable in your search path.

Unzip and tar (Winzip on WIN32 systems)

You must have tools available to unzip and untar the EPICS base distribution file.

Tornado 2.0

You must have Tornado 2.0 installed if any of your target systems are vxWorks systems. Tornado 2.0 provides the cross-compiler and header files needed to build for these target systems. The full path location to Tornado 2.0 must be specified in the base/configure/RELEASE file. You will also need one or more board support packages. Consult the vxWorks documentation for details.

Host system storage requirements

The GNU zipped tar file is approximately 1.4 MB in size. The unzipped untarred distribution source tree is approximately 6 MB. The build created files for each host take approximately 40 MB and the build created files for each target take approximately 10 MB.

Documentation

EPICS documentation is available on the WWW via the EPICS home page at APS: URL http://www.aps.anl.gov/Epics

This README.html is in the base distribution file and will be available on the IOC software R3.14 EPICS WWW page which can be accessed from the APS EPICS home page.

WWW pages

EPICS home page at APS

http://www.aps.anl.gov/Epics

Other WWW sites

Additional information on EPICS can be found at the various other WWW links on the EPICS home page at APS.

Mailing Lists

There are five EPICS mailing lists provided by APS. See The EPICS home page for subscription instructions.

Directory Structure

Distribution directory structure

base Root directory of the base distribution

base/configure Operating system independent build config files

base/configure/os Operating system dependent build config files

base/configure/tools Perl and shell scripts used in the build

base/config R3.13 compatibility build configuration files
base/src All epics base source code in subdirectories
base/src/as Access security
base/src/bpt Break point table
base/src/ca Channel access
base/src/cas Channel access server
base/src/db Database access

base/src/dbStatic Static database access

base/src/dbtools Database dbLoadTemplate tools
base/src/dev Device support
base/src/gdd General data descriptor
base/src/libCom General purpose library code in subdirectories
base/src/libCom/bucketLib Hash bucket
base/src/libCom/calc Algebraic expression interpreter
base/src/libCom/cvtFast Fast number to string conversion
base/src/libCom/dbmf Memory management for frequent alloc/free
base/src/libCom/ellLib EPICS double linked list
base/src/libCom/env Default EPICS environment settings
base/src/libCom/error Error handling definitions and routines
base/src/libCom/fdmgr File descriptor manager
base/src/libCom/freeList Memory management using free lists
base/src/libCom/gpHash General purpose hash table
base/src/libCom/logClient Logging client
base/src/libCom/macLib Macro substitution handler
base/src/libCom/misc Miscellaneous utilities
base/src/libCom/osi Operating system independent code
base/src/libCom/osi/os Operating system dependant code in subdirectories
base/src/libCom/test Test tools (timer, semBinary, semMutex,fdmgr, …)
base/src/libCom/timer Timer
base/src/libCom/taskwd Task watchdog
base/src/libCom/cxxTemplatesC++ templates
base/src/libCompat EPICS base R3.13 compatibility code
base/src/makeBaseApp Perl tool and templates to create application dvl tree
base/src/makeBaseExt Perl tool and templates to create extension dvl tree
base/src/misc Miscellaneous (coreRelease, iocInit, asSub*)
base/src/rec Record support
base/src/registry EPICS support function registry
base/src/rsrv Channel access ioc resource server library
base/src/toolsComm Code for the build tools antelope and e_flex
base/src/util Utilities (ca_test, iocLogServer, startCArepeater)
base/src/vxWorks R3.13 compatibility code specific to vxWorks
base/src/iocsh Ioc shell command interpreter

base/startup Scripts for setting up path and environment

Install directories created by the build

base/bin Installed scripts and executables in subdirectories
base/lib Installed libraries in arch subdirectories
base/dbd Installed data base definitions
base/include Installed header files
base/include/os Installed os specific header files
base/templates Installed templates

Build related components (this section needs work)

base/README* files

base/startup files

.cshrc

EpicsHostArch

epics.bat

.bashrc

…

base/configure

base/config

Building EPICS base (Unix and Win32)

Unpack file

Unzip and untar the distribution file. Use WinZip on Windows systems.

Set environment variable

Before you can build or use EPICS R3.14, the environment variable EPICS_HOST_ARCH must be defined. A perl script EpicsHostArch.pl in the base/startup directory has been provided to help set EPICS_HOST_ARCH. You should have EPICS_HOST_ARCH set to your host operating system followed by a dash and then your host architecture, e.g. solaris-sparc.

Check path requirements

As already mentioned, you must have the perl executable and you may need C and C++ compilers in your search path. For building base you also must have echo in your search path. For Unix host builds you also need touch, cpp, cp, rm, mv, and mkdir in your search path and /bin/chmod must exist. On some Unix systems you may also need ar and ranlib in you path.

Do site-specific build configuration

Site configuration

To configure EPICS, you may want to modify the default definitions in the following files:

configure/CONFIG_SITE - Build choices. Specify your targets architectures.

configure/CONFIG_SITE_ENV - Set your environment variable definitions

configure/RELEASE - TORNADO full path location

Host configuration

To configure each host system, you may override the default definitions by adding a new file with override definitions into the configure/os directory. The new file should have the same name as the distribution file to be overridden except with CONFIG in the name changed to CONFIG_SITE.

configure/os/CONFIG.<host>.<host> - Host build settings

configure/os/CONFIG.<host>.Common - Host cross build settings

Target configuration

To configure each target system, you may override the default definitions by adding a new file with override definitions into the configure/os directory. The new file should have the same name as the distribution file to be overridden except with CONFIG in the name replaced by CONFIG_SITE.

configure/os/CONFIG.Common.<target> - Target cross build settings

configure/os/CONFIG.<host>.<target> - Host-target build settings

Build EPICS base

After configuring the build you should be able to build EPICS base by issuing the following commands in the distribution’s root directory (base) -

gnumake clean uninstall

gnumake

The command "gnumake clean uninstall" will remove all files and directories generated by a previous build. The command "gnumake" will build and install everything for the configured host and targets.

It is recommended that you do a “make clean uninstall” at the root directory of an EPICS directory structure before each complete rebuild to ensure that all components will be rebuilt.

Multiple host platforms

You can build using a single EPICS directory structure on multiple host systems and for multiple cross target systems. The intermediate and binary files generated by the build will be created in separate system subdirectories and installed into the appropriate separate host/target install directories. EPICS executables and perl scripts are installed into the $(INSTALL_LOCATION)/bin/<arch> directories. Libraries are installed into $(INSTALL_LOCATION)/lib/<arch>. The default definition for $(INSTALL_LOCATION) is $(TOP) which is the rootdirectory in the directory structure, base. Temporary objects are stored in O.<arch> source subdirectories, This allows objects for multiple cross target architectures to be maintained at the same time. To build EPICS base for a specific host/target combination you must have the proper host/target c++ cross compiler and target header files and the base/configure/os directory must have the appropriate configure files.

Examples

A perl tool, makeBaseApp.pl is included in the distribution file. This script will create a sample application that then can be built and then executed to try out this release of base. Also, a perl script, makeBaseExt.pl, is included in the distribution file. This script will create a sample extension that can be built and executed. The makeBaseApp.pl and makeBaseExt.pl scripts are installed into the install location bin/<hostarch> directory during the base build.

Example base application (Unix and Windows)

This section briefly explains how to create an example IOC application in a directory <top>, naming the application firstApp and the ioc directory ioctarget.

Check Environment variable

Execute the command: echo $EPICS_HOST_ARCH (Unix) or

set EPICS_HOST_ARCH (Windows)

This should display your workstation architecture, for example solaris-sparc or win32-x86. If you get an "Undefined variable" error, you should set EPICS_HOST_ARCH to your host operating system followed by a dash and then your host architecture, e.g. solaris-sparc. The perl script EpicsHostArch.pl in the base/startup directory has been provided to help set EPICS_HOST_ARCH.

Create example Application

Execute the commands:

mkdir <top>

cd <top>

<base>/bin/<hostarch>/makeBaseApp.pl -t example first

<base>/bin/<hostarch>/makeBaseApp.pl -i -t example target

When prompted for architecture, give one of the CROSS_COMPILER_TARGET_ARCHS values specified in base/configure/CONFIG_SITE.

<base>/bin/<hostarch>/makeBaseApp.pl -i -t example host

When prompted for architecture, give the host architecture, EPICS_HOST_ARCH, value.

where:

<top> is any directory name you chose,

<base> is the full path name to EPICS base, and

<hostarch> is your host architecture (i.e. the output of the echo command above).

Windows Users Note: Perl scripts are invoked with the command perl <scriptname> on win95/NT. Perl script names are case sensitive. For example to create an application on WIN95/NT:

perl C:\epics\base\bin\win32\makeBaseApp.pl -t example first

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

Execute the host application

In directory <top>/iocBoot/iochost execute the command: ../../bin/<hostarch>/example stcmd.hos

Try some of the shell commands (e.g. dbl or dbpr <recordname>) described in the "IOC Test Facilities" chapter of the Application Developer's Guide.

Execute the channel access application

While the host application is running, execute the command:

<mytop>/bin/<hostarch>/caExample <user>:calcExample

where <mytop> is the full path name to your application top directory.

Execute a vxWorks target application

First kill the host application so there will be no channel access record name conflicts because you will be loading the same database onto the target system.

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

The vxWorks boot parameters look something like the following:

boot device : xxx

processor number : 0

host name : xxx

file name : <full path to board support>/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) : <hostname for this inet address>

startup script (s) : <top>/iocBoot/ioctarget/st.cmd

other (o) :

The actual values for each field are site and IOC dependent. Two fields that you can change at will are the vxWorks boot image and the location of the startup script.

Note that the full path name for the correct board support boot image must be specified. If bootp is used the same information will need to be placed in the bootp host's configuration database instead.

Boot

You are now ready to boot your IOC. When your boot parameters are set properly, just press the reset button on your IOC, or use the @ command to commence booting. You will find it VERY convenient to have the console port of the IOC attached to a scrolling window on your workstation.

Test

Try some of the shell commands (e.g. dbl or dbpr <recordname>) described in the "IOC Test Facilities" chapter of the Application Developer's Guide.

Execute the channel access application

While the target application is running, on a workstation in the same subnet at the target system, execute the command:

<mytop>/bin/<hostarch>/caExample <recordname>

where <mytop> is the full path name to your application top directory.