This is on-line help file on CTC++ IDE integration to Microsoft Visual Studio IDE versions 2003-2012. This CTC++ IDE integration is used also in some other graphical development environments. Usage in them follows the same principles as described here on Microsoft Visual Studio IDE case.
The overall idea of the use is the following:
Into the Visual Studio "Tools" menu two commands have been added: "CTC++ Set/Clean..." and "CTC++ Report...".
Before you build your program you use the "CTC++ Set/Clean..." command and set CTC++ mode ON. Also you set the instrumentation mode and other instrumentation parameters in the way as you want them to be applied when the instrumented application will be built.
Next you (re)build you program normally by Visual Studio "Build" menu commands. When CTC++ mode is ON the compilation and link commands that Visual Studio invokes behave like "ctc-compile" and "ctc-link". As result you get instrumented program (.exe, .dll, .lib). The instrumentation phase creates also a symbolfile (by default MON.sym at the project build directory), which contains descriptions of the instrumented files, and which are needed by CTC++ in later phases.
Next you do some test runs with the instrumented program. The instrumentation probes collect execution history into main memory and at the end of the program execution a datafile is written (by default MON.dat at the same directory as the MON.sym resides). The datafile contains the coverage data in binary form.
Next you use "CTC++ Report..." command for getting the various coverage reports. Effectively the "CTC++ Report..." command dialog box is just a graphical interface on running the ctcpost and ctc2html tools and starting the reports (in notepad or your default HTML browser). The ctcpost utility is always invoked and it reads the symbolfiles (MON.sym files from the project directories) and datafiles (MON.dat files) and generates a textual report. If you have asked for a HTML report, the ctc2html tool is additionally invoked to generate it.
Some links:
The dialog looks as follows:
When you start this dialog the most recently used values are remembered in the fields. Select CTC++ mode ON and set the other instrumentation options, when you want to set CTC++ mode ON.
The instrumentation options map to the ctc.exe option -i. You need to select one of the mentioned code coverage options. In CTC++ there are also coverage measures, which you can not select here: "statement coverage" (it comes automatically when the instrumentation is at least "decision coverage"), and "condition coverage" and "MC/DC coverage" (these are coverage views and you get them with appropriate option in "CTC++ Report..." dialog, provided that the instrumentation is "multicondition coverage"). Additionally you can select timing instrumentation.
In field "Additional/advanced options (ctc)" you can give more options to ctc.exe. See the general CTC++ documentation what options ctc has. However, mentioning the following, which may come into use most often:
-v
(verbose).
In the beginning at least recommended that you use this option for
understanding how the instrumentation happens. Under this option ctc
writes certain progress messages of its internal processing phases to
Visual Studio output window. When contacting support, please use this
option and provide a copy of the output window. In stabilized use
phase you may not want to use this option, because there can come
quite a lot text to the output window.
-V
(VERBOSE).
Under this option ctc writes it version number, and the names of the
configuration files that it loaded, to the output window. Use this
option for checking those things. In longer run use of this option
may be "overkill".
-n symbolfilename[.sym]
When
this option is not given, ctc uses symbolfile MON.sym in the project
directory where the build takes place. With this option you can
specify that some other symbolfile will be used. Note that if you
specify the symbolfile differently as the default, in "CTC++
Report..." dialog you have to specify it as well.
-C
EXCLUDE+filespecifications
-C
NO_EXCLUDE+filespecifications
With
these setting you can fine-tune what files will be instrumented/not
instrumented. Default settings come from configuration file, which is
that all files that are compiled will be instrumented but no code
that is #included to those files (code from header files) is not
instrumented. See the general CTC++ documentation how these settings
are used.
The additional/advanced options can be written on one line or on multiple lines.
This "CTC++ Set/Clean..." dialog can be started even if there is not any project selected in the Visual Studio IDE. Once the CTC++ mode has been set ON, the selected options will be applied on any coming builds, until the the CTC++ mode is set OFF.
The dialog looks as follows:
You can start this dialog when you have some project selected as active project at Visual Studio side. It will specify the directory where CTC++ IDE looks some files and where the resultant report files are written. At field "Directory:" you see the name of that project directory.
At field "Symbolfile" you see the name of the symbolfile, if it resides in the directory with its default name MON.sym. If the project has not been instrumented, or if the project is instrumented and -n option has been given so that the symbolfile has not its default name and directory, the field has contents "N/A (not instrumented or other directory/name)". In such case you have to give the symbolfile name(s) explicitly in the "Additional/advanced options(ctcpost)" field.
At field "Datafile" you see the name of the datafile, if it resides in the directory with its default name MON.dat. If the project has not been instrumented, or if test runs have not been done, or if the project is instrumented and -n option has been used so that the symbolfile has not its default name and directory (it determines also the datafile name), the field has contents "N/A (no test runs or other directory/name)". In such case you have give the datafile name(s) explicitly in the "Additional/advanced options(ctcpost)" field.
The "Report type" field is a pull-down menu having selections:
HTML report
First
a normal textual Execution Profile Listing is generated by ctcpost.
Then it is converted to HTML form by ctc2html utility. Finally the
HTML report is started to your default browser (if "Invoke
viewer" is checked).
Untested report to Visual Studio
First a normal textual Untested Code Listing is generated by ctcpost. Then it is parsed and written to Visual Studio output window with lines prefixed with sourcefilename (linenumber). You then can click on the lines and get to the actual source code at that line in the Visual Studio source code window.
Profile listing (textual)
Normal
textual Execution Profile Listing is generated by ctcpost. Then it is
started to the specified viewer program, which is specified in the
"Viewer" area (if "Invoke viewer is checked).
Untested listing (textual)
Normal
textual Untested Code Listing is generated by ctcpost. Then it is
started to the specified viewer program, which is specified in the
"Viewer" area (if "Invoke viewer is checked).
Timing listing (textual)
Normal
textual Execution Time Listing is generated by ctcpost. Then it is
started to the specified viewer program, which is specified in the
"Viewer" area (if "Invoke viewer is checked).
XML report
Normal
textual XML Report is generated by ctcpost. Then it is started to the
specified viewer program, which is specified in the "Viewer"
area (if "Invoke viewer is checked).
In the "Coverage view" area you can fine-tune how the coverage reports are generated. The selections are:
As instrumented
No
ctcpost option added. The coverage will be show in the way as the
code has been instrumented, i.e. in multicondition, decision,
function coverage view as the each file has been instrumented.
Reduced to MC/DC coverage
-fmcdc
ctcpost option used. If the code has been instrumented for
multicondition coverage and if there are condition expressions having
&& or || operators, the report is generated from those
portions in a reduced MC/DC coverage view.
Reduced to condition coverage
-fc
ctcpost option used. If the code has been instrumented for
multicondition coverage and if there are condition expressions having
&& or || operators, the report is generated from those
portions in a reduced condition coverage view.
Reduced to decision coverage
-fd
ctcpost option used. If the code has been instrumented for
multicondition coverage and if there are condition expressions having
&& or || operators, the report is generated from those
portions in a reduced decision coverage view.
Reduced to function coverage
-ff
ctcpost option used. If the code has been instrumented for decision
coverage or multicondition coverage, the report is generated in a
reduced function coverage view.
Read from the general CTC++ documentation what the coverage views mean.
In field "Additional/advanced options (ctcpost)" you can give such ctcpost options and arguments for which there is not a special control in the dialog. See the general CTC++ documentation what the ctcpost options are. However mentioning here the following:
Additional or specially named symbolfiles and datafiles:
If
at instrumentation time you have used -n option to specify the
symbolfile name (it determines also the datafile name and location),
and this dialog does not find them with their default names MON.sym
and MON.dat in the project directory, you have to give them
explicitly here.
Another typical case is
when you want the report to contain coverage data of many projects of
a solution. You need to give neighbor projects' symbolfile and
datafile here for getting a combined report.
-f filespecification
-nf
filespecification
These
options mean "select files" (-f) and "not select
files" (-nf). By default the report contains all the
instrumented files that the symbolfile(s) specify. If for some
instrumented file there is no coverage data at all in the datafiles,
or the coverage data is rejected due to timestamp check, the report
contains zero counters on those files, which of course affect the
overall TER%.
With these options you
can select from the symbolfile(s) those code files which you only
want to be included into the report. If no -f options are given, all
files are the starting point. If -f options are given, only those
files that match to the file specifications are selected. Then -nf
options are looked. The -nf options can further exclude files from
the report.
You can use many -f and
-nf options, if that is needed.
The field "Additional/advanced options (ctc2html)" can be filled when HTML report is selected. One of the ctc2html options, option -t, the threshold percent, is modeled in the dialog. It determines what is the "required" TER% at various summary levels in the HTML report. If the TER% is under the requirement, the corresponding histogram is in red (it is in blue when the TER% is met).
See the general CTC++ documentation about the other ctc2html options and use them as needed.
In field "Viewer" you can check if a viewer will be started on the generated report. On HTML report it is always your default HTML browser. On the textual reports you can select the viewer utility. It is notepad by default.
In this dialog there is counterpart on using the rarely needed ctcpost options -a (adding symbolfiles and datafiles) and -l and -L (getting listings of symbolfile and datafile contents). If you need those things, you need to do them from command line.
The dialog looks as follows:
This dialog is invoked by "Clean..." button from "CTC++ Set/Clean..." dialog. With this dialog you can delete the CTC++ generated files and directory (CTCHTML) from the project directory. Check the files that you want to be deleted.
You need to have some project selected in the Visual Studio side, because CTC++ IDE needs to know the project directory to operate at.
If you have multiple projects in your solution, you need to visit each project and delete the files there.
The CTC++ User's Guide resides in %CTCHOME%\Doc\ctcug.pdf.
That folder contain also other text files, which you may find useful.
When you invoke the tool components in command line with option -h (ctc -h, ctcpost -h, ctc2html -h), you get a short description of the command line options.