512 lines
24 KiB
Plaintext
512 lines
24 KiB
Plaintext
README.1st
|
|
Installation Instructions
|
|
|
|
EPICS base
|
|
|
|
Release 3.14.*
|
|
|
|
Table of Contents
|
|
|
|
* What is EPICS base?
|
|
* What is new in this release?
|
|
* Copyright
|
|
* Supported platforms
|
|
* Supported compilers
|
|
* Software requirements
|
|
* Host system storage requirements
|
|
* Documentation
|
|
* WWW pages
|
|
* Directory Structure
|
|
* Build related components
|
|
* Building EPICS base (Unix and Win32)
|
|
* Example application and extension
|
|
* Multiple host platforms
|
|
|
|
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?
|
|
|
|
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
|
|
for the following targets. If you are trying to build EPICS base on a
|
|
different host or for a different target machine you must get the proper
|
|
host/target cross compiler and header files, and you will have to create and
|
|
add the appropriate new 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 platforms (operating system - architecture [- alternate toolset])
|
|
|
|
cygwin-x86 (unix style API, uses cygwin1.dll compatability library)
|
|
darwin-ppc
|
|
darwin-x86
|
|
darwin-ppcx86
|
|
freebsd-x86
|
|
freebsd-x86_64
|
|
linux-ppc
|
|
linux-x86
|
|
linux-x86_64
|
|
linux-x86-borland
|
|
solaris-sparc
|
|
solaris-sparc-gnu
|
|
solaris-sparc64
|
|
solaris-sparc64-gnu
|
|
solaris-x86
|
|
solaris-x86-gnu
|
|
win32-x86
|
|
win32-x86-mingw (WIN32 API, uses MS dlls)
|
|
win32-x86-cygwin (WIN32 API, uses MS dlls)
|
|
|
|
Cross compile target platforms (operating system - architecture)
|
|
|
|
linux-386
|
|
linux-486
|
|
linux-586
|
|
linux-686
|
|
linux-arm
|
|
linux-arm_eb
|
|
linux-arm_el
|
|
linux-athlon
|
|
linux-cris
|
|
linux-cris_v10
|
|
linux-cris_v32
|
|
linux-xscale_be
|
|
vxWorks-486
|
|
vxWorks-68040
|
|
vxWorks-68040lc
|
|
vxWorks-68060
|
|
vxWorks-pentium
|
|
vxWorks-ppc603
|
|
vxWorks-ppc603_long
|
|
vxWorks-ppc604
|
|
vxWorks-ppc604_long
|
|
vxWorks-ppc604_altivec
|
|
vxWorks-mpc8540
|
|
RTEMS-at91rm9200ek
|
|
RTEMS-beatnik
|
|
RTEMS-gen68360
|
|
RTEMS-mcp750
|
|
RTEMS-mvme167
|
|
RTEMS-mvme2100
|
|
RTEMS-mvme3100
|
|
RTEMS-mvme5500
|
|
RTEMS-pc386
|
|
RTEMS-psim
|
|
RTEMS-uC5282
|
|
|
|
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
|
|
definitions of CC and CCC in base/configure/os/CONFIG.<host>.<host>.
|
|
|
|
Software requirements
|
|
|
|
GNU make
|
|
You must use GNU make, gnumake, for any EPICS builds. Set your path so that
|
|
a gnumake version 3.81 or later is available.
|
|
|
|
gcc
|
|
For most cases, you must have gcc version 3.4.2 or later. Appropriate
|
|
versions of vendor C and C++ compilers may be used for native compilation.
|
|
|
|
Perl
|
|
You must have perl version 5.8.1 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.
|
|
|
|
Target systems
|
|
EPICS supports IOCs running on embedded platforms such as VxWorks and RTEMS
|
|
via cross-compilers. EPICS also supports ?soft? IOCs running as processes on
|
|
the host platform.
|
|
|
|
Tornado 2
|
|
You must have Tornado 2 installed if any of your target systems are vxWorks
|
|
systems. Tornado 2 provides the cross-compiler and header files needed to
|
|
build for these target systems. The full path location to Tornado 2 should
|
|
be specified in the base/configure/RELEASE or
|
|
base/configure/RELEASE.<hostarch> file. You will also need one or more board
|
|
support packages. Consult the vxWorks documentation for details.
|
|
|
|
RTEMS
|
|
For RTEMS targets, you need RTEMS core and toolset version 4.9.2 or later.
|
|
|
|
GNU readline or Tecla library
|
|
GNU readline and Tecla librararies can be used by the IOC shell to provide
|
|
command line editing and command line history recall and edit. GNU readline
|
|
(or Tecla library) must be installed on your target system when
|
|
COMMANDLINE_LIBRARY is set to READLINE (or TECLA) for that target. EPICS
|
|
(EPICS shell) is the default specified in CONFIG_COMMON. A READLINE override
|
|
is defined for linux-x86 in the EPICS distribution. Comment out
|
|
COMMANDLINE_LIBRARY=READLINE in configure/os/CONFIG_SITE.Common.linux-x86 if
|
|
readline is not installed on linux-x86. Command-line editing and history
|
|
will then be those supplied by the os. On vxWorks the ledLib command-line
|
|
input libraries are used.
|
|
|
|
Host system storage requirements
|
|
|
|
The GNU zipped tar file is approximately 1.4 MB in size. The unzipped
|
|
untarred distribution source tree is approximately 7.3 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 by selecting IOC software/ Base R3.14/
|
|
<release number>.
|
|
|
|
Release specific documentation can be found in the base/documentation
|
|
directory of the distribution.
|
|
|
|
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 List
|
|
|
|
There is an EPICS mailing list called tech-talk which is hosted at APS
|
|
with a list repeater at BESSY. See the EPICS home page for subscription
|
|
instructions.
|
|
|
|
Directory Structure
|
|
|
|
Distribution directory structure:
|
|
|
|
base Root directory of the base distribution
|
|
base/config R3.13 compatibility build configuration files
|
|
base/config/tools Perl and shell scripts used in the R3.13 build
|
|
base/configure Operating system independent build config files
|
|
base/configure/os Operating system dependent build config files
|
|
base/documentation Distributation documentation
|
|
base/src All epics base source code in subdirectories
|
|
base/src/RTEMS Code to configure RTEMS for EPICS
|
|
base/src/as Access security
|
|
base/src/bpt Break point table
|
|
base/src/ca Channel access
|
|
base/src/cap5 Channel Access client interface for Perl 5
|
|
base/src/cas Channel access server library and examples
|
|
base/src/catools Channel access tools caget, cainfo, camonitor, caput
|
|
base/src/db Database access
|
|
base/src/db/test Database access tests
|
|
base/src/dbStatic Static database access
|
|
base/src/dbtools Database dbLoadTemplate tools
|
|
base/src/dev Device support (camacDev, softDev, and testDev)
|
|
base/src/excas Example channel access server
|
|
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/cppStd Support for C++ standard template library
|
|
base/src/libCom/cvtFast Fast number to string conversion
|
|
base/src/libCom/cxxTemplates C++ templates and templates tests
|
|
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/iocsh ioc shell call registered functions
|
|
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/ring Methods for creating and using ring buffers
|
|
base/src/libCom/taskwd Task watchdog
|
|
base/src/libCom/test Test tools (timer, semBinary, semMutex,fdmgr, ...)
|
|
base/src/libCom/timer Timer
|
|
base/src/libCom/tsDefs R3.13 time stamp definitions and routines
|
|
base/src/makeBaseApp Perl tool+templates to create ioc app dvl tree
|
|
base/src/makeBaseExt Perl tool+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/softIoc Example softIoc
|
|
base/src/tools Perl scripts used during the builds
|
|
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/startup Scripts for setting up path and environment
|
|
|
|
Install directories created by the build:
|
|
|
|
bin Installed scripts and executables in subdirs
|
|
cfg Installed build configuration files
|
|
db Installed data bases
|
|
dbd Installed data base definitions
|
|
doc Installed documentation files
|
|
html Installed html documentation
|
|
include Installed header files
|
|
include/os Installed os specific header files in subdirs
|
|
javalib Installed java class and jar files
|
|
lib Installed libraries in arch subdirectories
|
|
lib/perl Installed perl modules
|
|
templates Installed templates
|
|
|
|
Build related components
|
|
|
|
base/documentation files
|
|
|
|
README.1st Instructions for setup and building epics base
|
|
README.html html version of README.1st
|
|
README.WIN32 Microsoft WIN32 specific instructions
|
|
README.cxxTemplates Information about C++ templates in EPICS base
|
|
README.niCpu030 NI cpu030 specific instructions
|
|
README.darwin Installation notes for Mac OS X (Darwin)
|
|
RELEASE_NOTES.html Notes on release changes
|
|
KnownProblems.html List of known problems and workarounds
|
|
Converting*To*.html Release specific conversion instructions
|
|
Building*With*.html Release specific build instructions
|
|
|
|
base/startup directory - contains scripts to set environment and path
|
|
|
|
EpicsHostArch c shell script to set EPICS_HOST_ARCH env variable
|
|
EpicsHostArch.pl perl script to set EPICS_HOST_ARCH env variable
|
|
Site.profile bourne shell script to set path and env variables
|
|
Site.cshrc c shell script to set path and env variables
|
|
borland.bat WIN32 bat file to set borland path and env variables
|
|
cygwin.bat WIN32 bat file to set cygwin path and env variables
|
|
win32.bat WIN32 bat file to set path and env variables
|
|
|
|
base/configure directory - contains build definitions and rules
|
|
|
|
CONFIG Includes configure files and allows variable overrides
|
|
CONFIG.CrossCommon Cross build definitions
|
|
CONFIG.gnuCommon Gnu compiler build definitions for all archs
|
|
CONFIG_ADDONS Definitions for <osclass> and DEFAULT options
|
|
CONFIG_BASE EPICS base tool and location definitions
|
|
CONFIG_BASE_VERSION Definitions for EPICS base version number
|
|
CONFIG_COMMON Definitions common to all builds
|
|
CONFIG_ENV Definitions of EPICS environment variables
|
|
CONFIG_FILE_TYPE Definitions for file types adl,alh,cfg,perlmod,edl
|
|
CONFIG_SITE Site specific make defintions
|
|
CONFIG_SITE_ENV Site defaults for EPICS environment variables
|
|
MAKEFILE Installs CONFIG* RULES* creates CONFIG_APP_INCLUDE
|
|
RELEASE Location of external products such as Tornado II
|
|
RULES Includes appropriate rules file
|
|
RULES.Db Rules for database and database definition files
|
|
RULES.ioc Rules for application iocBoot/ioc* directory
|
|
RULES_ARCHS Definitions and rules for building architectures
|
|
RULES_BUILD Build and install rules and definitions
|
|
RULES_DIRS Definitions and rules for building subdirectories
|
|
RULES_EXPAND Devinitions and rules for expanding vars in a file
|
|
RULES_FILE_TYPE Definitions and rules for user defined file types
|
|
RULES_JAVA Definitions and rules for java jars and classes
|
|
RULES_TARGET Definitions and rules for prod and lib named targets
|
|
RULES_TOP Rules specific to a <top> dir (uninstall and tar)
|
|
Sample.Makefile Sample makefile with comments
|
|
|
|
|
|
base/configure/os directory - contains os-arch specific definitions
|
|
|
|
CONFIG.<host>.<target> Specific host-target build definitions
|
|
CONFIG.Common.<target> Specific target definitions for all hosts
|
|
CONFIG.<host>.Common Specific host definitions for all targets
|
|
CONFIG.UnixCommon.Common Definitions for Unix hosts and all targets
|
|
CONFIG.Common.UnixCommon Definitions for Unix targets and all hosts
|
|
CONFIG.Common.vxWorksCommon Definitions for all vx targets for all hosts
|
|
CONFIG_COMPAT R3.13 arch compatibility definitions
|
|
CONFIG_SITE.<host>.<target> Site specific host-target definitions
|
|
CONFIG_SITE.Common.<target> Site specific target defs for all hosts
|
|
CONFIG_SITE.<host>.Common Site specific host defs for all targets
|
|
|
|
|
|
base/src/tools directory - contains Perl scripts used for the build
|
|
|
|
Makefile Makefile for installing the scripts into cfg dir
|
|
convertRelease.pl Performs consistancy checks on RELEASE files
|
|
cvsclean.pl Remove all .#* files in directory tree
|
|
dos2unix.pl Converts text file from DOS CR/LF to unix ISO
|
|
expandvars.pl Tool to expand @VAR@ variables while copying a file
|
|
filterWarnings.pl Filters warning messages during HP builds
|
|
fullpathName.pl Returns fullpath name of directory arg
|
|
installEpics.pl Installs built files into install directories
|
|
makeDbDepends.pl Gets dependencies from .substitution/.template files
|
|
makeIncludeDbd.pl Creates *Include.dbd file from filename args files
|
|
makeMakefile.pl Creates a Makefile in O.<arch> dirs
|
|
makeTestfile.pl Generates a test harness $target.t file
|
|
mkmf.pl Generates dependencies from include stmnts
|
|
munch.pl Creates a ctdt.c file for vxWorks targets
|
|
replaceVAR.pl Changes CapFast VAR(xxx) to $(xxx) notation
|
|
useManifestTool.pl Use MS VC++ version to set usage of Manifest Tool
|
|
|
|
Building EPICS base (Unix and Win32)
|
|
|
|
Unpack file
|
|
|
|
Unzip and untar the distribution file. Use WinZip on Windows systems.
|
|
|
|
Set environment variables
|
|
|
|
Files in the base/startup directory have been provided to help set
|
|
required path and other environment variables .
|
|
|
|
EPICS_HOST_ARCH
|
|
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.
|
|
If you are not using the OS vendor's c/c++ compiler for host builds, you
|
|
will need another dash followed by the alternate compiler name (e.g.
|
|
"-gnu" for GNU c/c++ compilers on a solaris host or "-borland" for
|
|
Borland c/c++ compilers on a WIN32 host). See configure/CONFIG_SITE for
|
|
a list of supported EPICS_HOST_ARCH values.
|
|
|
|
PERLLIB
|
|
On WIN32, some versions of Perl require that the environment variable
|
|
PERLLIB be set to <perl directory location>.
|
|
|
|
PATH
|
|
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 ln,
|
|
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 your
|
|
path, and the c compiler may require as and ld in your path. On solaris
|
|
systems you need uname in your path.
|
|
|
|
LD_LIBRARY_PATH
|
|
It is no longer necessary to have LD_LIBRARY_PATH include EPICS
|
|
directories on a Unix type system. R3.14 shared libraries and
|
|
executables will contain the full path name to libraries they require.
|
|
However, if you move the EPICS directories from their build-time
|
|
location then in order for libraries to be found at runtime
|
|
LD_LIBRARY_PATH must include the full pathname to
|
|
$(INSTALL_LOCATION)/lib/$(EPICS_HOST_ARCH) when invoking executables.
|
|
Building shared libraries is now the default setting for all Unix type
|
|
hosts. NOTE: You will still need LD_LIBRARY_PATH for R3.13 extension
|
|
shared libraries even if the R3.13 extensions are built with R3.14 base.
|
|
|
|
Win32 PATH
|
|
On WIN32 systems, for R3.14.7 and later, it is no longer necessary to
|
|
add fullpathname to $(INSTALL_LOCATION)/bin/$(EPICS_HOST_ARCH) to your
|
|
path for finding dlls during EPICS builds. The win32 configure files in
|
|
base now add this directory to the path definition.
|
|
|
|
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 target archs.
|
|
configure/CONFIG_SITE_ENV Environment variable defaults
|
|
configure/RELEASE TORNADO2 full path location
|
|
|
|
Host configuration
|
|
To configure each host system, you may override the default definitions
|
|
by adding a new file in the configure/os directory with override
|
|
definitions. 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 common build settings
|
|
|
|
Target configuration
|
|
To configure each target system, you may override the default
|
|
definitions by adding a new file in the configure/os directory with
|
|
override definitions. 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. This step is necessary even if the host system
|
|
is the only target system.
|
|
|
|
configure/os/CONFIG.Common.<target> Target common settings
|
|
configure/os/CONFIG.<host>.<target> Host-target settings
|
|
|
|
R3.13 compatibility configuration
|
|
To configure EPICS base for building with R3.13 extensions and ioc
|
|
applications , you must modify the default definitions in the
|
|
base/config/CONFIG_SITE* files to agree with definitions you made in
|
|
base/configure and base/configure/os files.
|
|
|
|
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 "gnumake clean uninstall" at the root
|
|
directory of an EPICS directory structure before each complete rebuild
|
|
to ensure that all components will be rebuilt.
|
|
|
|
Example application and extension
|
|
|
|
A perl tool, makeBaseApp.pl is included in the distribution file. This
|
|
script will create a sample application that can be built and then executed
|
|
to try out this release of base.
|
|
|
|
Instructions for building and executing the 3.14 example application can be
|
|
found in the section "Example Application" of Chapter 2, "Getting Started",
|
|
in the "IOC Application Developer's Guide" for this release. The "Example
|
|
IOC Application" section briefly explains how to create and build an example
|
|
application in a user created <top> directory. It also explains how to run
|
|
the example application on a vxWorks ioc or as a process on the host system.
|
|
By running the example application as a host-based IOC, you will be able
|
|
to quickly implement a complete EPICS system and be able to run channel
|
|
access clients on the host system.
|
|
|
|
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.
|
|
|
|
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 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 root directory in the
|
|
distribution directory structure, base. Created object files 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/c++ cross compiler and target header files and the base/configure/os
|
|
directory must have the appropriate configure files.
|