PureCoverage User’s Guide

1 user s GuideIMPORTANT NOTICEDISCLAIMER OF WARRANTYR ational Software Corporation makes no representations or warranties, eitherexpress or implied, by or with respect to anything in this Guide , and shall notbe liable for any implied warranties of merchantability or fitness for aparticular purpose or for any indirect, special or consequential NOTICEPureCoverage, copyright 1992-1997 Rational Software Corporation. Allrights part of this publication may be reproduced, stored in a retrieval system ortransmitted, in any form or by any means, photocopying, recording orotherwise, without prior written consent of Rational Software Corporation. Nopatent liability is assumed with respect to the use of the informationcontained herein.

2 While every precaution has been taken in the preparation ofthis book, Rational Software Corporation assumes no responsibility for errorsor omissions. This publication and features described herein are subject tochange without program and information contained herein are licensed only pursuant toa license agreement that contains use, reverse engineering, disclosure andother restrictions; accordingly, it is Unpublished rights reserved under thecopyright laws of the United States for purposes of the RIGHTS LEGENDUse, duplication, or disclosure by the Government is subject torestrictions set forth in DFARS (a) and (a) (1995),DFARS (c)(1)(ii) (Oct 1988), FAR (a) 1995, FAR ,or FAR , as , Purify, PureCoverage , Quantify, PureLink, ClearDDTS, andClearCase are U.

3 S. registered trademarks of Rational Software other products or services mentioned in this Guide are covered by thetrademarks, service marks, or product names as designated by the companieswho market those , PureCoverage , and Quantify are covered by one or more of PatentNos. 5,193,180 and 5,335,344 and 5,535,329. Purify is licensed under SunMicrosystems Inc. s Pat. No. 5,404,499. Other and foreign in the user S GUIDEC ontentsiWelcome to PureCoverageUsing this Guide .. viiPureCoverage features .. viiGetting started .. viiTaking advantage of special features .. viiiCommon questions and reference material .. viiiConventions used in this Guide .. viiiUsing online Help.

4 IxDisplaying the release notes .. ixInstalling PureCoverage .. ixContacting technical support .. x1 Introducing PureCoveragePureCoverage: simple & effective .. 1-2 Key PureCoverage features .. 1-32 Finding Untested Areas of Hello WorldInstrumenting a program .. 2-1 Running an instrumented program .. 2-4 Program output .. 2-4 Coverage data .. 2-5 Displaying coverage data .. 2-5 Expanding the detail level .. 2-6 Examining function level detail .. 2-7 Examining the annotated source .. 2-8 Improving Hello World s test coverage .. 2-9 Modifying makefiles for PureCoverage .. 2-11iiBeyond Hello World: how PureCoverage works .. 2-12 Files created by PureCoverage .

5 2-12 Compiling with the debugging option -g .. 2-13 How PureCoverage finds source files .. 2-14 Covering multiple processes .. 2-15 Signal handling .. 2-17 Covering multi-threaded applications .. 2-17 Saturating counters .. 2-183 When to Use PureCoverageUsing PureCoverage in nightly builds .. 3-1 Using PureCoverage with test harnesses .. 3-2 Separating data for individual test runs .. 3-3 Combining data from multiple program runs .. 3-4 Discarding data from failed tests .. 3-6 Exporting data .. 3-8 Running report scripts .. 3-9 Using PureCoverage with other Rational Software products .. 3-11 Using PureCoverage with Purify .. 3-11 Using PureCoverage and Purify with PureLink.

6 3-12 Using PureCoverage with ClearDDTS .. 3-124 Customizing CoverageExcluding libraries, directories, and files from coverage .. 4-1 Coverage for libraries .. 4-1 Customizing data collection .. 4-2 Adjusting coverage on a line-by-line basis .. 4-4 Adjustments .. 4-4 Types of adjustments .. 4-5 Marking adjustments manually .. 4-5 Marking adjustments interactively .. 4-10 Unnecessary adjustments .. 4-12 Saving files with adjustments .. 4-12iiiRemoving adjustments in the Annotated Source window .. 4-13 Adjustment file format .. 4-14 Strategies for using PureCoverage adjustments .. 4-15 Adjustment usage considerations .. 4-15 Models for using PureCoverage adjustments.

7 4-175 Using the PureCoverage Graphical DisplayPureCoverage Viewer .. 5-1 Selecting items .. 5-1 Using the toolbar .. 5-2 Selecting Viewer columns .. 5-3 Using the Viewer File menu .. 5-6 Using the Viewer View menu .. 5-7 Using the Viewer Adjustments menu .. 5-8 Using the Viewer Help menu .. 5-8 Annotated Source window .. 5-9 Using the Annotated Source File menu .. 5-10 Using the Annotated Source View menu .. 5-10 Using the Annotated Source Help menu .. 5-11 Navigating in the Annotated Source window .. 5-116 Report ScriptsPureCoverage report scripts .. 6-1 Coverage summary report .. 6-2 Low coverage report .. 6-3 Low coverage mail report .. 6-3 Spreadsheet report.

8 6-4 Differences report .. 6-5 Build differences summary report .. 6-6 Annotated source report .. 6-8 Annotated differences report .. 6-9 Selected tests report .. 6-11ivCustom reports .. 6-15A sample custom report script .. 6-157 PureCoverage OptionsOption tables .. 7-1 Using PureCoverage options .. 7-2 PureCoverage option syntax .. 7-2 Using conversion characters in filenames .. 7-3 PureCoverage option types .. 7-3 PureCoverage option processing .. 7-4 Specifying options in environment variables .. 7-4 Using the PUREOPTIONS environment variable .. 7-4 Setting options for Purify and PureCoverage .. 7-5 Specifying options on the link line .. 7-5 Using the ignore-run-time-environment option.

9 7-6 Using analysis-time mode options .. 7-7 Build-time options .. 7-7 Options for caching .. 7-7 Options for linker and collector .. 7-9 Run-time options .. 7-10 Options for file identification .. 7-10An option for saving data .. 7-12An option for data collection .. 7-12 Options for signal handling .. 7-13An option for exit processing .. 7-14 Analysis-time options .. 7-15An option for handling adjustments .. 7-15An option for merging .. 7-15 Analysis-time mode options .. 7-16 Informational options .. 7-19v8 PureCoverage APIC alling PureCoverage API functions from your program .. 8-1 Calling PureCoverage API functions from a debugger .. 8-2 Data collection API functions.

10 8-3 AppendixesA Common QuestionsCustomizing coverage .. A-1 General questions .. A-2 Performance issues .. A-4B Export FormatExport format description .. B-1 The effect of coverage adjustments on export .. B-93 Annotation VariationsComplex source lines ..C-1 Multi-line statements ..C-2 Function entry points ..C-3 Local variable declarations ..C-5 Switch statements ..C-5exit() statements ..C-7C++ inline functions ..C-7 PureCoverage Quick ReferenceIndexviPURECOVERAGE user S GUIDEviiWelcome to PureCoveragePureCoverage is a test-coverage monitoring program that is botheffective and easy to use. Once PureCoverage is installed, you canimmediately start using it on your applications by adding thewordpurecov to your link line.