Menu

Squish Coco

Code Coverage Measurement for Tcl, QML, C# and C/C++

Part VIII
Other Coco Tools

Chapter 22  cmedit – Edit the paths in a csmes file

cmedit is a tool to modify the paths of the files in a .csmes file.

Syntax:

cmedit [⟨options⟩] ⟨infile⟩ [-o ⟨outfile⟩]

where:

infile
The .csmes file to be edited. Unless the option -o is set, the changes in the path names are written to this file too. (Required parameter)
-o outfile | --output=outfile
The .csmes output file. If this parameter is set, the original ⟨infile⟩ is unchanged and the edited version of ⟨infile⟩ is written too ⟨outfile⟩.
options
Any of:
-c depth | --cut=depth
Remove a common initial segment of all paths in ⟨infile⟩.

depth⟩ is a non-negative integer and describes the number of path components that should be removed. A path component is every sequence of characters that lies between slashes or backslashes. The drive letter (plus colon) at the beginning of a Windows path name is also counted as a path component. Therefore the command --cut=1 will transform the path “/home/someone/main.cpp” into “/someone/main.cpp”, and “C:\mydir\main.cpp” into “\mydir\main.cpp”.

If ⟨depth⟩ is too large, cmedit exits with an error and does nothing. This occurs either if there is a path with less than ⟨depth⟩ components or if there are two paths that differ in the first ⟨depth⟩ components. If ⟨infile⟩ contains the two paths “/home/someone/myproject/main.cpp” and “/home/someone/library/header.h”, the command --cut=3 will not succeed.

The --cut command is always executed before all --rename commands.

-C | --cut-all
Remove the largest common initial segment of the paths in ⟨infile⟩. The option is equivalent to calling -c depth⟩ with the highest possible value of ⟨depth⟩.

The --cut-all command is always executed before all --rename commands. You may either use --cut or --cut-all, not both.

-r command | --rename=command
Rename all paths that match a given pattern.

The parameter ⟨command⟩ has the form “⟨pattern⟩,⟨replacement⟩” or “⟨pattern⟩,⟨replacement⟩,⟨flags⟩”, where:

  • pattern⟩ is the pattern to replace. cmedit searches for it in every path in ⟨infile⟩ and tries to replace it with the ⟨replacement⟩ string. If ⟨pattern⟩ occurs more than once in a path, all occurrences are replaced.

    By default, ⟨pattern⟩ uses the wildcard syntax, with “?” standing for a single character and “*” standing for any number of characters. By setting the “r” flag (see below), one can use regular expression syntax instead. (Note that with regular expressions, the backslashes in Microsoft® Windows path names must be doubled to distinguish them from the backslashes of the regular expression syntax.)

  • replacement⟩ is the replacement string.
  • flags⟩ can be the letters “i” or “r” or both. The flag “i” enables case-insensitive comparison, while “r” enables regular expression matching.

If ⟨pattern⟩ or ⟨replacement⟩ should contain a comma, it can be written as “\,”.

The option can be repeated to set more than one ⟨command⟩. The commands are then executed in sequence in the order in which they are written. But before they are executed, cmedit checks whether the resulting transformation is possible at all. If there are two paths that would be transformed into the same new path, cmedit exits with an error and does nothing.

-l | --list-sources
List the paths of all sources in ⟨infile⟩. The paths are left unchanged.
-f | --force
Rename source files even if errors are reported.
-n | --dry-run
Do not change the paths, only describe what would be done.
-v | --verbose
Make the output more verbose.
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.
Exit values

cmedit exits with status 0 if it succeeds. It returns -1 is the Squish Coco license is invalid, and 1 if the requested renamings cannot be done.

Chapter 23  cmmerge – Merging Utility

cmmerge is a small utility which permits to merge several instrumentation databases (.csmes file) together. It behaves like the CoverageBrowser menu entry "File->Merge with…" (see Chapter 19.8.1).

Syntax:

cmmerge [⟨options⟩] -o ⟨outfile⟩ ⟨infile⟩...
cmmerge --blackbox  -o ⟨outfile⟩ ⟨infile

where:

-o outfile | --output=outfile
.csmes output file. (Required.)
infile
.csmes input file. Only one input file is allowed if --blackbox is selected.
-b | --blackbox
Generate a .csmes file for black-box testing.
options
Any of:
-a | --append
Merge the input file(s) with the existing content of the output file. ⟨outfile⟩ must already exist.
-i reference | --instrumentation-and-execution=reference

Include only execution results that belong to the .csmes file ⟨reference⟩.

With this option, cmmerge merges ⟨reference⟩ with the ⟨infile⟩s, but includes the instrumentations and executions of an ⟨infile⟩ only if they also occur in ⟨reference⟩. If --append is set, ⟨outfile⟩ is viewed as a part of ⟨reference⟩.

This option is useful for unit tests, where the ⟨reference⟩ is the program for which the test is written, while the ⟨infile⟩s contain the execution results of the unit tests.

-r reference | --reviews-only=reference

Merge ⟨reference⟩ with the comments and manual validations in the ⟨infile⟩s.

The file ⟨reference⟩ is a .csmes file. Only validations and comments of unmodified functions are imported. If there are comments for the same line of code, they are merged. The original comments are then separated by a horizontal bar. If however the same comment occurs more than once in the input files, only one copy is kept.

-s | --strict

Require that the preprocessed output for each C++ file is identical across the build.

--delete
Delete the input files from disk after importing them.
-v | --verbose
Verbose output.
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.

Chapter 24  cmcsexeimport – Command Line Import Utility

cmcsexeimport is a utility to import an execution report (.csexe file) into an instrumentation data base (.csmes file). It behaves like the menu entry "File->Load Execution Report…" in the CoverageBrowser (see Chapter 18.1.2).

Syntax:

cmcsexeimport -m ⟨csmes_file⟩ -t ⟨title⟩ [⟨options⟩] ⟨csexe_file⟩...

where

-m filename | --csmes=filename
Set the name of the .csmes file into which the .csexe files are imported. This parameter is mandatory.
-t string | --title=string
Set a default name for the executions in the ⟨csexe_file⟩s. This parameter is mandatory.

Executions that already have a name will be imported unchanged. Others get the name ⟨string⟩, with a number attached in braces if there is more than one of them.

csexe_file
Name of one of the .csexe files that should be imported.
options
Any of:
-e filename | --csexe=filename
Set the name of a .csexe file to be imported. This argument can be repeated to process more than one file.
-l filename | --csexe-list=filename
Read the list of .csexe files to import from a text file. The text file must have one file name per line, without leading or trailing spaces.
-p policy | --policy=policy
Set the import policy. The possible import policies are:
ignore_duplicates
Executions are ignored if they have executed the same code as an execution that was already imported. (Default.)
import_duplicates
Executions are imported if at least one instrumented source code line is executed.
import_duplicates_and_empty
All Exections are imported.
merge
All executions with the same name are merged. The execution counts of all merged instrumentations are added.
-I | --incident
Mark the executions in the imported files as “INCIDENT”.
-S | --skipped
Mark the executions in the imported files as “SKIPPED”.
-P | --passed
Mark the executions in the imported files as “PASSED”.
-F | --failed
Mark the executions in the imported files as “FAILED”.
-C | --check-manually
Mark the executions in the imported files as “CHECK_MANUALLY”.
-f num | --csmes-save-frequency=num
After every ⟨num⟩ exection reports have been read, the current state of the instrumentation database is written to disk. Without this option, the it is written to the disk only at the end.
-d | --delete
Delete the imported files after processing them.
-v | --verbose
Write progress messages to the standard error output (stderr).
-D | --debug
Write debugging information to the standard error output (stderr).
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.

Chapter 25  cmreport – Code coverage report generation

cmreport is a utility which permits to generate Text, HTML, XML or CSV reports from an instrumentation data base (a .csmes file). It generates exactly the same reports as these generated by CoverageBrowser (see Chapter 20).

Example: The simplest use case is the generation of an HTML report from a single instrumentation database. If the name of the file is project.csmes, we may write:

cmreport --csmes=project.csmes --html=report

This command creates a file report.html and a directory report_html. The file report.html is the main page of the report and can be opened with the browser, while report_html contains all the other files. Most of the other command line options just modify the content of such a report.

Syntax:

cmreport -m ⟨csmes_file⟩ ...

Where:

-m file_name | --csmes=file_name
Set the name of the main .csmes file (mandatory).
-p file_name | --patch=file_name
Enable patch/diff file analysis. ⟨file_name⟩ is the name of a file im "unified diff" format (see Chapter 36). The file must contain the differences between the files in the directory tree covered by the .csmes file and a modified version of the same directory tree. Patch reports can be generated in the CSV and in the HTML format.

With the option --section (see Chapter 25.4) one can select which sections of the report are displayed.

--source-type=argument
Source type used for the analysis. Possible values:
preprocessed
The preprocessed code is analyzed.
original
The original source code is analyzed. C macros are ignored in this mode.
-l number | --level=number
Set the code coverage level. ⟨number⟩ must be an integer greater than 0.
--max-threads=number
Maximal number of threads used for the report computation. By default, there as many threads as there are CPUs on the system.
--stat
Print global coverage statistics to the standard output
--max-lines-per-page=number
Maximal number of lines per page for HTML tables.
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.

25.1  File selection options

The following options allow to specify the source files shown in the report.

--include-file-abs-regex=regex
Include the source files that match the regular expression ⟨regex⟩ in the report.
--exclude-file-abs-regex=regex
Exclude the source files that match the regular expression ⟨regex⟩ from the report.
--include-file-abs-wildcard=wildcard
Include the source files that match the wildcard pattern ⟨wildcard⟩ in the report.
--exclude-file-abs-wildcard=wildcard
Exclude the source files that match the wildcard pattern ⟨wildcard⟩ from the report.

If two or more of these options match a file, the last one decides whether it is included or excluded. For the syntax of regular expressions and wildcard patterns see Chapter 19.1.

25.2  Execution selection options

The following options allow to specify the executions that occur in the report.

-s regex | --select=regex
Select executions using regular expression. If not used, all executions are implicitly selected.
-d regex | --deselect=regex
Deselect executions using regular expression
--deselect-to-check
Deselect all executions with the status “CHECK_MANUALLY”
--select-passed
Select all executions with the status “PASSED”
--deselect-passed
Deselect all executions with the status “PASSED”
--select-failed
Select all executions with the status “FAILED”
--deselect-failed
Deselect all executions with the status “FAILED”
--select-unknown
Select all executions with unknown status
--deselect-unknown
Deselect all executions with unknown status
--executions-reference-from-csmes=argument
Select all executions present in the specified .csmes file.

25.3  Release comparison

With the following options, one can compare the coverage of two releases.

-mr file_name | --csmes-reference=file_name
Set the name of the .csmes reference file. With this option, cmreport compares two software releases.
--release-comparison=argument
Comparison mode when comparing two software releases. Possible values:
none
Display only the differences between two software releases.
modified_functions
Display code coverage only for modified functions.
unmodified_functions
Display code coverage only for identical functions.
-sr regex | --select-reference=regex
Select reference executions using regular expression. This option activates the comparison of executions.
-dd regex | --deselect-reference=regex
Deselect reference executions using regular expression. This option activates the comparison of executions.
--deselect-to-check-reference
Deselect all reference executions with the status “CHECK_MANUALLY”
--select-passed-reference
Select all reference executions with the status “PASSED”
--deselect-passed-reference
Deselect all reference executions with the status “PASSED”
--select-failed-reference
Select all reference executions with the status “FAILED”
--deselect-failed-reference
Deselect all reference executions with the status “FAILED”
--select-unknown-reference
Select all reference executions with unknown status
--deselect-unknown-reference
Deselect all reference executions with unknown status

25.4  Options for HTML or CSV reports

Command line arguments:

-h file_name | --html=file_name
Browsable HTML report output file name
--html-single=file_name
HTML report output file name (single file)
--csv-excel=file_name
CSV report (optimized for Excel and OpenOffice) output file name
--execution-level=argument
Code coverage level for executions
--css=file_name
CSS style sheet
--icon=file_name
Icon
--title=file_name
Title
--section=section_name
Select the sections of the generated report. This option can be repeated to select more than one section type. If nothing is selected, cmreport generates all relevant sections automatically.

The following sections are possible:

global
Global statistics
function
Function statistics
function-tree
Function tree with statistics
class
Class/namespace statistics
execution
Execution statistics
source
Source file statistics
source-tree
Source tree with statistics
directory
Directory file statistics
manually-validated
Manually validated code fragments
unexecuted
Unexecuted code fragments
dead-code
Dead code fragments
executed
Executed code fragments

If the option --patch is used, the following sections are also possible.

patch-execution-statistic
Global execution statistics of a patch
patch-source-statistic
Global source code statistics of a patch
patch-execution
Executions impacted by a patch
patch-source
Annotated patch file

For the content of these sections, see Chapter 19.6. By default, if no --section option is set, all them occur in the report.

--global-threshold-low-medium=num
Global threshold setting
--global-threshold-medium-high=num
Global threshold setting
--source-threshold-low-medium=num
Source/directory threshold setting
--source-threshold-medium-high=num
Source/directory threshold setting
--function-threshold-low-medium=num
Function/class/namespace threshold setting
--function-threshold-medium-high=num
Function/class/namespace threshold setting
-b | --coverage-statement-block
Code coverage of statement blocks only
--coverage-condition
Code coverage at decision/condition level
--coverage-mcc
Code coverage at multiple conditions level
--coverage-mcdc
Code coverage at MC/DC level
--line-coverage
Line coverage analysis
--function-coverage
Function coverage analysis
-t | --test-coverage
Test count mode
-D | --debug
Debug flag
--csv-field-separator=char
Field separator for a CSV file
--csv-comma=char
Separator (, or .) used for floats in a CSV file
--no-line-metrics
Disable the eLOC metrics.
--no-mccabe-metrics
Disable the McCabe (cyclomatic complexity) metrics.

25.4.1  Obsolete options for CSV reports

Command line arguments:

--csv-method=argument
Generate a CSV report file for each method
--csv-source=argument
Generate a CSV report file for each file
--csv-field-separator=argument
Field separator for a CSV file
--csv-comma=argument
Separator (, or .) used for floats in a CSV file

25.5  Options for text reports

Command line arguments:

-t file_name | --text=file_name
Text report output file name
--format-executed=argument
Line format for the executed for code fragments
--format-unexecuted=argument
Line format for the unexecuted for code fragments
--format-manually=argument
Line format for the manually validated for code fragments
--format-dead-code=argument
Line format for dead code fragments

The following escape sequences are recognized:

%f
Absolute source code file name
%r
Relative to the current build directory source code file name
%l
Line number
%c
Column number
%m
Explanation

It is allowed to to set the output file to an empty string (i.e.: --text=), in this case the standard output of the console is used.

25.6  Options for EMMA-XML reports

The following options are used if a report in the EMMA-XML format is generated:

--emma=filename
Generate an EMMA-XML report. ⟨filename⟩ is the name of the XML file that is generated.
--emma-source-pattern=argument
Source file pattern for EMMA-XML reports
--emma-package-pattern=argument
Package name pattern for EMMA-XML reports

The patterns have the following format:

%f
file name (without path)
%b
file name without path and extension
%e
file extension
%p
file path (without file name)
%P
absolute file path (without file name)
For Jenkins-CI users, it is not recommended to use the last two parameters. The default values are chosen to work with the EMMA-XML plugin.

25.7  Options for JUnit reports

Command line arguments:

-j file_name | --junit=file_name
Generate an JUnit report

JUnit reports does not contain any code coverage information. The report list only the tests executed, their status (passed or failed) and their comments.

25.8  Options for Cobertura reports

Command line arguments:

--cobertura=argument
Generate a Cobertura-XML report
--cobertura-source=argument
Root path of the source code when generating a Cobertura-XML report
--sonarqube-project=argument
Generate a Cobertura-XML report for a SonarQube project

To generate a Cobertura reports two work flows are supported:

  1. Specifying directly all necessary arguments to generate the report which are:
    1. the output file name (--cobertura=argument⟩ command line option)
    2. the root path of the source directory tree (--cobertura-source=argument⟩ command line option)
  2. Indicating the path of a SonarQube project properties file sonar-project.properties (--sonarqube-project=argument⟩ command line option): in this case, the root path of the source tree is extracted from its contents using sonar.cxx.coverage.reportPath, sonar.cxx.coverage.itReportPath or sonar.cxx.coverage.overallReportPath property.

Chapter 26  cocolic – License activation

Command line alternative to cocolicwizard. The program can be used to activate and configure the Squish Coco license on a computer without a graphical interface.

Syntax:

cocolic ⟨arguments

Where:

--fetch-license-key=code
Use an activation code to retrieve the license key for a node-locked license. The activation code is provided by froglogic.

For this, cocolic needs a network connection to froglogic. It can also be configured to connect via a proxy server (see below).

--license-key=key
Set the key for a node-locked license. The license key is generated by froglogic from the output of cocolic --machine-identifier.
--machine-identifier
Display the machine identifier on the standard output.
--license-server=server:port
Set the address and the port of the license sever for a floating license. The port can be omitted; then the default port of 49344 is used.
--check
Check the license validity. The program prints a message about the status of the license to stderr. It then exits with a return value of 0 if the license is valid, or 1 if it is invalid.
--http-proxy=server:port
Use a HTTP proxy sever to retrieve the license key.
--socks5-proxy=server:port
Use a SOCKS5 proxy sever to retrieve the license key.
--proxy-user=name
Set the user name for the proxy server.
--proxy-password=password
Set the password for the proxy server.
--no-proxy
Disable the use of a proxy server.
--disable-node-locked
Disable the node locked license. This option is meaningful if a node-locked license and a license server use are present on the same machine. Squish Coco will then use the license server, but the node-locked license is still present and can be enabled later.
--enable-node-locked
Re-enable a previously disabled node locked license. Do nothing if the license is already enabled.
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.

Chapter 27  cocolicwizard – GUI for license activation

cocolicwizard provides a graphical user interface to configure the license. It allows to enter a license activation code, send an activation email, to enter a license key or to configure the connection to a license server. The program also displays information about the currently active license.

Syntax:

cocolicwizard [--check]

Where:

--check
check whether there is a valid license. Show the GUI window only if there is no valid license, otherwise do nothing.

Chapter 28  cocolicserver – License Server

cocolicserver can be used to serve Squish Coco licenses from a central computer; clients can connect to the server and cocolicserver will make sure that no more than the available number of licenses will be used concurrently.

Syntax:

cocolicserver ⟨options

where:

-s | --server-identifier
Print the identifier of the machine on which cocolicserver should run. This identifier must then be sent to froglogic to get a license file (see Chapter 2.2.1).
-c path | --config=path
Path to the configuration file (provided by froglogic).
-l path | --logfile=path
Write log messages to the file at ⟨path⟩. The file name may contain the following escape sequences:
%Y
current year, in four digits,
%M
current month number, in two digits,
%D
current day, in two digits,
%h
current hour, in two digits,
%m
current minute, in two digits,
%s
current second, in two digits.
New log files will be opened according to the values of the escape sequences. This means that if ⟨path⟩ is e.g. cocoserver_%Y_%M_%D.log, every day a new log file is created, and the files have names like cocoserver_2016_01_01.log, cocoserver_2016_01_02.log, etc.
@path
Read command line options from the file at ⟨path⟩ and insert them at the position of this option. The option file is a text file with one option per line. Leading and trailing blanks and empty lines are ignored.

The following options are available only on Linuxand macOS:

--syslog
Write log messages to the UNIX® system logging service.
--daemon
On Linuxand macOS: Launch cocolicserver as a daemon background process.

The following options are available only on Microsoft® Windows:

--service-install
Install cocolicserver as a Windows service that starts automatically at boot time.

For this option cocolicserver needs administrator privileges. It must be run in the form

C:\somedir> cocolicserver --service-install ⟨options

Then the service is installed and starts automatically. It will run as if called directly in the form cocolicserver options⟩. The visible name of the server is “Squish Coco License Server”.

If the server is already installed as a service, the ⟨options⟩ are updated. The new options have effect only after the service is restarted.

--service-uninstall
Uninstalls the cocolicserver Windows service. For this option cocolicserver needs administrator privileges.
email squish@froglogic.com