Release notes for PureCoverage version 2003.06.00 HP-UX
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.
- Purecov now supports 64-bit applications. Please refer to the
section "Restrictions and Known Issues" for the limitations in
the current version.
- Support for shared libraries built with +init or +fini linker option.
- Support for gcc/g++ 3.0.x and 3.1 compiler (32-bit only).
- 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 aCC 3.31 and 3.33 compiler
- Support for ld/dld version 11.30
- Support for dlopen, dlclose, dlsym calls in 32-bit applications.
You can make calls to the above dynamic library routines,
and Purecov will make sure those libraries are instrumented as well
for coverage checking.
- Two new options -lib-path-length and -replace-path are added
to Purecov. These options help one to relocate the cache.
For information on the options and how to move the cache,
please refer to the online documentation.
Please see the section "Restrictions and Known Issues"
for more details.
New in PureCoverage 2002.05.00
=========================
- Bug fixes and compatibility with OS patches.
- Support for gcc 2.95.2 and 2.95.3 compilers.
- Support for aCC 3.27 and 3.30 compilers.
- This release supports the LD_PRELOAD environment variable. This
feature is available on HP-UX 11.00, AR0301(DART52) or later
releases. Please see the section "Restrictions and Known Issues"
for known issues with LD_PRELOAD usage.
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.2 for HP-UX
- This release supports HP-UX 11.11.
- This release does not support HP-UX 10.01 and 10.10.
- This release supports objdebug style debug information generated by
cc and aCC compilers. This feature is supported on HP-UX versions
11.00 and higher only. With the +objdebug option to the compiler,
extra debug information is placed into each object file to help
the debugger locate the object file and to quickly find global types
and constants.
==================================================
Supported systems
=================
Operating system and Hardware
-----------------------------
PureCoverage has been tested with HP-UX versions 10.20, 11.00 and 11.11
from Hewlett Packard.
Compilers
---------
PureCoverage has been tested with the following compilers:
- Bundled cc.
- ANSI cc.
- C++.
- aCC versions 3.27, 3.30, 3.31, and 3.33.
- GNU gcc and g++ versions 2.8.1, 2.95.X, 3.0.x, 3.1 (32-bit only)
- Cygnus GNUpro v.98r2
Threads
-------
PureCoverage supports these threads packages:
- DCE threads (either libdce or libcma).
- HP-UX kernel 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.
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.
64-bit Development
------------------
- PureCoverage supports both 32-bit and 64-bit application development, and
will select the correct mode of operation automatically based on inputs.
The product banner will report the mode of operation during
instrumentation and at runtime. However, the "-version" option will
always report 32-bit mode; the product version is the same for both modes.
The product home directory has been reorganized to support both
32 and 64-bit development. This organization should be transparent
for all 32-bit users and most 64-bit users. However, the location of
the PureCoverage stubs library is different for 64-bit applications:
32-bit libraries have been moved to the lib32 sub-directory:
purecovhome/lib32/purecov_stubs.a
purecovhome/lib32/libpurecov_stubs.a
To preserve backward compatibility, the following links are provided
in purecovhome:
purecovhome/purecov_stubs.a
purecovhome/libpurecov_stubs.a
32-bit API users are encouraged to use the libraries from the lib32
sub-directory, and not from purecovhome.
64-bit API users must link against the equivalent library in the
lib64 sub-directory:
purecovhome/lib64/purecov_stubs.a
purecovhome/lib64/libpurecov_stubs.a
The API header file has not moved and is shared for both development
modes.
Purecov 64
----------
- Currently Purecov does not support 64-bit static executables.
- Thread local storage is currently not supported.
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").
- Archive libraries containing both 32-bit and 64-bit libraries are
not supported. All components of a link must be of the same file type.
- gcc/g++ 3.1 compilers are not supported on HP-UX 10.20 platform.
- 64-bit applications produced by gcc/g++ 3.1 compilers are not
supported.
- gcc/g++ 2.8.1 is supported, but there are known problems with
C++ shared libraries containing exception handling code.
- 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.
- Using PureCoverage with HP-UX linker version 11.13 or older may cause
instrumented 32-bit applications to hang. An upgrade of linker
should solve the problem.
- PureCoverage does not have SDK / XDK support, a feature available with
the HPUX Compiler Tool chain from the AR1201 release.
- PureCoverage does not support filtered libraries.
- Instrumented programs now always use immediate binding for the initial
load of shared libraries and for any dynamic loads using shl_load().
- PureCoverage will not run on short (14-character) file systems.
- Operating system revisions earlier than HP-UX 10.20 are no longer
supported.
- The PA-RISC 1.0 CPU is no longer supported.
- Profile Based Optimization is not supported.
- Applications which link to over 50 large dynamic libraries may
experience reduced startup times by setting the runtime option
-lazy-dld-maps=1.
- Shared libraries are never unloaded. When a program attempts to
unload a shared library through a call to shl_unload or dlclose,
the call will appear to succeed, but the library will not actually
be closed or unloaded. As a consequence, the "fini" sections
(which usually comprise the C++ "static destructors") are not run
for shared libraries.
Using LD_PRELOAD
----------------
- For 64-bit applications, use of environment variable LD_PRELOAD
is supported only with instrumented shared libraries. If any of
of the libraries in the LD_PRELOAD environment variable are not
instrumented, the application may crash.
- For 64-bit applications running on HP-UX 11.00 or later systems
with a version of dld which does not support LD_PRELOAD, the
instrumented application will give an error message and quit,
if the environment variable LD_PRELOAD is set and contains any
uninstrumented shared libraries. In this case, unsetting the
environment variable LD_PRELOAD will cause the application to
execute normally.
- For 32-bit applications running on HP-UX 11.00 or later systems
with a version of dld which does not support LD_PRELOAD, the
instrumented application will check the environment variable
LD_PRELOAD and instrument any uninstrumented libraries given in
the LD_PRELOAD value. This instrumentation is harmless and does
not affect the functionality of the program in anyway. To prevent
this unnecessary instrumentation, users should unset the
environment variable LD_PRELOAD before running the application.
- Invoking the viewer with "purecov -view" or "purecov -version"
when LD_PRELOAD is set may sometimes cause the viewer to crash.
This can be overcome by unsetting LD_PRELOAD and then
invoking PureCoverage.
Using 32-bit vs 64-bit PureCoverage
------------------------------
PureCoverage supports both 32- and 64-bit development. "Wide" mode, or 64-bit
applications are those compiled with the +DA2.0W option - applications
using 64-bit pointers. "Narrow" mode applications are traditional
32-bit programs. Both are installed on the same file system, but the
64-bit version can only be used on 64-bit HP-UX 11.x systems.
If you attempt to use the 64-bit PureCoverage using -ptr64 on a non
11.x systems, execution will fail. It only runs on HP-UX 11.x and later.
- Restrictions on the HP-UX 11.00-wide
(64-bit) version of PureCoverage:
- Using PureCoverage with old versions of the HP-UX linker may cause the
install test to fail with an error from the linker saying the
"+nodynhash" option is not recognized. You should obtain a newer
linker from HP. This option is support by 64-bit linkers from
07-Jan-1999 and later.
You may also work around this problem by include the following in your
PUREOPTIONS environment variable:
-force-no-dynhash=no
The default setting of this option (to "yes") is used to work around an
HP bug in newer linkers.
- There is a bug in strlen in the 64-bit libc which causes the example
program "hello.c" to get numerous UMR's instead of only one, as you
might expect.
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.
- When a Japanese locale is specified using the LANG environment variable,
instrumentation of archive libraries may fail with the message:
Error: Child process exited with status = 1.
This is caused by an 'ar' failure in this locale. A workaround is to
unsetenv LANG before instrumenting.
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).
- C revisions 9.61 through 9.65
- These compilers generate incorrect debugging information for some
functions. Programs compiled using these compilers may not be
debuggable after translation. In this case PureCoverage may produce a
message beginning "Failure relocating..."
Additionally PureCoverage may not be able to attach coverage
information to specific line numbers in such cases.
HP patch PHSS_4923 corrects this problem.
- Exception handling
g++ 2.7.2 exceptions are not supported.
Debuggers
---------
- XDB & Softdebug
- Use purecovhome/purecov_xdb to
invoke xdb on an instrumented program.
- An instrumented program receives a signal 18 (death of child) during
its initialization. Place "z 18 sir" in your ~/.xdbrc file to
suppress this warning. Failure to suppress the warning will sometimes
cause xdb to fail.
- XDB, when debugging a program that uses shared libraries, reads
the symbol table from /lib/dld.sl. However, PureCoverage has changed
your program to use an instrumented version of dld.sl. The
symptom of this mismatch is the message:
Wait...loading shared-library map tables.
xdb panic: Mapped addresses for dld
overlap text segment for dld
There is a simple workaround for this problem and we've implemented
it in the
shell script purecovhome/purecov_xdb.
Whenever you use xdb on an instrumented program use this script to
invoke xdb.
- Typing ^C while running an instrumented program under xdb requires
caution. There is a high probability that the interrupt will occur
inside the code PureCoverage has added to your application. If this is
the case, you must single step or set a breakpoint and continue
before you attempt to call any subroutines (the PureCoverage API is an
example).
- The XDB single stepping command, 's' sometimes fails to find the
next source line. When this happens, usually near a subroutine
call, program execution continues until the next breakpoint. The
'S' command is always reliable.
- DDE - Distributed Debugging Environment
- The DDE debugger at release 2.10 has been used with instrumented
programs. The shell
script: purecovhome/purecov_dde
implements one of the workarounds.
- Instrumented programs get a SIGCHLD signal at program initialization.
One workaround is to just hit "go" when the program stops. The
following commands added to a .dderc file also help:
prop system -on
alias `after_debug delete intercept signal SIGCHLD; \
prop system -off; \
breakpoint -in main -entry -exit; \
go
Old Style Fixups
----------------
PureCoverage does not support a type of relocation information known as "old
style fixups". These were generated by HP-UX system software before
release 3.0. If PureCoverage detects old style fixups the message:
Object file has incompatible format
(may be older than HP-UX 3.0)
is generated. We have seen this problem with HP's libsql.a and some of
Oracle's Oracle6 libraries.
There is a simple workaround. Given a problem object module (or modules)
the workaround is to have /bin/ld build a new object module. Suppose
the old object modules are called `foo.o' and `bar.o'. Issuing the command:
% ld -r -o new_foo.o foo.o
% ld -r -o new_bar.o bar.o
or
% ld -r -o foo_and_bar.o foo.o bar.o
would generate a new object module where the old style fixups have been
removed.
In the case of an archive file the following script will create a new
archive given the full pathname of the original:
#!/bin/sh
# Remove old fixups from an archive.
# Supply original .a name as first argument.
cd /tmp
lib=new_`basename $1`
ar x $1
rm -f $lib
for member in `ar t $1` ; do
ld -r -o _$member $member
ar q $lib _$member
rm $member _$member
done
echo Created `pwd`/$lib
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.