diff --git a/README b/README index 39077c872..47c5bdbd1 100644 --- a/README +++ b/README @@ -1,414 +1,24 @@ -README +--------------------------------------------------------- +EPICS Base - the central core of a control system toolkit +--------------------------------------------------------- - Installation Instructions +Copyright (c) 2002 The University of Chicago, as Operator +of Argonne National Laboratory. +Copyright (c) 2002 The Regents of the University of +California, as Operator of Los Alamos National Laboratory. - EPICS base +EPICS Base Versions 3.13.7 and higher are distributed +subject to a Software License Agreement found in the +file LICENSE that is included with this distribution. - Release 3.14.0beta1 +--------------------------------------------------------- -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 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 - ) - - solaris-sparc - solaris-sparc-gnu - linux-x86 - win32-x86 - win32-x86-borland - - Cross compile target platforms (operating system - architecture) - - vxWorks-486 - vxWorks-68040 - vxWorks-68040lc - vxWorks-68060 - vxWorks-ppc603 - vxWorks-ppc604 - vxWorks-pentium - RTEMS-gen68360 - RTEMS-mvme167 - RTEMS-pc386 - -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 ACC and - CCC in base/configure/os/CONFIG.. 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 or - base/configure/RELEASE. file. You will also need one or - more board support packages. Consult the vxWorks documentation for - details. - - Optional GNU compiler requirement for solaris-sparc and - win32-x86 hosts - If you have state notation language source files (*.st files) which require - c preprocessing before conversion to c source, gcc must be in your path. - -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.htm 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 istribution - 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/configure/tools Perl and shell scripts used in the build - base/copyright Text files describing software copyrights - 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/db/test Database access tests - base/src/dbStatic Static database access - base/src/dbtools Database dbLoadTemplate tools - base/src/dev Device support (softDev and testDev) - base/src/gdd General data descriptor - base/src/iocsh Ioc shell command interpreter - 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/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 code - base/src/libCom/osi/os Operating system dependant code in subdirectories - 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/libCom/ring ringPointer: First in first out circular buffers - base/src/libCom/cppStd epicsList: Lists of pointers to objects - 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/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: - - base/bin Installed scripts and executables in subdirs - 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 - - base/README* files - README.htm Instructions for setup and building epics base - (i.e. this document) - README.WIN32 Microsoft WIN32 specific instructions - README.cxxTemplates Information about C++ templates in EPICS base - README.niCpu030 NI cpu030 specific 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 path and env variables - win32.bat WIN32 bat file to set path and env variables - - base/configure directory - contains build definitions and rules - CONFIG.CrossCommon Cross build definitions - CONFIG.gnuCommon Gnu compiler build definitions for all archs - CONFIG_ADDONS Definitions for 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 - CONFIG Includes configure files and allows variable overrides - RELEASE Location of external products such as Tornado II - RULES Includes appropriate rules file - RULES.Db Rules for database and database definition files - 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 dir (uninstall and tar) - Sample.Makefile Sample makefile with comments - - base/configure/os directory - contains os-arch specific definitions - CONFIG.. Specific host-target build definitions - CONFIG.Common. Specific target definitions for all hosts - CONFIG..Common Specific host definitions for all targets - CONFIG.UnixCommon.Common Definitions for Unix hosts and all target - CONFIG..vxWorksCommon Specific host definitions for all vx targets - CONFIG_COMPAT R3.13 arch compatibility definitions - CONFIG_SITE.. Site specific host-target definitions - CONFIG_SITE.Common. Site specific target defs for all hosts - CONFIG_SITE..Common Site specific host defs for all targets - - base/configure/tools directory - contains Perl scripts used for the build - MakeReleae Unix shell script to create a release tar file - convertRelease.pl Performs consistancy checks on RELEASE files - cp.pl This Perl script copies an existing file - installEpics.pl Installs built files into install directories. - makeDependsTargets.pl Creates targets of include dependency files - makeMakefile.pl Creates a Makefile in O. dirs - makeMakefileInclude.pl Creates file to be included by Makefile - mkdir.pl Creates a directory (like Unix mkdir) - mkmf.pl Generates dependencies from include stmnts - munch.pl Creates a ctdt.c file for vxWorks targets - mv.pl Renames an existing file. - replaceVAR.pl Changes CapFast VAR(xxx) to $(xxx) notation - rm.pl Quietly removes an existing file. - -Building EPICS base (Unix and Win32) - - Unpack file - - Unzip and untar the distribution file. Use WinZip on - Windows systems. - - Set environment variable - - 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 . - - 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 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 your path, and the c compiler may require ld in your path. - - Unix LD_LIBRARY_PATH - If you plan to build EPICS base shared libraries instead of - archive libraries, on Unix systems you will need to add - fullpathname to $(INSTALL_LOCATION)/lib/$(EPICS_HOST_ARCH) to - your LD_LIBRARY_PATH environment variable. - - Win32 PATH - On WIN32 systems, building shared libraries is the default - setting and you will need to add fullpathname to - $(INSTALL_LOCATION)/bin/$(EPICS_HOST_ARCH) to your path. - Building shared libraries is determined by the value of the - macro SHARED_LIBRARIES in CONFIG_SITE (either YES or NO). - - - 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 TORNADO 2 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 build settings - configure/os/CONFIG..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 cross settings - configure/os/CONFIG.. - 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. - -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/ directories. Libraries are - installed into $(INSTALL_LOCATION)/lib/. 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. 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. - -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. 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/ directory during the base build. - - Instructions for building and executing the 3.14 example application - can be found in the section "Example Application" of Chapter 2, "New - Features for 3.14", in the "IOC Application Developer's Guide - R3.14.0beta1". The "Example Application" section briefly explains - how to create and build an example application in a user created - directory. It also explains how to run the example application on a - vxWorks ioc or a host system and run an example channel access client - on the host system. +Installation and release information can be found in the +various files in the documentation subdirectory. +Additional information about EPICS including mailing list +archives and subscription instructions, documentation and +training materials, additional components, links to other +websites etc. is available on the EPICS home page at + http://www.aps.anl.gov/epics/