----------------------------------------------------------------------------- Copyright (c) 1995 Southeastern Universities Research Association, Continuous Electron Beam Accelerator Facility This software was developed under a United States Government license described in the NOTICE file included as part of this distribution. ----------------------------------------------------------------------------- PACKAGE NAME: cdev PURPOSE: To provide a simplified and extensible object oriented interface to the services provided by any control system or other message based system. VERSION: 1.7.2 DESCRIPTION: The cdev (common device) C++ library is designed to provide a standard application programming interface (API) to one or more underlying packages, typically control system interfaces. The implementation is in 2 layers: the uppermost layer is used directly by an application, and provides an abstraction of the underlying package as well as many general purpose features. The second layer (service layer) provides the interface to one or more underlying packages, and is implemented as loadable libraries. cdev was initially developed at Jefferson Lab in collaboration with the EPICS community, and is now available to anyone to take. It has been interfaced to a variety of accelerator control systems, including EPICS, systems at SLAC, CERN, Brookhaven and others. We welcome all comments, suggestions, bug reports, and (especially) bug fixes. There are many planned enhancements, and we welcome volunteers to contribute to this project. See the release notes for a summary of planned features. DIRECTORIES: ./src * cdev source parent directory, * contains makefiles and subdirectories * with the source code necessary to * create the cdev libraries ./src/ca (only used by EPICS) ./src/cdevIO ./src/common ./src/callback ./src/device ./src/directory ./src/group ./src/lib ./src/namesvc ./src/system ./src/utility ./extensions * cdev network extensions to allow quick * and easy development of cdev servers ./extensions/cdevGenericServers ./extensions/SimpleService ./include * header files for cdev applications, * this directory will be populated * during the first execution of make ./lib * cdev library parent directory, this * directory will be populated with * subdirectories that contain target * specific libraries and object files ./lib/hpux-09.XX ./lib/hpux-10.XX ./lib/solaris ./lib/Linux ... ./bin * cdev binary parent directory, this * directory will be populated with * subdirectories that contain target * specific sample applications created * with the cdev libraries ./bin/hpux-09.XX ./bin/hpux-10.XX ./bin/solaris ./bin/Linux ... ./applications * ./applications/cdevGateway. A simple cdevGateway using cdevGenericServer library. ./doc * directory containing the most up-to-date * cdev documentation. BUILDING CDEV: After installing the cdev package from the distribution media to the target directory, the user should be aware of the following considerations prior to starting a build. Configure cdevDirectory and static services: This must be done before any installation procedures. cdev supports dynamically linked services as well as statically linked (archive library) services. In each case, services are accessible by name. For statically linked services, cdevDirectory must be configured to reference all needed services so that they are linked in at load time. Additionally, cdevDirectory supports a default service which is used if no entry in a ddl file (or other user supplied directory service) for that operation. cdev is shipped with code to default to the EPICS channel access library. This default is enabled by defining the flag _HAS_CA. There is a script (configSvc) in the src directory to assist in generating the proper code for the default service and statically linked services. Example: You wish to use the EPICS channel access (ca) service and a service with name xyz, and want to enable defaulting to ca: configSvc services=ca xyz \ headers=/usr/local/epics/base/include \ /usr/local/cdev/src/ca /usr/local/cdev/src/xyz \ flags=_HAS_CA The headers are the include directories needed for these services. The services are the names of the services. The configSvc will generate Makefile and cdevSvcConfig.cc in src/directory directory. MAKE VARIABLES: The cdev makefiles require several environment variables to be specified in order to compile correctly. These variables may either be entered explicitly on the make command line or may be specified in the local environment. The following variables should be specified... MAKE This variable specifies the make command that will be used in the makefiles of the subdirectories. Always use gnu make. CDEV top directory of cdev. CDEVSHOBJ directory in which shared libraries for services are installed. EPICS This variable contains the EPICS root directory. This variable is undefined by default, and must be specified by the user if one wants to build channel access service. EPICSLIB This variable contains the EPICS library path. It is used when one wants to build channel access service. COMPILING THE DISTRIBUTION: In order to compile this distribution you must perform the following steps. 1) Determine the required values of the makefile variables listed that will be necessary to compile cdev for your system. 2) Go to $CDEV/include/makeinclude directory. Make a link to a right makefile. For example, on a Sun running solaris, do ln -s Makefile.solaris Makefile.OS 3) Change directories to the cdev distribution src directory. This is where the Makefile and Makefile.config will be located. 4) If you have compiled the cdev distribution for and other TARGET in the past, you should execute a 'make clean' to remove any outdated object files. 5) If you want to change default timeout value and connection retry frequency in channel access of EPICS, you should change DEFAULT_TIMEOUT and DEFAULT_CONN_FREQUENCY values in the caRequestObject.h right now. 6) Run configSvc in the src directory. This will generate Makefile and cdevSvcConfig.cc in src/directory. 7) Type make, the output will tell you the following: Type one of the following: make hpux for HP systems make hpux-sl for HP systems building shared library make hpux-cl for HP systems with CenterLine make hpux-cl-sl for HP systems with CenterLine Building shared library make irix5 for SGI running irix5 make irix5-sl for SGI running irix5 building shared library make sunos4-gcc for SunOs 4.x and gcc make sunos4-gcc-sl for SunOs 4.x and gcc building shared library make solaris for Solaris2.x make solaris-sl for Solaris2.x and building shared library make solaris-gcc for Solaris2.x and gcc make solaris-gcc-sl for Solaris2.x and gcc building shared library make ultrix-gcc for ultrix 4.x and gcc make aix for IBM AIX 4.x make linux-sl for linux shared library make linux for linux archived library make clean Pick one from the above to build src distribution. If there is no one from the above list to match your platform, you can take a look at the Makefile.config to create one. Please send e-mail to us at cdev@jlab.org about your new makefile. 8) The libcdev.so or libcdev.a will be installed in $CDEV/lib/$(ARCH). and all services (caService.so) are installed in the $CDEVSHOBJ/1.7. All executables are installed in $CDEV/bin/$(ARCH). 9) Now you are ready to use cdev. If you decide to build extension part of cdev, you can go to extensions/cdevGenericServer directory. 10) Go to include/makeinclude directory. Make a link for a right Makefile. For example, on Linux machine, you will do ln -s Makefile.linux Makefile.OS. 11) Go back to $CDEV/extensions/cdevGenericServer. Type make (make sure it is gnu make). It should build everything from NameServer (rsvcServer) to libcdevGenericServer.a(so), libcdevClient.a(so), libcdevReactor.a(so), libcdevClientLite.a(so), librsvc.a(so) and rnsService.so. The rsvcServer will be in $CDEV/bin/$(ARCH), and rnsService.so is installed in $CDEVSHOBJ/1.7, the rest of them will be in $CDEV/lib/$(ARCH). 12) If you wish to use the generic CLIP service (used in communicating with CLIP servers written in Java), go to $CDEV/extensions/CLIPService and type make. The service will be placed into $CDEVSHOBJ/1.7. 13) If you wish to use cdevGateway (needed for Java clients), go to $CDEV/applications/cdevGateway and type make. Executable will be placed in $CDEVBIN and service in $CDEVSHOBJ/1.7. USING CDEV: After reviewing the documentation supplied with this cdev distribution, you should be able to construct a cdev application. In order to compile this application you must perform the following: 1) Specify the cdev header files that you will be using within the source code. 2) Add the path to the cdev include files to your compiler command line. example: -I$(CDEV)/include 3) Add the path to the cdev libraries to your compiler or linker command line. example: -L$(CDEVROOT)/lib/solaris 4) Specify the cdev libraries to be linked to your application on the compiler or linker command line. These libraries are libEpicsCa.a and libcdev.a. Additionally, the yacc, lex and math libraries must be linked. (EpicsCa only needed for programs statically linking to EPICS channel access.) a) Link with archived library example: -lcdev -lcaService -L$(EPICSLIB) -ly -ll -lm b) Link with shared library example: -lcdev -ly -ll -lm 5) Set the CDEVDDL environment variable. This is a variable specifying the location of DDL file (device definition file). This variable should be set prior to executing your new application. example: setenv CDEVDDL /usr/cdev/ddl/myFile.ddl 6) Set the CDEVSHOBJ environment variable if your application is linked with shared library. This is a variable specifying the directory of caService.so which contains all shared object codes for channel access. Default location is /usr/local/lib.