-----------------------------------------------------------------------------
 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.






