TCAT C/C++, Ver. 3.2 -- README Notes

TCAT C/C++, Ver. 3.2
INSTALLATION README

Contents of the TCAT C/C++, Ver. 3.2 Installation README

The following information is available in this README file:

Prerequisites

Solution to potential problems

For the cl.exe problem

Technical Support

Technical Documentation

The fully working examples are provided in Examples subdirectory:

"...\Examples\Instrumented Example"

"...\Examples\Uninstrumented Examples"

(1) Prerequisites

Before starting, you will need to have installed Microsoft Visual Studio 6.0 or higher.

(2) License

DEMO versions of TCAT C/C++ for Windows contains a temporary access license file located in TCAT C/C++'s Program directory. EVAL versions will require a license key to operate properly.

DEMO versions are restricted to writing at most 5 modules into the MDF file. To request a FULL evaluation license key, please contact Software Research by sending email to <licenses@soft.com>.

NOTE: Please read details attached with each emailed license key.

(3) Environment Settings

The default installation directory for TCAT C/C++ is C:\Program Files\Software Research\Coverage\TCAT-CPP

The path needs to be appended to your path in autoexec.bat and/or the path environment variable.

If you are using NT, you can change the "environment variable" by opening the environment window from the System Properties window.
For Windows 2000/XP users, you can invoke System Properties window from the Start button by selecting Start-> Settings-> Control Panel-> System -> Advanced

TCAT C/C++ also needs the COMSPEC variable to be set in order to spawn the compiler on the instrumented code. Please set up your environment's startup files to an appropriate value:

For older Windows - the path of command.com, for example, COMSPEC=C:\COMMAND.COM
For Windows NT - cmd.exe, for example, COMSPEC=C:\WINNT\SYSTEM32\CMD.EXE
For Windows 2000/XP - cmd.exe, for example, COMSPEC=C:\Windows\SYSTEM32\CMD.EXE

TCAT C/C++ may create temporary files of the form _sbxxxx.tmp in your temp directory. These can be removed after the current instrumentation is done.

TCAT C/C++ supports Microsoft Visual C++ 6.0.

Please use the Scribble sample provided in the ...\Examples\Uninstrumented Examples\Scribble - VC 6.0 directory. The files in these directories are exactly the same as those provided in the Visual C++ CD-ROM. So if you need to restore their contents, you could copy the files from CD-ROM: ...\SAMPLES\VC98\MFC\TUTORIAL\SCRIBBLE\STEP7

(4) Runtime Library

The Runtime module of the instrumentor writes the coverage data into a trace file. The library "runtmdll.lib" must be linked with your instrumented application.

The number of coverage data to buffer before writing into the trace file defaults to infinite, that is all data is buffered before they are flushed into the trace file. This can be modified from the TCAT Options configuration tool that you will install in your Visual Studio Environment.

The Runtime module of the instrumentor (which writes the trace file) is provided in three categories. The choice of which one to link with your application depends upon the application's target and how it is compiled. The small table below illustrates the combinations possible.

Application Targets links with

Multi-threaded library Runtmdll.lib

Multi-threaded DLL Runtmdll.dll

(5) Getting Started

An already instrumented example to demonstrate the viewing parts ahead can help you in getting a quicker headstart. This bypasses the compiler instrumentation section. The example is created using the scribble example from Visual C++ 6.0, and the directory is located at

$SR Examples\Instrumented Example\Scribble - VC 6.0

where $SR is your TCAT C/C++ installation directory, for example,

C:\Program Files\Software Research\Coverage\TCAT-CPP

All Scribble files are instrumented by using WinIC9. Calltree and Digraph are used to view the control structure associated with the source code. The trace file ("trace.trc") is created after running the instrumented code and the coverage report can be viewed by using Cover.

A step by step instruction is given below.

Preparing and Instrumenting Scribble

There are two methods to instrument Scribble by either using options from the TCAT/C-C++ Integrated with Microsoft Visual C++ 6.0 window. Or applying your own workspace within WinIC9 along with IC9 command lines.

Using the TCAT C/C++ Integrated with Microsoft Visual C++ 6.0

1) Integrating TCAT C/C++ into Microsoft Visual C++...

From Tools pull-down menu select Customize.
On the Add-ins and Macro Files tab menu, click on the Browse button and select the SRCov.dll file from your TCAT C/C++ installation directory C:\Program Files\Software Research\Coverage\TCAT-CPP\Program
If you cannot find the file, make sure the "Files of type:" drop-down list reads "Add-ins (.dll)".
This will integrate TCAT C/C++ into Microsoft Visual C++ 6.0.

2) Opening the Scribble Example...

Select File | Open Workspace
Select the Scribble.dsw file from the ...\Examples\Uninstrumented Examples\Scribble - VC 6.0 directory.

3) Creating a Coverage Project Configuration for Scribble...

From the Build pull-down menu, select Configurations.
Click the Add button.
Type in Coverage as a new Project Configuration name. Click on OK and then on Close to accept the changes.
Select Project | Settings.
Select Win32 Coverage in the drop down box labeled Settings For:. Make sure the Scribble Project Name is selected.
The Intermediate files: and the Output files: in the General tab must contain the string Coverage.
At the C/C++ tab menu, select Category: Precompiled Headers from the drop down menu.
Select the Not using precompiled headers option.
Do the same for the stdafx.cpp file. Click on OK to accept the changes.

4) Configuring TCAT C/C++...

Click on the Configure TCAT Options button on the TCAT C/C++ Toolbar.
At the Instrumentor Options tab menu, check C1 and S1.
At the Runtime Selection tab menu. enter the path to Runtmdll.lib file located in the TCAT C/C++ Program directory, if default choice differs.
The Buffering slider indicates the number of hits to buffer before they are flushed into the trace file. A smaller buffer degrades performance.
Click on Apply and OK to accept the changes, if any. Don't forget to save your Workspace before closing Microsoft Visual Studio.

5) Instrumenting the Scribble Example...

Click on the Build The Instrumented App button.
The instrumented object files will be placed in the debug (or release directory if you choose) directory.

6) Executing the Instrumented Scribble

Click on the Run The Instrumented App button.
Test-drive the instrumented Scribble app to create a TCAT C/C++ trace file, trace. trc.

Viewing Coverage Reports

Click on the Run Coverage Report button to run the WinCover.
From the menu, select File > Open.
In the Open dialogue, click on the filename trace.trc from the Scribble's \Coverage\tcat_db\Scribble\ directory, created during instrumentation.
The dialog box then asks for an archive file; ignore this request by clicking the Cancel button, if no archives exist.
WinCover will display a coverage report generated while running the instrumented Scribble app.

Viewing the Source Code Associated With Coverage Reports

Click on the Segment number, or the Call pair number of the function.
The code is displayed in a separate window with the calling statement highlighted in red.

Viewing Directed Graphs

Click on the Run Digraph button.
Select File | Open.
You are prompted for the name of the directed graph file to view. Find the Scribble.dg file under the d_graph directory, e.g.
...\Examples\Instrumented Example\Scribble - VC 6.0\Coverage\tcat_db\Scribble\d_graph\
A window listing the available functions is displayed. Select one of the functions to view.
WinDigraph displays a directed graph depicting possible program flows of the function.
By clicking near the number associated with an edge and clicking on the View Source button...
... you can call up and view the associated source code.

Viewing a Calltree

Click on the Run Callgraph button.
Select Open | File.
Select SCRIBBLE.cg under the c_graph directory, e.g.
...\Examples\Instrumented Example\Scribble - VC 6.0\Coverage\tcat_db\Scribble\c_graph\
A Select a Function ID window is displayed. Select a function to view from the list.
WinCalltree displays a calltree depicting the selected function.

Viewing the Directed Graph Associated With a Calltree Node

Select the Root node of the calltree.
Click on the View Digraph button on the toolbar.
A directed graph of the function appears.

Viewing the Source Code Associated With A Calltree

Click on the edge running from the root node to the left-most node.
Click on the Source Code button on the toolbar (It gives you a red arrow if there is a source file.).
The code is displayed in a separate window with the calling statement highlighted in red.

(6) Solutions to potential problems.

Installing a Visual Studio Service Pack when TCAT C/C++ is already installed will create compilation errors like

Command line warning D4002 : ignoring unknown option '-TCAT-B'

Go to your "Microsoft Visual Studio/VC98/Bin" directory, delete
"mscl.exe", and re-install TCAT C/C++.
Trace file reports no coverage data on DEMO licenses.
The DEMO license limits instrumentation to a small number of modules. Unless your sample test run covers that section of code, you will not receive any coverage data.
Unable to Locate DLL" error when running an instrumented app.
Ensure the path to your TCAT/C-C++ Program directory is in your
Environment path.

For the cl.exe problem

There may have been a problem getting a build to go through successfully, claiming it can't find "cl.exe".
Solution: TCAT C/C++ Ver. 3.2 and later assume that you are installing on a system which has connections only for Visual C/C++ 6.0 (or later) Developer's Studio environment. If you have any older versions of the compiler(i.e. "cl.exe") you must make certain that your Studio and project settings contain references to and select the path to TestWorks' modified version of "cl.exe".(This file is copied into the directory C:\Program Files\Microsoft Visual Studio\Vc98\Bin during installation.)
The error message Error executing "cl.exe" will reflect an incorrect path setting for your Studio's executables table.
To setup the correct path for Visual C/C++ 6.0, please add the path
C:\Program Files\Software Research\Coverage\TCAT-CPP\Program to Tools | Options | Directories | Executable Files.

(7) Technical Support

If you are having any problems either setting up or working with this version of TCAT C/C++, Ver. 3.2, please report them to Software Research and every effort will be made to get them resolved and included in the next release.

(8) Technical Documentation

A quick start document in PDF or postscript format is also available in the Help directory.

To view the PDF file, you need the Acrobat Reader which can be downloaded from:

http://www.adobe.com/prodindex/acrobat/readstep.html

If you do not have a postscript printer, you may get a postscript viewer called GhostScript (and GhostView) which may print to your printer, but at the very least would display the file on the screen. To obtain this, connect to:

http://www.cs.wisc.edu/~ghost/index.html

The complete manual is provided with the CD-ROM version in PDF format. You can view and print the document without a postscript printer.

Feedback

We would also appreciate feedback on how we can improve the usability, the project and workflow.
We welcome any other comments or insights from you.
Please contact Software Research by:

Incident Form
Phone: +1 (415) 861-2800 or +1 (800) 942-SOFT
FAX: +1 (415) 861-9801

Updated: December, 2006

Application Targets	links with
Multi-threaded library	Runtmdll.lib
Multi-threaded DLL	Runtmdll.dll