polyspace-code-profiler-server

R2026b

(System Command) Profile your source code for calculating C/C++ code coverage, code execution time, and memory use

Since R2026b

collapse all in page

Syntax

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -cov-metric-level covLevel [instrumOptions] -- compileCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -cov-metric-level covLevel -instrument-in-place -msbuild [instrumOptions] -- MSbldCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -exec-metric-level executionTimeLevel -prof-counter-size counterSize [instrumOptions] -- compileCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -exec-metric-level executionTimeLevel -prof-counter-size counterSize -msbuild [instrumOptions] -- MSbldCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -stack-metric-level memoryUseLevel -prof-counter-size counterSize [instrumOptions] -- compileCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -stack-metric-level memoryUseLevel -prof-counter-size counterSize -msbuild [instrumOptions] -- MSbldCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -sanitizer [-sanitizer-selection defectSelection] [-sanitizer-max-error-occurrences maxOccurrences] [instrumOptions]-- compileCommand
polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -sanitizer [-sanitizer-selection defectSelection] [-sanitizer-max-error-occurrences maxOccurrences] -msbuild [instrumOptions] -- MSbldCommand
polyspace-code-profiler-server -run -instrum-dir instrumFolder -results-dir resultsFolder [runOptions] -- runCommand
polyspace-code-profiler-server -report -xml -report-dir reportDir [reportOptions] resultsPath
polyspace-code-profiler-server -report -html -report-dir reportDir [reportOptions] resultsPath
polyspace-code-profiler-server -report -xml -report-dir reportDir -filter-files filterFile [reportOptions] resultsPath
polyspace-code-profiler-server -report -html -report-dir reportDir -filter-files filterFile [reportOptions] resultsPath
polyspace-code-profiler-server -merge -results-dir mergedResult [mergeOptions] resultsToMerge
polyspace-code-profiler-server -merge -operation mergeOperation -results-dir mergedResult [mergeOptions] resultsToMerge
polyspace-code-profiler-server -convert -instrum-dir instrumFolder [convertOptions] binaryResultsPath
polyspace-code-profiler-server -justify-uncovered-dead-code -rationale reasonForDeadCode saResults [-target-filter-file customFilter] codeCoverageResults
polyspace-code-profiler-server -import-filters [-filter-file filterFile] sourceCovResult [-target-filter-file customFilter] targetCovResult
polyspace-code-profiler-server -version

Description

The polyspace-code-profiler-server system command instruments source code for code profiling and runs tests using the instrumented source code to collect code profiling results.

Instrument Source Files

Note

This Polyspace® command is available in the folder <POLYSPACEROOT>\polyspace\bin. Here, <POLYSPACEROOT> is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026b. To avoid typing the full path to this command, add this location to the PATH environment variable in your operating system.

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -cov-metric-level covLevel [instrumOptions] -- compileCommand instruments source files to calculate the code coverage metrics specified by covLevel.

In this step, Polyspace parses the source code, and then uses the compileCommand to compile the instrumented source files. If your code contains nonstandard code constructs, the parsing step might fail. Review the log to find which code constructs are unsupported. Before continuing, remove the unsupported construct.

example

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -cov-metric-level covLevel -instrument-in-place -msbuild [instrumOptions] -- MSbldCommand instruments a Microsoft® Visual Studio® project to calculate code coverage metrics specified by covLevel.

example

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -exec-metric-level executionTimeLevel -prof-counter-size counterSize [instrumOptions] -- compileCommand instruments the source files to calculate the execution time up to the level of details specified by executionTimeLevel. You cannot calculate more than one of the code coverage, execution time, or memory use metrics at a time.

example

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -exec-metric-level executionTimeLevel -prof-counter-size counterSize -msbuild [instrumOptions] -- MSbldCommand instruments a Microsoft Visual Studio project to calculate the execution time up to the level of details specified by executionTimeLevel. You cannot calculate more than one of the code coverage, execution time, or memory use metrics at a time.

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -stack-metric-level memoryUseLevel -prof-counter-size counterSize [instrumOptions] -- compileCommand instruments the source files to calculate the memory use up to the level of details specified by memoryUseLevel. You cannot calculate more than one of the code coverage, execution time, or memory use metrics at a time.

example

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -stack-metric-level memoryUseLevel -prof-counter-size counterSize -msbuild [instrumOptions] -- MSbldCommand instruments a Microsoft Visual Studio project to calculate the memory use up to the level of details specified by memoryUseLevel. You cannot calculate more than one of the code coverage, execution time, or memory use metrics at a time.

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -sanitizer [-sanitizer-selection defectSelection] [-sanitizer-max-error-occurrences maxOccurrences] [instrumOptions]-- compileCommand instruments the source files compiled by compileCommand for code sanitization.

polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -sanitizer [-sanitizer-selection defectSelection] [-sanitizer-max-error-occurrences maxOccurrences] -msbuild [instrumOptions] -- MSbldCommand instruments the source files in the Microsoft Visual Studio project built by MSbldCommand for code sanitization.

Run Instrumented Test Executable

polyspace-code-profiler-server -run -instrum-dir instrumFolder -results-dir resultsFolder [runOptions] -- runCommand runs the test executable runCommand, collects code profiling data, and creates a Polyspace Test™ profiling results (.psprof) file populated with the collected data. You must create the instrumented text executable before invoking this command. After calling polyspace-code-profiler-server -instrument, link the instrumented source files and tests with the Polyspace Test run-time libraries to create the instrumented test executable.

example

Create Report

polyspace-code-profiler-server -report -xml -report-dir reportDir [reportOptions] resultsPath creates XML reports from code profiling results stored in resultsPath. The reports are stored in reportDir.

polyspace-code-profiler-server -report -html -report-dir reportDir [reportOptions] resultsPath creates HTML reports from code profiling results stored in the paths you specify in resultsPath. The reports are stored in reportDir.

example

polyspace-code-profiler-server -report -xml -report-dir reportDir -filter-files filterFile [reportOptions] resultsPath creates XML reports from code profiling results stored in the paths you specify in resultsPath. The reports are stored in reportDir.

polyspace-code-profiler-server -report -html -report-dir reportDir -filter-files filterFile [reportOptions] resultsPath creates HTML reports from code profiling results stored in the paths you specify in resultsPath. The reports are stored in reportDir.

Merge Results and Filter Files

polyspace-code-profiler-server -merge -results-dir mergedResult [mergeOptions] resultsToMerge merges the data results stored in resultsToMerge and creates a merged data file. This command also merges any filters associated with each set of result. The merged data file and filters are stored in mergedResult. You can generate different results in various separate runs and then use this command to merge the results into a single file.

polyspace-code-profiler-server -merge -operation mergeOperation -results-dir mergedResult [mergeOptions] resultsToMerge performs mergeOperation on the results and filters stored in resultsToMerge and creates a new files in mergedResult.

Convert Results

polyspace-code-profiler-server -convert -instrum-dir instrumFolder [convertOptions] binaryResultsPath converts the binary results in binaryResultsPath into .psprof files. You typically obtain the code profiling results in binary form when running your tests on a target.

Justify Uncovered Dead Code Using Polyspace Code Prover or Polyspace Bug Finder Result

polyspace-code-profiler-server -justify-uncovered-dead-code -rationale reasonForDeadCode saResults [-target-filter-file customFilter] codeCoverageResults creates a filter file to justify the uncovered code in codeCoverageResults that are reported as unreachable or dead code in saResults. The generated filter file contains the reasonForDeadCode as the value for the field rationale.

Import Filters

polyspace-code-profiler-server -import-filters [-filter-file filterFile] sourceCovResult [-target-filter-file customFilter] targetCovResult imports comments and justifications from previous coverage results sourceCovResult to current coverage results targetCovResult. If the coverage results folder does not contain a filter file (.psprof.filter containing comments and justifications, specify a filter file explicitly using options -filter-file and -target-filter-file.

Version

polyspace-code-profiler-server -version displays the version of the Polyspace Test product.

Examples

collapse all

To calculate coverage for C/C++ code, first instrument your source files, then compile the instrumented sources with your tests and the instrumentation macro library, and finally run the resulting executable.

  1. Before instrumenting your code, compile the source and test files to make sure that there are no compilation errors. This example uses the GCC compiler (with compilation command gcc). The compilation command is:

    gcc src/source.c tests/test.c <PSTEST_SOURCE> -I <PSTEST_INCLUDE>
    Here, <PSTEST_SOURCE> and <PSTEST_INCLUDE> are locations of files and folders containing definitions of the Polyspace Test xUnit API macros. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  2. Instrument the source files used in the previous compilation command:

    polyspace-code-profiler-server -instrument -limit-instrumentation-to src -instrum-dir instrums -cov-metric-level mcdc -- gcc -c -D PSTEST_RUNTIME_AS_STATIC_LIBRARY=1 src/source.c tests/test.c <PSTEST_SOURCE> -I <PSTEST_INCLUDE>
    This command instruments the sources for calculating all available code coverage metrics and scopes the instrumentation to the src folder only. The results of this step, such as instrumented sources and traceability databases, are saved in the folder instrums/. The GCC compilation command uses the -c option to compile the files without linking the compiled object files.

  3. After generating the compiled objects, link them with the precompiled run-time library provided with Polyspace Test. You can link the objects and the library using the gcc compiler.

    gcc file.o test.o pstunit.o <PSPROFILELIB> -o testRunner
    Here, <PSPROFILELIB> is the path to a precompiled run-time library containing the instrumentation macro definitions. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

    This step generates the test executable, which you can run with polyspace-code-profiler-server -run to determine if the tests pass or fail and collect code profiling data. The test executable name is testRunner.exe in Windows® and testRunner.out in Linux®.

  4. Run the executable testRunner.exe (or testRunner.out) generated in the previous step, tracking the execution with polyspace-code-profiler-server -run:

    polyspace-code-profiler-server -run -instrum-dir instrums -results-dir results -- testRunner.exe
    This step generates code coverage results in a .psprof file in the folder results. You can upload the results to Polyspace Access™ or generate an HTML report from the results.

    To generate an HTML report, enter:

    polyspace-code-profiler-server -report -html -report-dir reports results

To calculate execution time for C/C++ code, first instrument your source files, then compile the instrumented sources with the instrumentation macro library (and optionally tests), and finally run the resulting executable.

  1. To create a test executable for calculating the execution time, instrument your code by using this syntax:

    polyspace-code-profiler-server -instrument -limit-instrumentation-to src/ -instrum-dir instrums/ -cov-metric-level none -exec-metric-level standard -prof-counter-size 32 -- gcc -c -D PSTEST_RUNTIME_AS_STATIC_LIBRARY=1 src/source.c tests/tests.c <PSTEST_SOURCE> -I <PSTEST_INCLUDE>
    Here, <PSTEST_SOURCE> and <PSTEST_INCLUDE> are locations of files and folders containing definitions of the Polyspace Test xUnit API macros. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  2. After successfully instrumenting the source code, link the compiled objects:

    gcc file.o test.o pstunit.o <PSPROFILELIB> -o testRunner
    Here, <PSPROFILELIB> is the path to a precompiled run-time library containing the instrumentation macro definitions. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

    This step generates the test executable, which you can run with polyspace-code-profiler-server -run to determine if the tests pass or fail and collect execution time data. The test executable name is testRunner.exe in Windows and testRunner.out in Linux.

  3. Run the executable testRunner.exe (or testRunner.out) generated in the previous step, tracking the execution with polyspace-code-profiler-server -run.

    polyspace-code-profiler-server -run -instrum-dir instrums -results-dir results -- testRunner.exe
    This step generates execution time results in a .psprof file in the folder results. You can upload the results to Polyspace Access, or generate an HTML report from the results.

    To generate an HTML report, enter:

    polyspace-code-profiler-server -report -html -report-dir reports results

To calculate memory use for C/C++ code, first instrument your source files, then compile the instrumented sources with the instrumentation macro library (and optionally tests), and finally run the resulting executable.

  1. To create a test executable for calculating the stack memory use, instrument your code by using this syntax:

    polyspace-code-profiler-server -instrument -limit-instrumentation-to src/ -instrum-dir instrums/ -stack-metric-level standard -prof-counter-size 64 -- gcc -c -D PSTEST_RUNTIME_AS_STATIC_LIBRARY=1 src/source.c tests/tests.c <PSTEST_SOURCE> -I <PSTEST_INCLUDE>
    Here, <PSTEST_SOURCE> and <PSTEST_INCLUDE> are locations of files and folders containing definitions of the Polyspace Test xUnit API macros. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  2. After successfully instrumenting the source code, link the compiled objects:

    gcc file.o test.o pstunit.o <PSPROFILELIB> -o testRunner
    Here, <PSPROFILELIB> is the path to a precompiled run-time library containing the instrumentation macro definitions. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

    This step generates the test executable, which you can run with polyspace-code-profiler-server -run to determine if the tests pass or fail and collect stack memory use data. The test executable name is testRunner.exe in Windows and testRunner.out in Linux.

  3. Run the executable testRunner.exe (or testRunner.out) generated in the previous step tracking the execution with polyspace-code-profiler-server -run:

    polyspace-code-profiler-server -run -instrum-dir instrums -results-dir results -- testRunner.exe
    This step generates memory use results in a .psprof file in the folder results. You can upload the results to Polyspace Access, or generate an HTML report from the results.

    To generate an HTML report, enter:

    polyspace-code-profiler-server -report -html -report-dir reports results

To run code sanitizer on C/C++ code, first instrument your source files, then compile the instrumented sources with the instrumentation macro library (and optionally tests), and finally run the resulting executable.

  1. To create a test executable for sanitizer profiling, instrument your source code by entering this syntax:

    polyspace-code-profiler-server -instrument -limit-instrumentation-to src/ -instrum-dir instrums/ -sanitizer -sanitizer-selection numeric -- gcc -c -D PSTEST_RUNTIME_AS_STATIC_LIBRARY=1 src/source.c tests/tests.c <PSTEST_SOURCE> -I <PSTEST_INCLUDE>

    Here, <PSTEST_SOURCE> and <PSTEST_INCLUDE> are locations of files and folders containing definitions of the Polyspace Test xUnit API macros. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

  2. After successfully instrumenting the source code, link the compiled objects:

    gcc file.o test.o pstunit.o <PSPROFILELIB> -o testRunner
    Here, <PSPROFILELIB> is the path to a precompiled run-time library containing the instrumentation macro definitions. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds.

    This step generates the test executable, which you can run with polyspace-code-profiler-server -run to determine if the tests pass or fail and collect information on any run-time error occurrences. The test executable name is testRunner.exe in Windows and testRunner.out in Linux.

  3. Run the executable testRunner.exe (or testRunner.out) generated in the previous step tracking the execution with polyspace-code-profiler-server -run:

    polyspace-code-profiler-server -run -instrum-dir instrums -results-dir results -- testRunner.exe
    This step generates code sanitizer results in a .psprof file in the folder results. You can upload the results to Polyspace Access, or generate an HTML report from the results.

    To generate an HTML report, enter:

    polyspace-code-profiler-server -report -html -report-dir reports results

The first step in calculating the code coverage of your code is to instrument your source files and produce the test executable from the instrumented code. Use the msbuild command at the Developer Command Prompt for Visual Studio to generate the instrumented test executable for the project. See Algorithms.

  1. After setting up a project demoProject.vcxproj, at the Developer Command Prompt for Visual Studio, navigate to the folder containing your project file and enter:

    polyspace-code-profiler-server -instrument -instrum-dir instrums -cov-metric-level mcdc -instrument-in-place -ignore-file <PSTEST_SOURCE> -msbuild -- msbuild demoProject.vcxproj /t:rebuild -p:platform=x64

    Note the following:

    • The file <PSTEST_SOURCE> refers to the file that contains definitions of the Polyspace Test xUnit API macros. For more information, see Set Up C/C++ Testing and Code Profiling Using Self-Managed Builds. Calculating coverage for this file is not necessary. Exclude the file from instrumenting by using -ignore-file.

    • When instrumenting Visual Studio projects, you must specify the options -instrument-in-place and -msbuild.

    • Specify a writable folder instrums to store the instrumented code and database.

    • To specify which code coverage metrics you want to calculate, set a value for -cov-metric-level. The default value is decision. To calculate coverage of all supported coverage metrics, use mcdc.

    The folder instrums stores the instrumented source files. The x64/Debug folder contains the instrumented test executable.

  2. After instrumenting your code, at the Developer Command Prompt for Visual Studio, enter:

    polyspace-code-profiler-server -run -instrum-dir instrums -results-dir results -- "x64/Debug/demoProject.exe"

    • Specify the folder instrums as the input to -instrum-dir. This folder must contain the instrumented code.

    • Specify a writable folder results as the input to -results-dir. The run command generates the results file ( .psprof) from the instrumented code, and stores it in the results folder.

    • Specify the instrumented test executable to run. In this example, this test executable is in x64/Debug.

When reviewing coverage results, you can add justifications and comments to missing coverage results that you do not plan to fix. You can carry forward these justifications to later code coverage results on the same or updated source code.

Suppose that your previous coverage results are stored in a folder results_run1. This folder contains a .psprof file containing the coverage results and a .psprof.filter file containing justifications added to those results.

  1. Rerun code profiling and store your results in a folder results_run2. At this point, the results folder only contains coverage results (.psprof file).

  2. To import review information from previous coverage results stored in folder results_run1 to new results in folder results_run2, enter:

    polyspace-code-profiler-server -import-filters results_run1 results_run2

    If the filters are imported successfully, the folder results_run2 contains a new .psprof.filter file with the imported justifications and comments. You can open the coverage results in the Polyspace Access web interface and verify that the previous justifications and comments were imported.

Input Arguments

collapse all

Instrument Source Files

Path to folder containing instrumented sources and a traceability database (database listing files, functions, decisions, and other elements that are instrumented for code profiling). This folder:

  • Must be provided as a results folder in the instrumentation step:

    polyspace-code-profiler-server -instrument -instrum-dir <instrumFolder>

  • Must be provided as input to the code profiling data collection step (and must be the same as the results folder in the previous instrumentation step):

    polyspace-code-profiler-server -run -instrum-dir <instrumFolder>
    Or:
    polyspace-code-profiler-server -convert -instrum-dir <instrumFolder>

  • Must be different than the folder where you keep the source files that you specified as the input to -limit-instrumentation-to.

You must have write access to this folder. if you do not have permission to write in this folder, the instrumentation process fails.

Example: -instrum-dir "C:\src\coverage_data\"

Compiler command specified exactly as you use to compile your source code. The instrumentation step extracts all source filenames from this compile command.

Example: gcc src.c, g++ src.cpp

msbuild command specified exactly as you use to build your Visual Studio project. The option -instrument-in-place is required when you instrument a Visual Studio project.

Example: msbuild demoProject.vcxproj /t:Rebuild -p:platform=x64

Polyspace profiles your code to calculate various test coverage metrics. To enable the different coverage levels, use these values:

If you specify a value for -cov-metric-level, then you cannot specify -exec-metric-level at the same time.

Example: -cov-metric-level mcdc

Polyspace profiles your code to calculate the execution time at different levels of details. To select the different levels, use these values:

  • none — Disables collecting execution time data.

  • minimal — Enables calculating the Total time.

  • standard — Enables calculating Total time, Self Time, and Count.

  • detailed — Enables calculating Total time, Self Time, and Count, and Max.

See Execution Time.

Polyspace Test does not support simultaneously calculating more than one among code coverage, execution time, and memory use.

Example: -exec-metric-level standard

Polyspace profiles your code to calculate the memory use at different levels of details. To select the different levels, use these values:

  • none — Disables collecting memory use.

  • minimal — Enables calculating the maximum (max) stack memory usage of a function among its different execution path.

  • standard — Enables calculating the stack memory use by each function (self) as well as the max value for each function.

  • detailed — Enables calculating max, self, and Count values.

See Memory Use.

Polyspace Test does not support simultaneously calculating more than one among code coverage, execution time, and memory use.

Example: -stack-metric-level standard

This option represents the width of the platform on which you run your test executable. This option is required if you specify -exec-metric-level or -stack-metric-level. If your target platform is narrower than 32 bits, specify 32 as the value.

Example: -prof-counter-size 32

This option specifies the types of defects that must be covered during code sanitization. Specify one or more of these values in a comma-separated list when instrumenting your source files for code sanitization:

  • numeric: Instruments only those expressions that might cause numeric errors such as numeric overflows and division by zero.

  • memory: Instruments only those expressions that might cause static or dynamic memory-related errors such as array or pointer access out of bounds.

  • memleak: Instruments memory allocation and deallocation operations to detect memory that is allocated but never freed during test execution.

If you omit this option, the value implicitly selected is numeric, memory.

Example: -sanitizer-selection numeric

This option specifies the maximum number of error occurrences that must be reported by the code sanitizer before it stops reporting errors. If you omit this option, there is no ceiling on the error reporting and all errors found are reported.

If the binary created using instrumented sources takes a long time to run, try setting a lower value for this option.

Example: -sanitizer-max-error-occurrences 100

File Instrumentation Options

OptionArgumentDescription
-limit-instrumentation-toPath to folder

Limit instrumentation to the specified folder and exclude other files.

This option works exactly opposite to the -ignore-dir option. If you specify both options on the same folder, you see an error. If you specify -limit-instrumentation-to on a folder and -ignore-dir on a subfolder of that folder, the subfolder is ignored.

Example: -limit-instrumentation-to src

-ignore-dirPath to folder

Path to folders containing sources that must not be instrumented.

This option works exactly opposite to the -limit-instrumentation-to option. If you specify both options on the same folder, you see an error. If you specify -ignore-dir on a folder and -limit-instrumentation-to on a subfolder of that folder, the subfolder is instrumented.

Example: -ignore-dir src/3rdparty/

-ignore-filePath to file

Path to file that must not be instrumented. You can specify this option multiple times.

Example: -ignore-file src/framework.c

-ignore-fcnFunction name

Function that must not be instrumented.

For functions that are part of a namespace, use the fully qualified name, including the scope resolution operator.

Example: -ignore-fcn main

-ignore-fcn-callFunction name

Ignore the coverage of calls to one or more functions.

For functions that are part of a namespace, use the fully qualified name, including the scope resolution operator. If you specify a function with multiple overloads, calls to all overloads of the function are ignored.

When you specify a function as an input to this option, the content of the function is instrumented, but the call to the function is not instrumented.

Example: -ignore-fcn-call foo

-fail-if-errorN/A

Whether code instrumentation must stop on build errors.

By default, code instrumentation can continue if your build command invokes a compiler and the compilation is successful (even if there are other build errors later). Use this option if you want the code instrumentation to stop on any kind of build error.

-instrument-in-placeN/A

Whether the source files must be instrumented in place.

By default, a copy of the source files are instrumented. The instrumentation step:

  1. Parses the build command to identify the source files.

  2. Copies the source files into instrumFolder.

  3. Instruments the copied source files to generate the traceability data base.

In this process, Polyspace Test does not modify your original source file.

If the source files cannot be identified by parsing the build command, use the option -instrument-in-place to instrument the original sources themselves.

If you specify this option, then the source files must be in a writable folder. If you specify this option without having write permissions for the source files, Polyspace exits with an error.

To avoid data races and compilation errors, using this option is not recommended when instrumenting the same source file multiple times in parallel.

-compactN/A

Selecting this option might reduce the amount of memory required to run the test executable.

By default, when instrumenting your code for code coverage calculations, Polyspace allocates an unsigned 32-bit integer counter to count the number of times a coverage outcome is achieved. When you specify this option, Polyspace allocates only a single bit to record whether a coverage outcome was achieved or not.

For more information, see Enable compact mode for coverage calculation (-compact).

-cov-relboundN/A

Specify this option to enable computation of relational boundary coverage.

-cov-relbound-abs-tolNumberAbsolute tolerance value for relational boundary coverage. A warning is shown if you specify this option without specifying -cov-relbound.
-cov-relbound-rel-tolNumberRelative tolerance value for relational boundary coverage. A warning is shown if you specify this option without specifying -cov-relbound.
-sources-encoding

The encoding method of your source code.

Valid values for this options include:

  • system: Specifies the encoding method as the default encoding method of the operating system you use.

  • auto: Polyspace Test uses internal heuristics to determine the encoding method used in your source file from its content.

  • shift-jis: Specifies the source code encoding as Shift JIS (Shift Japanese Industrial Standards). This encoding method is used for encoding Japanese language.

  • iso-8859-1: Specifies the encoding as ISO/IEC 8859-1. This ASCII-based character encoding method encodes "Latin alphabet no.1", which consists of 191 characters from the Latin script.

  • windows-1252: Specifies the encoding as Windows-1252. This single byte encoding method is used by some legacy Windows components for encoding European language characters.

  • UTF-8: Specifies the encoding as UTF-8. This encoding method encodes all Unicode code points by using up to four 8-bit blocks.

-sources-encoding-listN/AUse this option to obtain a complete list of all source encoding supported by Polyspace Test. When you use this option, the log contains a message that lists all supported source encoding.

Other Options

OptionArgumentDescription
-options-filePath to text file

Path to a text file containing one option per line.

Example: -options-file options\instrum_options.txt

-verbose 

Whether the instrumentation command produces a more detailed output on the console (with individual steps of instrumentation broken down).

Use this option for troubleshooting purposes. By default, if an error occurs during instrumentation, you see the error message. If you also want to see the phases of instrumentation that completed before the error, use this option.

-help 

Use this option to see the options available with polyspace-code-profiler-server -instrument.

Run Instrumented Test Executable

Command to run the instrumented test executable. This test executable is previously created by linking object files from:

Example: testrunner.out, testrunner.exe

The run command executes the instrumented source code and generates a results (.psprof) file containing the code profiling data. The resultsFolder contains the .psprof file and other outputs of the run command. Use this folder as the resultsPath to generate a report.

Example: -result-dir ../results

Options for Test Execution, Code Profiling Data Collection, and Storage

OptionArgumentDescription
-results-dirPath to folder

Path to folder where code profiling data is stored after running the test executable.

Example: -results-dir results/

-working-dirPath to folder

Path to folder from which the test executable must be run.

Example: -working-dir execs/

-results-nameString

Name of the output without the extension. The default name is 'output_run'.

Example: -results-name new_results

-return-code-fail-valueintSpecify the value that the -run commands returns if there are no errors in the source code, but the -run command fails to produce a results (.psprof) file. If you do not specify this option, the -run command returns the default value 253 in such a situation.
-return-code-from-app N/A

When you specify this option, the run command returns different values for different errors.

ErrorReturn value
Error in command syntax1
Error in your source codeError code returned by the test executable.
No error in command syntax and no Error in code, but a results (.psprof) file is not generated.Value specified by -return-code-fail-value. If no value if specified as -return-code-fail-value, the -run command returns the default value 253.
No error in command syntax and no Error in code, and a results (.psprof) file is generated.The value returned by the test executable.

If you do not specify this option, the run command returns a single value 1 in case of any failure, and a single return value 0 if a .psprof file is generated.

Other Options

OptionArgumentDescription
-options-filePath to text file

Path to a text file containing one option per line.

Example: -options-file options\run_options.txt

-do-not-remove-duplicated 

By default, if multiple instrumented source files correspond to the same source file, Polyspace Test considers the latest instrumented source files and traceability database when profiling the code.

Use this option to consider the older instrumented source files as well when profiling the code. For instance, you might have instrumented two versions of the same source file with different options. Using this file allows you to retain the traceability files for both versions and, for instance, include both versions of the results in your report.

-verbose 

Whether the run command produces a more detailed output on the console.

Use this option to see the results of test execution along with code profiling data collection. By default, Polyspace Test suppresses the results of test execution. To see those results, you have to run the test executable by itself (without the polyspace-code-profiler-server -run command). If you want to see test execution results and collect code profiling data in one step, use the -verbose option.

-help 

Use this option to see the options available with polyspace-code-profiler-server -run.

Create Report

Path to results (.psprof) files or folders containing .psprof. If you specify path to one or more folders containing .psprof files, a report is generated from each .psprof files in those folders.

The results files are generated by executing the run command, either on host or on a target.

  • For execution on a host, the test execution step can be run on its own or preceded by the command polyspace-code-profiler-server -run. If the execution step runs on its own, the results file is a .bin file. Otherwise, the results file is a .psprof file. These files can be located in resultsFolder after you execute the run command.

  • After execution on target, the results file is a .bin file. Transfer the .bin file back to the host for conversion and report generation.

If the results file is a .bin file, you provide the folder containing this file to the command polyspace-code-profiler-server -convert to generate a .psprof file. You then provide the path containing a .psprof file to the command polyspace-code-profiler-server -report for generating HTML reports.

Example: ../results

After you run the report command, the generated reports are stored in the folder reportDir.

Example: -report-dir ../reportFolder

Path to a filter (.psprof.filter) file. To justify or exclude certain coverage results in the generated report, you create a .psprof.filter filter file and specify the path to the file as filterFile. If you do not specify a specific filterFile, Polyspace Test uses the default filter file. Typically, the default filter file is stored in the same folder as the .psprof file.

Example: -filter-files Filter/filterFile.psprof.filter

Reporting Options

OptionArgumentDescription
-report-dirPath to folder

Path to folder where Polyspace Test stores the generated reports.

Example: -report-dir reports/

-add-environment-infoPath to file

Path to JSON file specifying environment information to be added to the report. Use this option if you want to save environment information in your profiling result reports.

The JSON file has the following structure: 

{
    "BuildConfiguration": "<nameOfConfiguration>",
    "ConfigurationDescription": "<descriptionOfConfiguration>",
    "Toolchain": "<nameOfToolchain>",
    "Board": "<nameOfBoard>"
}
You can set these values as desired to reflect your profiling configuration.

Note that if you generate a report using a Polyspace Platform project, the same values are automatically populated from your project configuration and you do not require to specify an additional file for the environment information. For more information on the values expected for the JSON keys, see Structure of HTML Reports Generated from C/C++ Test Results.

Example: -add-environment-info env_info.json

Other Options

OptionArgumentDescription
-options-filePath to text file

Path to a text file containing one option per line.

Example: -options-file options\report_options.txt

-verbose 

Whether the run command produces a more detailed output on the console.

Use this option for troubleshooting purposes. By default, if an error occurs during the report generation, you see the error message. If you also want to see the steps that completed before the error, use this option.

-help 

Use this option to see the options available with polyspace-code-profiler-server -report.

Merge Results

Path to .psprof files or folders containing the .psprof files. If you specify the path to one or more folder, all .psprof files in those folders are merged. You generate the .psprof data files in previous analyses. For example, if you execute the polyspace-code-profiler-server -run command, the .psprof is stored in the resultsFolder. If you have .bin files instead of .psprof files, use polyspace-code-profiler-server -convert to generate .psprof files from the .bin files.

Example: ../previous_results

Path to folder where the merged .psprof file is stored.

Example: -result-dir merged_results/

Specify what operation to perform between two results files.

  • union: Polyspace Test performs a union between the input results in resultsToMerge. The result file in mergedResults contains the aggregate of the input files. This operation can be performed on two or more input folders. If the input folders contain filter files, Polyspace moves the most recent filter files into the folder mergedResults.

  • diff: Polyspace Test performs a diff operation between the input results in resultsToMerge. The results file contains the difference calculated by excluding the results from the second folder in resultsToMerge from the first folder in resultsToMerge. This operation is sensitive to the order in which you specify the input folders. This operation can be performed only between two input folders. If the input folders contain filter files, the filter from the first folder is moved into mergedResults.

  • intersect: Polyspace Test performs an intersection between the results in resultsToMerge. The resultant results file contains the results that are present in all input folders. This operation can be performed on two or more input folders. If the input folders contain filter files, Polyspace moves the most recent filter files into the folder mergedResults.

  • aggregate-variants: Polyspace Test aggregates results from different code variants. Specify the results from the code variants in resultsToMerge. The results file in mergedResults combines the code coverage and profiling results from the different variants and provide a combined overview.

Example: -operation diff

Merging Options

OptionArgumentDescription
-results-nameName of the produced results file

Name of the merged results file without the extension. The default name is 'output_merged'.

Example: -results-name merged_results

Other Options

OptionArgumentDescription
-options-filePath to text file

Path to a text file containing one option per line.

Example: -options-file options\report_options.txt

-verbose 

Whether the run command produces a more detailed output on the console.

Use this option for troubleshooting purposes. By default, if an error occurs during the report generation, you see the error message. If you also want to see the steps that completed before the error, use this option.

-help 

Use this option to see the options available with polyspace-code-profiler-server -report.

Convert Results

Space-separated .bin file paths or paths to folder(s) containing coverage results in .bin files. If you provide file paths and your files do not have the .bin extension, the polyspace-code-profiler-server -convert command attempts to convert them anyway.

If you convert more than one .bin file, when you convert the results, the coverage data in all the .bin files are accumulated into a single .psprof file.

Example: ../binaryFolder

Converting Options

OptionArgumentDescription
-results-dirPath to folder

Path to folder where the converted result is stored.

Example: -results-dir converted_results/

-results-nameName of the converted results file

Name of the converted results file without the extension. The default name is 'output_converted'.

Example: -results-name converted_results

Other Options

OptionArgumentDescription
-options-filePath to text file

Path to a text file containing one option per line.

Example: -options-file options\report_options.txt

-verbose 

Whether the run command produces a more detailed output on the console.

Use this option for troubleshooting purposes. By default, if an error occurs during the report generation, you see the error message. If you also want to see the steps that completed before the error, use this option.

-do-not-remove-duplicated 

By default, if multiple instrumented source files correspond to the same source file, Polyspace Test considers the latest instrumented source files and traceability database when profiling the code.

Use this option to consider the older instrumented source files as well when profiling the code. For instance, you might have instrumented two versions of the same source file with different options. Using this file allows you to retain the traceability files for both versions and, for instance, to include both versions of the results in your report.

-help 

Use this option to see the options available with polyspace-code-profiler-server -report.

Justify Dead Code using Polyspace Bug Finder or Polyspace Code Prover Result

Provide a reason why some code in your source files is unreachable and thus cannot be covered by your tests. In the report, the coverage results of the uncovered code is then justified with the provided rationale.

Example: 'Justifying unreachable defensive code'

Path to a Code Prover results file (.pscp) or Bug Finder results file (.psbf). If the static analysis flags some code as unreachable, Polyspace Test justifies the coverage results of these unreachable code.

Example: ../foo.psbf

Path to code coverage results (.psprof) files. This file contains the unfiltered code coverage results of your code.

Example: ../foo.psprof

By default, Polyspace Test applies the default filter on the code coverage result. The default filter is located in the same folder as the results (.psprof) file. To specify a different filter, specify the path to the filter file as customFilter.

For more information on filter files, see Improve or Justify Missing Code Coverage Results.

Example: ../bar.psprof.filter

Import Filters

Folder containing old coverage results file (.psprof file) and associated review information file (.psprof.filter file).

Example: -import-filters source.psprof target.psprof

Folder containing new coverage results file (.psprof file). This folder might or might not contain a review information file (.psprof.filter file).

Example: -import-filters source.psprof target.psprof

Limitations

  • The command polyspace-code-profiler-server does not support multithreaded code.

  • When you instrument your code by using the polyspace-code-profiler-server -instrument command, Polyspace converts the encoding of your source files to utf-8 and then inserts instrumentation macros in the converted source files. If your code relies on the raw binary values of the source files, the change in encoding can result in unexpected result.

  • The instrumentation process might prevent some compiler optimization, such as inlining of functions. The execution time of the instrumented code can be larger than the execution time of the uninstrumented code. The execution times calculated by Polyspace Test represents the upper limit of the execution time of your code.

  • The instrumentation process might increase the stack memory use of your function. The memory use calculated by Polyspace Test represents the upper limit of the memory use of your code.

  • Because C++ compilers call destructors before a function exit, the calculated memory use of a function is larger if you compile your code using a C++ compiler.

  • Polyspace Test cannot calculate the stack memory consumed by the entry-point function. The self and max value of the memory use metric for entry-point functions are reported as 0.

  • When calculating the execution time and memory use of C++ code, polyspace-code-profiler-server ignores these functions:

    • Functions that throw an exception.

    • Functions that handle an exception thrown elsewhere in the call stack.

  • When calculating the memory use, Polyspace Test ignores variable length arrays (VLA).

  • If you use a function that is not instrumented, Polyspace Test does not measure the code coverage, execution time, or memory use of the function. When calculating the memory use of functions that call such uninstrumented functions, the memory use of the uninstrumented functions are ignored.

Tips

  • If you want to exclude specific portions of your source code from code profiling, use the pragma tmw code_instrumentation off. When Polyspace Test encounters this pragma, it stops instrumenting the source code until it encounters the pragma tmw code_instrumentation on. For instance, in this code, the call to foo is excluded from code profiling:

    void bar(){
	//...
	#pragma tmw code_instrumentation off 
	foo();
	#pragma tmw code_instrumentation on
	//....
}

  • Instead of typing the polyspace-code-profiler-server commands for instrumentation, run, and reporting directly at the command line, you can enter them in a makefile and execute make at the command line. For an example makefile, see Calculate Code Profile by Using Makefile.

    You can also generate such a makefile using generators such as CMake. For instance, when generating a makefile with the cmake command, in addition to your usual CMake flags, define the following variables using cmake options:

    • CMAKE_C_COMPILER_LAUNCHER: Set this variable to the full path of the polyspace-code-profiler-server command. Add appropriate polyspace-code-profiler-server options, separating the command from options and options from each other, using a ; separator.

      For instance, to construct the command:

      polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -- gcc <files>
      You can define these variables at the command line using the following flag:
      -DCMAKE_C_COMPILER=gcc -DCMAKE_C_COMPILER_LAUNCHER="polyspace-code-profiler-server;-instrument;-instrum-dir;instrumFolder;--"

    • CMAKE_CXX_COMPILER_LAUNCHER: Set this variable to the full path of the polyspace-code-profiler-server command. Add appropriate polyspace-code-profiler-server options, separating the command from options and options from each other using a ; separator.

      For instance, to construct the command:

      polyspace-code-profiler-server -instrument -instrum-dir instrumFolder -- g++ <files>
      You can define these variables at the command line using the following flag:
      -DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_COMPILER_LAUNCHER="polyspace-code-profiler-server;-instrument;-instrum-dir;instrumFolder;--"

    • CMAKE_EXE_LINKER_FLAGS: Set this variable to flags required for linking to the precompiled coverage instrumentation library available with Polyspace Test.

      For instance, to link to the library libmwpsprofile_cli_runtime, precompiled using MinGW in Windows, you can define the variable as follows:

      -DCMAKE_EXE_LINKER_FLAGS="-L \"<polyspaceroot>/polyspace/psprofile/lib/win64/import/mingw64\" -L \"<polyspaceroot>/polyspace/psprofile/lib/win64\" -l mwpsprofile_cli_runtime"
      Here, <polyspaceroot> is the path to the Polyspace installation folder, for instance, C:/Program Files/Polyspace/R2026b.

Algorithms

The code coverage calculation algorithm consists of several steps. The code instrumentation step:

  1. Runs the compileCommand or the MSbldCommand.

  2. Extracts source filenames from the executed processes.

  3. Instruments the source files with Polyspace Test macros to collect code profiling data.

  4. Creates the test executable.

After creating the test executable, in the next step, run the test executable. This step collects the code profiling data from your source code.

Once you generate the code profiling database, create an HTML or XML report from the data base.

For the complete workflow, see:

Version History

Introduced in R2026b

See Also

| | | | | | | |

Topics