Release notes for PureCoverage version 2003.06.00 Solaris 2
Contents
========
o Changes from previous releases
o Supported systems
o Restrictions and known issues
New in this release
===================
- Bug fixes and compatibility with OS patches.
- Support for Solaris 9.
- Support for gcc/g++ 3.0.x and 3.1 compiler (32-bit only).
- Support for 32-bit JNI applications using JDK 1.2.X and 1.3.1.
Please refer to the "Restrictions and Known Issues" section for
details.
- This release supports Java programs. JVM versions 1.3.1 and 1.4
are supported on Solaris 2.6. JVM versions 1.3.1, 1.4 and 1.4.1
are supported on Solaris 7 and newer versions of the operating
system, as long as the JVM is supported on that OS version. For
information on the Solaris versions supported by a JVM release,
please refer to the Sun Microsystems websites:
http://java.sun.com/j2se/1.3/relnotes.html
http://java.sun.com/j2se/1.4/relnotes.html
http://java.sun.com/j2se/1.4.1/relnotes.html
Refer to the "PureCoverage for Java" online document for
PureCoverage usage instructions. Use the link on the main page
for PureCoverage online help to view the "PureCoverage for Java"
supplement. For product details, please look at the "Restrictions
and Known Issues" section.
- This release supports viewing Unix data with the Windows product.
Please see the section "Restrictions and Known Issues" for known
issues with this feature.
New in PureCoverage 2002a.06.00
===============================
- Bug fixes and compatibility with OS patches.
- Modified support for Change Request Management
systems, including Rational's ClearQuest and
ClearDDTS. Please see online help for more
information.
- Support for Forte 7 compiler (compiler version 5.4).
- This release does not support Solaris 2.5.1 (SunOS 5.5.1).
New in PureCoverage 2002.05.00
=========================
- Bug fixes and compatibility with OS patches.
- Support for Forte 6 Update 2 compiler (compiler version 5.3).
- Support for gcc 2.95.3 compiler.
- This is the last release to support Solaris 2.5.1 (SunOS 5.5.1).
New in PureCoverage 2001a.04.00
===============================
- Bug fixes and compatibility with OS patches.
- HTML-based online help system. See the "HTML Help" topic in the
Restrictions and Known Issues section.
- New product versioning system. This release
is the successor of:
PureCoverage 5.3 for Solaris
- Support for Forte 6 Update 1 compiler (compiler version 5.2).
- Support for gcc 2.95.2 compiler.
==================================================
Supported systems
=================
Operating system and Hardware
-----------------------------
PureCoverage has been tested with Solaris versions 2.6, 7, 8 and 9 on
SPARC platforms.
PureCoverage has also been tested on V8 and V8+ SPARC programs on the
UltraSPARC.
Compilers
---------
PureCoverage has been tested with the following compilers:
- Forte 7 (compiler version 5.4)
- Forte 6 Update 2 (compiler version 5.3)
- Forte 6 Update 1 (compiler version 5.2)
- Forte 6 (compiler version 5.1)
- Sun Workshop C and C++ 4.2 and 5.0
- GNU gcc and g++ versions 2.8.1, 2.95.X, 3.0.x, 3.1 (32-bit only)
- Cygnus GNUpro v.98r
Threads
-------
PureCoverage supports these threads packages:
- The native Solaris libthread library.
- The Solaris Pthreads library, libpthread.
- Transarc DCE threads.
==================================================
Restrictions and Known Issues
=============================
Java Language Support
---------------------
- To use PureCoverage with JNI applications using JDK 1.2.X, please
refer to Solution ID 22506 on:
http://solutions.rational.com/
or contact Rational Technical Support and reference Solution ID 22506.
- To use PureCoverage with JNI applications using JDK 1.3.1 or higher,
please refer to the Solution ID 134726221 on:
http://solutions.rational.com/
or contact Rational Technical Support and reference Solution ID 134726221.
- PureCoverage for Java requires certain Java functions packaged in the
Rational.jar file. Part of the functionality provided by Rational.jar
is implemented in C/C++ and packaged as a shared object
libQProfJ.so. The default Java security manager disallows
running these files when executing applets. We currently
work around this problem by placing the Rational.jar file in your
<$JAVA_HOME>/jre/lib/ext directory. This is a special directory
for Java and the files placed here are given special permissions. If
you do not have write access to $(JAVA_HOME)/jre/lib/ext,
PureCoverage fails to place Rational.jar in the ext directory.
In that case, you must manually copy or link
Rational.jar from purecovhome to
the $(JAVA_HOME)/jre/lib/ext directory for PureCoverage to work.
The Rational.jar file or link in the $(JAVA_HOME)/jre/lib/ext
needs to be updated whenever the purecovhome location is moved,
either due to an install in a new location, or due to an upgrade.
If the link or copy is not updated, Java programs containing PureAPI
calls cannot be compiled.
While running certain Java-enabled programs such as Netscape,
stderr and stdout are redirected to /dev/null and the messages
that PureCoverage generates about Rational.jar and java security are
not displayed. If you are running applets and, your program, when
run with PureCoverage, crashes early in the run, it may be because of
this security problem. Please first make sure
that Rational.jar is present in $(JAVA_HOME)/jre/lib/ext and rerun
your program.
- PureCoverage for Java dumps core with some programs on Java 1.3.x.
This is most likely because of a JVMPI bug (bug number 4363175
in Sun's Java bug database). Please run the program with the
Java -Xint option. This restriction does not apply to Java 1.4.X.
The JVMPI bug is fixed in all versions of Java 1.4.X.
- The PureCoverage summary message, generated at the end of a run and
for each PureAPI.SaveData API call, shows the name of the program
that runs the Java virtual machine, instead of the name of
your Java program.
For example, if you run:
"purecov -java java MyClass"
The PureCoverage summary message displays:
"Saving coverage data to /people/anandi/test/java/java.pcv."
instead, it should display the message as:
"Saving coverage data to /people/anandi/test/java/MyClass.pcv."
- It is not possible to run PureCoverage for Java on Netscape version 4.7x.
To profile Java code running in Netscape, you must use
Netscape version 6. Note that Netscape 6 requires Solaris 7 or
later versions of the OS.
The Netscape version restriction is only for profiling Java code
using Netscape. It does not apply to using Netscape to access
online help. PureCoverage online help works with Netscape version 4.7x
on all versions of Solaris. Refer to the section on "HTML help"
later in this file to view the help pages independent of PureCoverage.
- Netscape 6 pipes all stdout, stderr output to /dev/null.
This implies that the messages that PureCoverage generates are
not displayed. When running PureCoverage with Netscape 6,
please use the -debug option to Netscape to view PureCoverage output:
For example:
purecov -java netscape -debug
- The option -copy_fd_output_to_logfile is not working with java.
- The option -follow-child-processes=no is not working with java.
Licensing Troubleshooting
-------------------------
- When PureCoverage is properly installed, a .lm_license_file file is
created in the product home directory to allow PureCoverage to locate
your licenses even when LM_LICENSE_FILE is not set appropriately
in the user's environment. If you get a message such as:
Error: Unable to open /product_home/.lm_license_file.
Your installation is incomplete. Did you run rs_install? ...
Check your product home directory to see if .lm_license_file exists
and is readable by you. If the file does not exist, your installation
is incomplete. You may need to re-run rs_install or license_setup.
If the permissions are incorrect, change them so that the file is
readable by all expected users of PureCoverage.
- If you manually change the location of your licenses (e.g. without
using license_setup), the .lm_license_file will not be updated and
you will not be able to checkout a license unless you set the env
var LM_LICENSE_FILE to point to the new location. You should always
use license_setup to make changes to your licenses.
- Be sure you install the products that correspond to your license(s).
Do not install PurifyPlus unless you have a PurifyPlus license or
another valid license. To check your license, locate the "INCREMENT"
line(s) in your license file (*.dat) or license update file (*.upd).
The license feature name is the first word on the line after "INCREMENT".
For example:
INCREMENT PurifyPlusUNIX rational 5.0 10-jan-2001 1 1234556789012
^^^^^^^^^^^^^^
HTML Help
---------
This product has an HTML based online help that incorporates all the
information from the product user manual.
The following restrictions and notes apply to using the HTML help system:
- The only supported browser for the HTML based help system is
Netscape Navigator, versions 4.7.x. The HTML based help system
does not work with pre 4.7 versions or with 6.x versions.
- You may view the help in stand-alone mode by pointing your browser to
the following:
product_home/UI/html/pcu.htm
(Where "product_home" is the installation location of PureCoverage. e.g. the
result of the -printhomedir option.)
- Netscape must be on your path when you run your instrumented program.
Your path is used to locate the browser.
- The first time you request help from a viewer, a new netscape session
will be started, even if you already have netscape running. This session
will be re-used by subsequent help requests unless you re-use the
launched browser for another purpose. If you close the browser, a new
browser will be launched upon the next help request.
- The new help system uses Javascript. On some platforms, the MOZILLA_HOME
environment variable must be set in order for Javascript based web pages
to work properly. If you experience Java related problems with the help:
Make sure your netscape installation directory is on your path and that
MOZILLA_HOME is either not set at all (we will set it for you) or is set
to the same installation directory.
If MOZILLA_HOME is set but does not point to the same netscape
installation as the netscape on your path, the help may not work
correctly.
If MOZILLA_HOME is not set at all, PureCoverage will attempt to set it when
we start netscape. But we will be unable to set it correctly if the
netscape found on your path does not resolve to an actual installation
directory. For example, if netscape actually references a wrapper script
in /usr/local/bin. In this case, you will need to set MOZILLA_HOME
explicitly.
See the Netscape release notes for more information on MOZILLA_HOME.
- Use the Help->Help Topics menu item to access the top level of the
help system.
- Context sensitive help is available on leaf menu items and on buttons
ONLY. For information about a window, use the Help->On Window menu item.
- PDF versions of the PureCoverage Quick Reference card is available in the
doc/pdf section of your installation, if you have installed PDF
documentation. Otherwise, see the corresponding area of your
installation CD.
General
-------
- PureCoverage does not present accurate line-by-line coverage data in the
annotated source window if the code is compiled with both debug and
optimization flags.
- If PureCoverage is run in "/tmp" or "/usr/tmp" or "/var/tmp" the generated
instrumented *.o files are deleted in these directories. Please do
not use commands such as:
purecov cc -nolink ld file.o
in "/tmp" or "/usr/tmp" or "/var/tmp" .
However there is a work-around for this , You can use the option
"-save-tmp-files" to tell PureCoverage not to delete the generated objects.
So using:
purify -save-tmp-files cc -nolink ld file.o
will generate the instrumented file_pure_*.o in "/tmp" or "/usr/tmp"
or "/var/tmp". Otherwise you can use -always-use-cache-dir so that
the generated file_pure*.o is generated in cache-dir where it is not
deleted (Note: if cache-directory is installed in "/tmp","/usr/tmp",
"/var/tmp" the generated *_pure_*.o in cache are not deleted, so you
can have the cache-directory safely in "/tmp","/usr/tmp","/var/tmp").
The product home directory has been reorganized. The new layout
should be transparent to most users. All libraries have been moved
to a lib32 sub-directory, but top level links preserve backward
compatibility for accessing the stubs libraries.
Users are encouraged to use the libraries from the lib32 directory,
and not from purecovhome.
In the unlikely event you need to access private libraries such as
solaris2_threads.so, and you use -printhomedir to construct the path,
you must now add a "lib32" component to the path:
`purecov -printhomedir`/lib32/solaris2_threads.so
Reference to these libraries is rarely necessary.
- Because of operating system differences, programs instrumented on one
version of Solaris may crash or generate incorrect results if run on
a different version of the operating system.
- PureCoverage does not support use of the LD_PRELOAD environment variable.
- The SPARCWorks incremental linker, ild, is automatically disabled by
PureCoverage due to an incompatibility with file naming conventions.
- If you are running your application on a different machine from the one
on which it was built, please ensure that both the machines have the
same operating system. Further, the system libraries on the two machines
should be identical. Otherwise, PureCoverage might generate a warning message.
For more details on how to build and run on different machines, please
please see Solution ID 5829 at:
http://eservice.rational.com/solutions
Or contact Rational Technical Support and reference Solution ID 5829.
- PureCoverage intercepts calls to dlclose() and can prevent
dynamically loaded libraries from being unmapped. This has
the effect of preventing static destructors from running but allowing
coverage data for such libraries to be saved at program exit. By default,
PureCoverage allows libraries to be unmapped, at the expense of
not saving coverage data for such libraries. Or it can save
coverage data just before unmapping.
The -dlclose-mode=i option controls this behavior :
-dlclose-mode=0 : libraries may not be unmapped.
-dlclose-mode=1 : libraries may be unmapped.
-dlclose-mode=2 : libraries may be unmapped, coverage data is saved
Viewing Unix Data on Windows
----------------------------
As described in the online help topic "Viewing UNIX ... data on
Windows", it is possible to generate PureCoverage for Unix data in a
format suitable for viewing with PureCoverage for Windows.
To take advantage of this feature, you must have a PureCoverage for
Windows license and you must use PureCoverage for Windows version
2003.06.00 Proto Build 4619 or later.
The following limitations apply to viewing Unix data on Windows:
- PureCoverage for Windows Build 4619 cannot open annotated source files
automatically unless they are co-located with your data file or you
use the new Unix "substitute" directive. For more information about the
substitute directive, refer to the PureCoverage for Unix online help.
PureCoverage for Windows releases after Build 4619 include a pathname
substitution feature as part of the GUI; see the PureCoverage for
Windows documentation for details.
- If your data file is co-located with your Unix executable and you
access your data file from Windows via a Samba file share, opening
the data file may remove owner execute permission on your executable.
If possible, do not share your Unix file sytems via Samba.
- Certain features of PureCoverage for Windows are disabled when viewing
Unix-generated data. These include File->Run Again and
Settings->Executable Settings. The execution environment of your
program can only be affected on Unix.
- Coverage statistics viewed using PureCoverage for Windows will not always
exactly matching the information displayed by PureCoverage for Unix:
PureCoverage for Windows does not handle inline functions in the same
fashion as PureCoverage for Unix. You may see the same function listed
multiple times in PureCoverage for Windows, once for each place it was
inlined.
When multiple functions record coverage statistics against the same
source lines, PureCoverage for Unix accumulates all the statistics and
reports them against only one of the functions. PureCoverage for Windows
does not do this - you will see coverage statistics for each function
separately. This usually only occurs with compiler generated functions
in C++ and Java.
- If your Unix source file location is mapped to the root directory of
a Windows mapped drive (i.e. F:\foo.c) and there are multiple modules
(.o or shared library files) in this directory, the PureCoverage for
Windows "File View" may not expand properly. Use the PureCoverage for
Windows "Module View" instead or map your source location to Windows
one directory higher. i.e. so that you have F:\parent\foo.c instead of
just F:\foo.c.
User Interface
--------------
- The PureCoverage GUI menus and buttons become inaccessible if either the
NumLock or ScrollLock key is activated. The workaround is to switch
them off, or add the following line(s) to your $HOME/.Xdefaults file.
! Ignore the NumLock and ScrollLock keys on
! mouse buttons
PureCoverage*ignoreModifierMask: Mod3|Mod2
This second workaround will take effect for a new PureCoverage viewer after
you restart your X-session or run a command like 'xrdb -merge
$HOME/.Xdefaults'.
Compilers
---------
- The GNU gcc extensions are not tested against PureCoverage. Most gcc
extensions will probably work fine. Known limitations at present
include problems with nested functions (e.g.: making a pointer to a
nested function and attempting to call through it will not work).
Threads
-------
- Customers using unsupported threads packages should contact Rational
Software technical support (support@rational.com) to ensure compatibility.
Copyright Notice
----------------
The following copyright applies to portions of the ClearQuest
integration and HTML based help system.
Copyright 1996 Netscape Communications Corporation, all rights reserved.
Created: Jamie Zawinski (jwz@netscape.com), 24-Dec-94. Permission to
use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided
that the above copyright notice appear in all copies and that both
that copyright notice and this permission notice appear in supporting
documentation. No representations are made about the suitability of
this software for any purpose. It is provided "as is" without express
or implied warranty.