##########################################################################
#                                                                        #
# Copyright 2002 Rational Software Corporation.                          #
# All Rights Reserved.                                                   #
# This software is distributed under the Common Public License Version   #
# 0.5 (CPL), and you may use this software if you accept that agreement. #
# You should have received a copy of the CPL with this software          #
# in the file LICENSE.TXT.  If you did not, please visit                 #
# http://www.opensource.org/licenses/cpl.html for a copy of the license. #
#                                                                        #
##########################################################################

 
ClearCase::CtCmd is an interface to Rational ClearCase.  For support, 
contact support@rational.com.  For installation instructions, see
INSTALL.


##########################################################################
#									 #
# Documentation								 #
#									 #
##########################################################################

ClearCase::CtCmd is self-documenting through the Perl POD (Plain Old
Documentation) facility.  After installation, "perldoc ClearCase::CtCmd"
will display the self-documentation.  Before installation the command
"perldoc -F CtCmd.pm" may be used from the installation directory.

##########################################################################
#									 #
# Signals								 #
#									 #
##########################################################################

In the interests of simplicity, performance and cross platform 
compatiblity ClearCase::CtCmd does not save/restore user signal 
handlers upon entrance/exit.  Users are, of course, able to explictly
restore their signal handlers with the $SIG{<signal>} = <handler ref>
mechanism after each invocation of ClearCase::CtCmd::exec(), 
and, under the terms of the License, free to modify CtCmd.xs
by inserting appropriate sigaction() or other function calls to store
and restore any or all signal handlers while entering and exiting 
CtCmd.xs:exec(...).  

Please note that the above behavior is consistent with other Rational
API products, including the ClearCase Automation Library  and the 
C API to ClearCase.

##########################################################################
#									 #
# Limitations - libperl.so						 #
#									 #
##########################################################################


On Solaris and presumably other Unix/Linux, 
/usr/atria/shlib/libperl.<shared object extension> on ClearCase v4.1 and v4.2 
can conflict with the user's perl installation if the user's perl is built 
as a wrapper around  a shared object of the same name, e. g., "libperl.so". 

Workarounds:

A.  Do not build Perl as a shared object.  

    pro:   Simple
    con:   Requires user to rebuild Perl. Since libperl.so is shared, 
           loses advantage of significantly less memory use when
           there are multiple Perl interpreters running. 

B.  Build a shared Perl using some name other than "libperl.<shared object extension>."

    pro:   Simple. Run Configure/modify the config.sh useshrplib,
           libperl and dflt variables, assigning some name other than
           "libperl.so" to libperl. "libperl561.so" does nicely.
    con:   Requires user to rebuild Perl. 

C. Another workaround is for the user (where, for example,  a shared Perl 
	is installed in /opt/perl_5.6.1) to:

	1. From the CtCmd directory, run "perl Makefile.PL; make". 
	2. copy  /usr/atria/shlib/libperl.so to 
		./blib/arch/auto/ClearCase/CtCmd/liboldperl.so
	3. run the following command:

LD_RUN_PATH="/usr/atria/shlib:/usr/lib:/var/tmp/CtCmd" ld  -G -L/usr/atria/shlib -L/usr/local/lib CtCmd.o -Lblib/arch/auto/ClearCase/CtCmd -R/usr/ucblib  -R/usr/atria/shlib -R/shlib  -R/opt/perl_5.6.1/lib/sun4-solaris/auto/ClearCase/CtCmd  -R/opt/perl/5.6.1/lib/site_perl/auto/ClearCase/CtCmd -Rblib/arch/auto/ClearCase/CtCmd -o blib/arch/auto/ClearCase/CtCmd/CtCmd.so -lzuba  -L/var/tmp/CtCmd  -latriacmdsyn -latriacmd -latriasumcmd -latriasum -latriamsadm -latriamntrpc -latriacm -latriavob -latriaview -latriacm -latriadbrpc -latriatirpc -latriaxdr -latriamvfs -latriatbs -latriaadm -latriasplit -latriacredmap -latriaks -lezrpc -lrpcsvc -latriaccfs -latriasquidad -latriasquidcore -lc -lw -lCrun -loldperl

	(The above will have to be on one line.)

	Now, in lieu of "make test",

	4.  perl -Iblib/lib  -Iblib/arch  t/t1_createArch.t

	5. perl -Iblib/lib  -Iblib/arch  t/t2_tstArch.t

	6. perl -Iblib/lib  -Iblib/arch  t/t3_cleanArch.t

	will run the test suite verbosely and clean up, hopefully with no failures. 

	7.  Copy the contents of  ./blib/arch/auto/ClearCase/CtCmd/ 
	(three files ending in .so ) to 
	/opt/perl_5.6.1/lib/sun4-solaris/auto/ClearCase/CtCmd . 
	Directories will have to be created first. 

	8. Copy blib/lib/ClearCase/CtCmd.pm to  
	/opt/perl_5.6.1/lib/sun4-solaris/ClearCase/CtCmd.pm .  
	Directories will have to be created. 


