From 1ce15d81375f6fed87c00e95d855fcb8ba566dc0 Mon Sep 17 00:00:00 2001 From: "Janet B. Anderson" Date: Fri, 31 Aug 2001 16:22:56 +0000 Subject: [PATCH] Adding txt version of README.htm. --- README | 483 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 483 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 000000000..d437a6107 --- /dev/null +++ b/README @@ -0,0 +1,483 @@ +README + + Installation Instructions + + EPICS base + + Release 3.14.0alpha3 + +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 + cp.pl This Perl script copies an + existing file + installEpics.pl Installs built files into install + directories. + makeConfigAppInclude.pl Generates include,bin, lib dir + definitions + makeDbDepends.pl Generates dependencies from + substitution files + makeIocCdCommands.pl Generates cdCommands file for use + in IOCs + makeMakefile.pl Creates a Makefile in O. + dirs + makeMakefileInclude.pl Creates file to be included by + Makefile + makeRulesInclude.pl Creates .h depends files included + by Makefile + mkdir.pl Creates a directory (like Unix + mkdir) + 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 + + 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. + + On WIN32, some versions of Perl require that the + environment variable PERLLIB be set to . + + 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 your path, and the c compiler may require ld in your 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. On + WIN32 systems, building shared libraries is the default + setting and you will need to add fullpathname to + $(INSTALL_LOCATION)/lib/$(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 the + definitions in your base/configure 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++ 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 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/ 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.0alpha3" . 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. + +