417 lines
21 KiB
Plaintext
417 lines
21 KiB
Plaintext
Installation Instructions
|
||
|
||
EPICS Base Release 3.15.*
|
||
|
||
--------------------------------------------------------------------------
|
||
|
||
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 LICENSE file included in the distribution for legal
|
||
terms of usage.
|
||
|
||
Supported platforms
|
||
|
||
The list of platforms supported by this version of EPICS base is given
|
||
in the configure/CONFIG_SITE file. If you are trying to build EPICS Base
|
||
on an unlisted host or for a different target machine you must have 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.
|
||
|
||
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 work for all cross-compiled targets. You may
|
||
need the C and C++ compilers to be in your search path to do EPICS
|
||
builds; check the definitions of CC and CCC in
|
||
base/configure/os/CONFIG.<host>.<host> if you have problems.
|
||
|
||
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.
|
||
|
||
Perl
|
||
You must have Perl version 5.8.1 or later installed. The EPICS
|
||
configuration files do not specify the perl full pathname, so the perl
|
||
executable must be found through your normal 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 built using a cross-compiler, and also supports soft IOCs running
|
||
as processes on the host platform.
|
||
|
||
vxWorks
|
||
You must have vxWorks 5.5.x or 6.x installed if any of your target
|
||
systems are vxWorks systems; the C++ compiler for vxWorks 5.4 is now too
|
||
old to support. The vxWorks installation provides the cross-compiler and
|
||
header files needed to build for these targets. The absolute path to and
|
||
the version number of the vxWorks installation must be set in the
|
||
base/configure/os/CONFIG_SITE.Common.vxWorksCommon file or in one of its
|
||
target-specific overrides.
|
||
|
||
Consult the vxWorks 5.x or vxWorks 6.x EPICS web pages about and the
|
||
vxWorks documentation for information about configuring your vxWorks
|
||
operating system for use with EPICS.
|
||
|
||
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 library is
|
||
used instead.
|
||
|
||
Host system storage requirements
|
||
|
||
The GNU zipped tar file is approximately 1.5 MB in size. The unzipped
|
||
untarred distribution source tree is approximately 9.0 MB. The build
|
||
created files for each host take approximately 37 MB and the build
|
||
created files for each cross target take approximately 15 MB.
|
||
|
||
Documentation
|
||
|
||
EPICS documentation is available through the EPICS website at Argonne.
|
||
|
||
Release specific documenataion can also be found in the
|
||
base/documentation directory of the distribution.
|
||
|
||
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/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/logClient Logging client
|
||
base/src/libCom/macLib Macro substitution handler
|
||
base/src/libCom/misc Miscellaneous utilities
|
||
base/src/libCom/osi Operating system independent API
|
||
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/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/README* 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
|
||
win32-debug.bat WIN32 debug bat file to set debug 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_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
|
||
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_JAVA Definitions and rules for java jars and classes
|
||
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 Specific host definitions for all vx targets
|
||
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
|
||
fullpathName.pl Returns fullpath name of directory arg
|
||
installEpics.pl Installs built files into install directories
|
||
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.15, 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 "-mingw" for MinGW 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
|
||
R3.15 shared libraries and executables normally contain the full path
|
||
to any libraries they require. However, if you move the EPICS files or
|
||
directories from their build-time location then in order for the
|
||
shared libraries to be found at runtime LD_LIBRARY_PATH must include
|
||
the full pathname to $(INSTALL_LOCATION)/lib/$(EPICS_HOST_ARCH) when
|
||
invoking executables, or some equivalent OS-specific mechanism (such
|
||
as /etc/ld.so.conf on Linux) must be used. Shared libraries are now
|
||
built by default on all Unix type hosts.
|
||
|
||
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
|
||
|
||
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.15 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.
|