345 lines
16 KiB
Plaintext
345 lines
16 KiB
Plaintext
Installation Instructions
|
|
|
|
EPICS Base Release 7.0.1.1
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
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
|
|
* 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 the GNU version of make for EPICS builds, and we now
|
|
recommend version 4.1 or later (version 3.82 may work on Linux, but
|
|
doesn't on Windows).
|
|
|
|
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 6 installed if any of your target systems are
|
|
vxWorks systems; the C++ compilers for vxWorks 5.x are 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 6.x EPICS web pages 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
|
|
4.10. The newer 4.11 or 5.x releases are not supported yet.
|
|
|
|
Command-line editing libraries
|
|
GNU readline or other OS-specific libraries can be used by the IOC shell
|
|
to provide command line editing and history recall. The default setting
|
|
is different for each OS. On Linux the default is to use READLINE since
|
|
most distributions include it. On MacOS the default is also READLINE
|
|
since Apple provides a compatible library, although it isn't GNU. On
|
|
RTEMS we support GNU readline and Tecla, although the default is to use
|
|
neither since these have to be added to the RTEMS installation
|
|
separately. On vxWorks we support the built-in ledLib library.
|
|
|
|
Host system storage requirements
|
|
|
|
The compressed tar file is approximately 1.6 MB in size. The
|
|
distribution source tree takes up approximately 12 MB. Each host target
|
|
will need around 40 MB for build files, and each cross-compiled target
|
|
around 20 MB.
|
|
|
|
Documentation
|
|
|
|
EPICS documentation is available through the EPICS website at Argonne.
|
|
|
|
Release specific documentation 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 Distribution documentation
|
|
base/src Source code in various subdirectories
|
|
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
|
|
include/compiler Installed compiler-specific header files
|
|
lib Installed libraries in arch subdirectories
|
|
lib/perl Installed perl modules
|
|
templates Installed templates
|
|
|
|
Build related components
|
|
|
|
base/documentation directory - contains setup, build, and install documents
|
|
|
|
README.1st Instructions for setup and building epics base
|
|
README.html html version of README.1st
|
|
README.darwin.html Installation notes for Mac OS X (Darwin)
|
|
RELEASE_NOTES.html Notes on release changes
|
|
KnownProblems.html List of known problems and workarounds
|
|
|
|
base/startup directory - contains scripts to set environment and path
|
|
|
|
EpicsHostArch Shell script to set EPICS_HOST_ARCH env variable
|
|
unix.csh C shell script to set path and env variables
|
|
unix.sh Bourne shell script to set path and env variables
|
|
win32.bat Bat file example to configure win32-x86 target
|
|
windows.bat Bat file example to configure windows-x64 target
|
|
|
|
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_APP_INCLUDE
|
|
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
|
|
CONFIG_SITE Site specific make definitions
|
|
CONFIG_SITE_ENV Site defaults for EPICS environment variables
|
|
MAKEFILE Installs CONFIG* RULES* creates
|
|
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_EXPAND
|
|
RULES_FILE_TYPE
|
|
RULES_TARGET
|
|
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
|
|
|
|
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 Base, the environment variable
|
|
EPICS_HOST_ARCH should 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 CPU architecture,
|
|
e.g. linux-x86_64. 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
|
|
EPICS 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 example IOC 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.
|