polyspaceConfigure

Create Polyspace Platform project, workspace, or options file from build command or compilation database

collapse all in page

Syntax

polyspaceConfigure [-output-platform-project|-update-platform-project] psPlatformProject [options] buildCommand
polyspaceConfigure [-output-platform-project|-update-platform-project] psPlatformProject -compilation-database jsonFile [options]
polyspaceConfigure -module [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand
polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand
polyspaceConfigure -module-output-pattern regexPattern [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand
polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] [-output-platform-project|-update-platform-project] psPlatformWorkspace -compilation-database jsonFile [options]
polyspaceConfigure -module-output-pattern regexPattern [-output-platform-project|-update-platform-project] psPlatformWorkspace -compilation-database jsonFile [options]
polyspaceConfigure -output-options-file optionsFile [options] buildCommand
polyspaceConfigure -output-options-file optionsFile -compilation-database jsonFile [options]
polyspaceConfigure -module -output-options-path optionsFolder [options] buildCommand
polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] -output-options-path optionsFolder [options] buildCommand
polyspaceConfigure -module-output-pattern regexPattern -output-options-path optionsFolder [options] buildCommand
polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] -output-options-path optionsFolder -compilation-database jsonFile [options]
polyspaceConfigure -module-output-pattern regexPattern -output-options-path optionsFolder -compilation-database jsonFile [options]

Description

The polyspaceConfigure command creates a Polyspace® Platform project or options file from a build command or compilation database.

Note

Before you run Polyspace from MATLAB®, you must link your Polyspace and MATLAB installations. See Integrate Polyspace with MATLAB and Simulink or Integrate Polyspace Server Products with MATLAB.

Create Project

polyspaceConfigure [-output-platform-project|-update-platform-project] psPlatformProject [options] buildCommand creates a Polyspace Platform project (.psprjx file) using information gathered from executing the command buildCommand.

  • If you use the option -output-platform-project, the command creates a new project.

  • If you use the option -update-platform-project, the command updates an existing project by overwriting auto-generated information such as automatically added sources and build configuration, and retaining manually added information such as static analysis configuration and tests.

If you create a project from a build command using polyspaceConfigure, the build command must be the last entry. Any option following the build command is considered as an option for the build command and not a polyspaceConfigure option.

example

polyspaceConfigure [-output-platform-project|-update-platform-project] psPlatformProject -compilation-database jsonFile [options] creates a Polyspace Platform project using information gathered from the JSON compilation database file specified by jsonFile.

Create Workspace with Multiple Projects for Multiple Components

polyspaceConfigure -module [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand creates or updates a Polyspace Platform workspace (.pswks file) using information from buildCommand. Each project in the workspace corresponds to one binary created by the build command and includes sources directly involved in creating the binary. The option -module is supported only if your build command uses GNU® or Visual C++® linkers.

polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand creates or updates a Polyspace Platform workspace (.pswks file) using information from buildCommand. If the file fileWithModulesList lists multiple root folders with one folder per line, each project in the workspace includes all sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current folder unless you use the option -project-root.

polyspaceConfigure -module-output-pattern regexPattern [-output-platform-project|-update-platform-project] psPlatformWorkspace [options] buildCommand creates or updates a Polyspace Platform workspace (.pswks file) using information from buildCommand. If the regular expression regexPattern contains a capturing group capturing multiple root folders, each project in the workspace includes all sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current folder.

polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] [-output-platform-project|-update-platform-project] psPlatformWorkspace -compilation-database jsonFile [options] creates or updates a Polyspace Platform workspace (.pswks file) using information from a compilation database jsonFile. If the file fileWithModulesList lists multiple root folders with one folder per line, each project in the workspace includes all sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current folder unless you use the option -project-root.

polyspaceConfigure -module-output-pattern regexPattern [-output-platform-project|-update-platform-project] psPlatformWorkspace -compilation-database jsonFile [options] creates or updates a Polyspace Platform workspace (.pswks file) using information from a compilation database jsonFile. If the regular expression regexPattern contains a capturing group capturing multiple root folders, each project in the workspace includes all sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the directory entry in the compilation database.

Create Options File

polyspaceConfigure -output-options-file optionsFile [options] buildCommand creates an options file for Polyspace static analysis using information gathered from executing the command buildCommand.

polyspaceConfigure -output-options-file optionsFile -compilation-database jsonFile [options] creates an options file for Polyspace static analysis using information gathered from the JSON compilation database file specified by jsonFile.

Create Multiple Options Files for Multiple Components

polyspaceConfigure -module -output-options-path optionsFolder [options] buildCommand creates multiple options files for static analysis in optionsFolder using information from buildCommand. Each options file corresponds to one binary created by the build command and lists sources directly involved in creating the binary. The option -module is supported only if your build command uses GNU or Visual C++ linkers.

polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] -output-options-path optionsFolder [options] buildCommand creates multiple options files for static analysis in optionsFolder using information from buildCommand. If the file fileWithModulesList lists multiple root folders with one folder per line, each generated options file lists sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current working folder unless you use the option -project-root.

polyspaceConfigure -module-output-pattern regexPattern -output-options-path optionsFolder [options] buildCommand creates multiple options files for static analysis in optionsFolder using information from buildCommand. If the regular expression regexPattern contains a capturing group capturing multiple root folders, each generated options file lists sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current folder.

polyspaceConfigure -modules-list fileWithModulesList [-project-root commonRootFolder] -output-options-path optionsFolder -compilation-database jsonFile [options] creates multiple options files for static analysis in optionsFolder using information from a compilation database jsonFile. If the file fileWithModulesList lists multiple root folders with one folder per line, each project in the workspace includes all sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the current folder unless you use the option -project-root.

polyspaceConfigure -module-output-pattern regexPattern -output-options-path optionsFolder -compilation-database jsonFile [options] creates multiple options files for static analysis in optionsFolder using information from a compilation database jsonFile. If the regular expression regexPattern contains a capturing group capturing multiple root folders, each generated options file lists sources residing under one such root folder. If the folder paths are not absolute, they are resolved with respect to the directory entry in the compilation database.

Examples

collapse all

This example shows how to use a compile command to create a Polyspace Platform project. The simplest way to run polyspaceConfigure is to run it directly on the compile command used to build your source code. This example uses the GCC compiler and the compile command gcc. GCC is a standard compiler suite included with Linux® based systems. For Windows® based systems, MinGW can be installed to support the GCC compiler.

To create a Polyspace Platform project from a gcc compilation:

  1. Open a terminal and run the gcc command to ensure that your source code compiles without errors. 

    gcc myFilename.c otherFile.c
    After confirming that your source code compiles without errors, remove the object files before continuing.
    rm myFilename.o otherFile.o

  2. Create a Polyspace Platform project specifying a unique project name. Run polyspaceConfigure on the compile command as previously tested.

    polyspaceConfigure -output-platform-project myProject gcc myFilename.c otherFile.c

  3. Open the Polyspace Platform project in the Polyspace Platform user interface.

    If you use Visual Studio® to compile your sources, you can replace gcc in the above example with cl. You can also run polyspaceConfigure on a full build of your Visual Studio project. See Create Polyspace Platform Projects From IDE Builds.

Input Arguments

collapse all

Build command specified exactly as you use to build your source code. polyspaceConfigure supports tracing of a build command only if the build command meets certain requirements. See Requirements for Polyspace Project Creation from Build Systems.

The build command must perform a full build of your sources and not an incremental build. Typically, build commands such as make are set up to only build sources that have changed since the previous build. However, polyspaceConfigure requires a full build to determine which sources to add to a Polyspace project or options file. Add appropriate options to your build command to force a full build. For instance, when using a makefile, append the option -B to make.

Example: make -B, make -B -W makefileName

Name and path to JSON compilation database, specified as a string. The extracted compiler paths in the JSON CDB must be accessible from the path where you run polyspaceConfigure.

These build systems and compilers support the generation of a JSON CDB:

  • CMake

  • Bazel

  • Clang

  • Ninja

  • Qbs

  • waf

For more on JSON compilation databases, see JSON Compilation Database.

Name and path of generated Polyspace Platform project, specified as a string.

  • If you omit the path and specify a name only, a project file with this name and extension .psprjx is generated in the current folder.

    For instance, -output-platform-project newProject creates a project newProject.psprjx in the current folder.

  • If you specify a name and path, a project file with this name and extension .psprjx is generated in the specified folder.

    For instance, -output-platform-project ../myProjects/newProject creates a project newProject.psprjx in the folder with the relative path ../myProjects/.

Name and path of generated Polyspace Platform workspace, specified as a string.

  • If you omit the path and specify a name only, a workspace file with this name and extension .pswks is generated in the current folder.

    For instance, -output-platform-project newWorkspace creates a project newWorkspace.pswks in the current folder.

  • If you specify a name and path, a workspace file with this name and extension .pswks is generated in the specified folder.

    For instance, -output-platform-project ../myWorkspaces/newWorkspace creates a project newWorkspace.pswks in the folder with the relative path ../myWorkspaces/.

Name and path of generated options file, specified as a string.

  • If you omit the path and specify a name only, an options file with this name is generated in the current folder.

    For instance, -output-options-file newOptsFile creates a file newOptsFile in the current folder.

  • If you specify a name and path, an options file with this name is generated in the specified folder.

    For instance, -output-options-file ../myPolyspaceFiles/newOptsFile creates an options file newOptsFile in the folder with the relative path ../myPolyspaceFiles/.

Note that a Polyspace options file is useful only for static analysis using one of these commands:

Path to folder, specified as a string. All generated options files are stored in this folder.

Path to folder with respect to which all relative paths must be resolved, specified as a string.

Path to file listing root folders, specified as a string. The file must contain one root folder per line. All source files in a root folder are considered as part of a single component.

Regular expression with capturing group, specified as a string. If the capturing group captures multiple root folders, all source files in one root folder are considered as part of a single component.

OptionDescription
-author authorName

Name of project author.

Example: -author jsmith

-allow-build-error

Option to create a Polyspace project even if an error occurs in the build process.

If an error occurs, the build trace log shows the following message:

polyspace-configure (polyspaceConfigure) 
   ERROR: build command 
   command_name fail [status=status_value]
command_name is the build command name that you use and status_value is the non-zero exit status or error level that indicates which error occurred in your build process.

This option can create a useful project if your build command builds the source files but exits with a non-zero exit status. If your source files do not compile and the build fails, resolve your build failure before using polyspace-configure (polyspaceConfigure) again.

This option is ignored when you use -compilation-database.

-allow-overwrite

Option to overwrite a project with the same name, if it exists.

By default, polyspace-configure (polyspaceConfigure) throws an error if a project with the same name already exists in the output folder. Use this option to overwrite the project.

-no-console-output

-silent (default)

-verbose

Option to suppress or display additional messages from running polyspace-configure (polyspaceConfigure).

  • -no-console-output – Suppress all outputs including errors and warnings.

  • -silent (default) – Show only errors and warnings.

  • -verbose – Show all messages.

If you specify more than one of these options, the most verbose option is applied.

Polyspace ignores these options when you use them in combination with -easy-debug.

-help

Option to display the full list of polyspace-configure (polyspaceConfigure) commands.

-debug

Option to store debug information for use by MathWorks® technical support.

This option has been superseded by the option -easy-debug.

-easy-debug folderPath

Path of folder where Polyspace stores debug information for use by MathWorks technical support.

After a polyspace-configure (polyspaceConfigure) run, the folder folderPath contains a zipped file ending with pscfg-output.zip. If the run fails to create a complete Polyspace project or options file, send this zipped file to MathWorks Technical Support for further debugging. The zipped file does not contain source files traced in the build. See also Errors in Project Creation from Build Systems.

OptionDescription
-categorization-config filePath

Path to file categorization XML file for distinguishing sources from tests in a Polyspace Platform project. Note that you do not need to use this XML file for test files using the following testing frameworks because the files are automatically identified as tests based on their inclusion of specific headers:

  • Polyspace Test™ xUnit framework: The test files are identified by their inclusion of the header pstunit.h.

  • GoogleTest: The test files are identified by their inclusion of the header gtest.h.

  • Catch2: The test files are identified by their inclusion of the header catch2.h.

The file classification XML is required only to enable support for other testing frameworks or to extend the support for the above testing frameworks.

You can start creating the file categorization XML from this template:

<categories>
   <category name="test">
      <directories>
          <dir>myPSTestXUnitTestDir</dir>
      </directories>
      <headers>
          <include>myPSTestXUnitTestHeader</include>
      </headers>
   </category>
      <category name="external_test">
      <directories>
          <dir>myExternalTestDir</dir>
      </directories>
      <headers>
          <include>myExternalTestHeader</include>
      </headers>
   </category>
</categories>
Any folder you specify in place of myExternalTestDir is considered as a folder containing external tests and any folder you specify in place of myPSTestXUnitTestHeader is considered as a folder containing Polyspace Test xUnit tests (you typically do not need this since files using the Polyspace Test xUnit API are automatically detected). Likewise, any header you specify in place of myExternalTestHeader is treated as an external test header.

If a file indirectly includes a test header via another header, depending on how you generate the project, you might have to specify the second header in your file categorization XML.

  • If you generate a project from a build command, the indirect inclusion of the test header is automatically detected.

  • If you generate a project from a compilation database, explicitly specify the intermediate header in your file categorization XML as a test header.

Example: -categorization-config test_classification.xml

-toolchain toolchainName

Toolchain to set in the Polyspace Platform project. The toolchain must have been registered previously using a custom target registration file and must be a valid value for the option Compilation toolchain (Testing) (Polyspace Test).

To see the currently registered toolchains:

  • In the Polyspace Platform user interface, open the configuration of a project. Check the values for the option Compilation toolchain (Testing).

  • At the command line, list registered toolchains using the command:

    polyspace-test -manage-target-package -list Toolchain
    For more information, see polyspace-test -manage-target-package (Polyspace Test).

Note that if you do not specify this option, the polyspace-configure command tries to assign a compilation toolchain for testing based on the compiler command invoked in your build. The polyspace-configure command tries to match the compiler command invoked in your build with the compiler command set in the currently registered toolchains. The compiler command can be set in a toolchain in several ways. For example, in a GMake-based toolchain, a compiler command is typically included in the toolchain using this syntax:

toolchain = target.create('Toolchain', ...
                        'MakeToolType', 'GMake', ...
                        'Name', toolchainName, ...
                        'CCompiler', compileCommand)
For more information, see target.Toolchain (Embedded Coder).

OptionDescription
-compiler-config filePath

Path to compiler configuration XML file.

The file must be in a specific format. For guidance, see the existing configuration files in polyspaceroot\polyspace\configure\compiler_configuration\. For information on the contents of the file, see Create Polyspace Projects from Build Systems That Use Unsupported Compilers.

Example: -compiler-config myCompiler.xml

-no-project

Option to trace your build system without creating a Polyspace project and save the build trace information.

Use this option to save your build trace information for a later run of polyspace-configure (polyspaceConfigure) with the -no-build option.

This option is not compatible with -compilation-database.

-no-build

Option to create a Polyspace project using previously saved build trace information.

To use this option, you must have the build trace information saved from an earlier run of polyspace-configure (polyspaceConfigure) with the -no-project option.

If you use this option, you do not need to specify the buildCommand argument.

This option is ignored when you use -compilation-database.

-no-sources

Option to create a Polyspace options file that does not contain the source file specifications.

Use this option when you intend to specify the source files by other means. For instance, you can use this option when:

  • Running Polyspace on AUTOSAR-specific code.

    You want to create an options file that traces your build command for the compiler options:

    -output-options-file options.txt -no-sources
    You later append this options file when extracting source file names from ARXML specifications and running the subsequent Code Prover analysis with polyspace-autosar
    -extra-options-file options.txt

    See also Run Polyspace on AUTOSAR Code Using Build Command.

  • Running Polyspace in Eclipse™.

    Your source files are already specified in your Eclipse project. When running a Polyspace analysis, you want to specify an options file that has the compilation options only.

-extra-project-options polyspaceAnalysisOpts

Options that are used for subsequent Polyspace analysis.

Once a Polyspace project is created, you can change some of the default options in the project. Alternatively, you can pass these options when tracing your build command. The flag -extra-project-options allows you to pass additional options.

Specify multiple options in a space separated list, for instance "-allow-negative-operand-in-shift -stubbed-pointers-are-unsafe".

Suppose you have to set the option -stubbed-pointers-are-unsafe for every Polyspace project created. Instead of opening each project and setting the option, you can use this flag when creating the Polyspace project:

-extra-project-options "-stubbed-pointers-are-unsafe"

For the list of options available, see:

If you are creating an options file instead of a Polyspace project from your build command, do not use this flag. Instead, add the extra analysis options manually in the generated options file, in a separate options file, or at the command-line when you start the analysis.

-tmp-path folderPathPath of folder where temporary files are stored.
-build-trace filePath

Path of file where build information is stored. The default is ./polyspace_configure_build_trace.log.

Example: -build-trace ../build_info/trace.log

-log filePath Path of log file where the output of the polyspace-configure (polyspaceConfigure) command is stored. The use of this option does not suppress the console output.

-include-sources glob pattern

-exclude-sources glob pattern

Option to specify which source files polyspace-configure (polyspaceConfigure) includes in, or excludes from, the generated project. You can combine both options together.

A source file is included if the file path matches the glob pattern that you pass to -include-sources.

A source file is excluded if the file path matches the glob pattern that you pass to -exclude-sources.

-print-included-sources

-print-excluded-sources

Option to print the list of source files that polyspace-configure (polyspaceConfigure) includes in, or excludes from, the generated project. You can combine both options together. The output displays the full path of each file on a separate line.

Use this option to troubleshoot the glob patterns that you pass to -include-sources or -exclude-sources. You can see which files match the pattern that you pass to -include-sources or -exclude-sources.

-compiler-cache-path folderPath

Specify a folder path where polyspace-configure (polyspaceConfigure) looks for or stores the compiler cache files. If the folder does not exist, polyspace-configure (polyspaceConfigure) creates it.

By default, Polyspace looks for and stores compiler caches under these folder paths:

  • Windows

    %appdata%\Mathworks\R2026a\Polyspace

  • Linux

    ~/.matlab/R2026a/Polyspace

  • Mac

    ~/Library/Application Support/MathWorks/MATLAB/R2026a/Polyspace

-no-compiler-cache

Use this option if you do not want Polyspace to cache your compiler configuration information or to use an existing cache for your compiler configuration.

By default, the first time you run polyspace-configure (polyspaceConfigure) with a particular compiler configuration, Polyspace queries your compiler for the size of fundamental types, compiler macro definitions, and other compiler configuration information then caches this information. Polyspace reuses the cached information in subsequent runs of polyspace-configure (polyspaceConfigure) for builds that use the same compiler configuration.

-reset-compiler-cache-entryUse this option to query the compiler for the current configuration and to refresh the entry in the cache file that corresponds to this configuration. Other compiler configuration entries in the cache are not updated.
-clear-compiler-cache

Use this option to delete all compiler configurations stored in the cache file.

If you also specify a build command or -compilation-database, polyspace-configure (polyspaceConfigure) computes and caches the compiler configuration information of the current run, except if you specify -no-project or -no-compiler-cache.

-import-macro-definitions none | from-allowlist | from-source-tokens | from-compiler

Typically, you do not need to specify this option.

Polyspace attempts to automatically determine the best strategy to query your compiler for macro definitions in this order of priority:

  1. from-compiler — Polyspace uses native compiler options, such as gcc -dm -E, to obtain the compiler macro definitions. This strategy does not require Polyspace to trace your build and is available only for compilers that support listing macro definitions.

  2. from-source-tokens — Polyspace uses every non-keyword token in your source code to query your compiler for macro definitions. This strategy is available only if Polyspace can trace your build. The strategy is not available if you use option -compilation-database.

  3. from-allowlist — Polyspace uses an internal allow list to query the compiler for macro definitions.

If you prefer to specify macro definitions manually, use this option with the none flag and use option Preprocessor definitions (-D) to specify the macro definitions.

If the macro import strategy that Polyspace uses is not the one that you expect, try specifying this option manually to troubleshoot the issue.

-options-for-sources-delimiter delimCharacter

Specify the character to use as a separator between analysis options when Polyspace generates an options file associated with one source file using the option -options-for-sources. Typically, the option -options-for-sources uses the ; character (semicolon) as a separator between analysis options in the generated file.

See also -options-for-sources.

These options are primarily useful for debugging. Use the options if polyspace-configure (polyspaceConfigure) fails and MathWorks Technical Support asks you to use the option and provide the cached files. Starting R2020a, the option -easy-debug provides an easier way to provide debug information. See Contact Technical Support About Issues with Running Polyspace.

Polyspace ignores these options when you use -compilation-database.

OptionDescription

-no-cache

-cache-sources (default)

-cache-all-text

-cache-all-files

Option to perform one of the following:

  • -no-cache: Not create a cache

  • -cache-sources: Cache text files temporarily created during build for later use by polyspace-configure (polyspaceConfigure).

  • -cache-all-text: Cache all text files including sources and headers.

  • -cache-all-files: Cache all files including binaries.

Typically, you cache temporary files created by your build command to debug issues in tracing the command.

-cache-path folderPath

Path of folder where cache information is stored.

When tracing a Visual Studio build (devenv.exe), if you see the error:

path is too long
try using a shorter path for this option to work around the error.

Example: -cache-path ../cache

-keep-cache

-no-keep-cache (default)

Option to preserve or clean up cache information after polyspace-configure (polyspaceConfigure) completes execution.

If polyspace-configure (polyspaceConfigure) fails, you can provide this cache information to technical support for debugging purposes.

Version History

Introduced in R2013b

See Also

Topics