polyspaceConfigure

Create Polyspace project from your build system at the MATLAB command line

Syntax

polyspaceConfigure buildCommand

polyspaceConfigure -option value buildCommand

Description

polyspaceConfigure buildCommand traces your build system and creates a Polyspace^® project with information gathered from your build system. You can run an analysis on a Polyspace project only in the user interface of the Polyspace desktop products.

polyspaceConfigure -option value buildCommand traces your build system and uses -option value to modify the default operation of polyspaceConfigure. Specify the modifiers before buildCommand, otherwise they are considered as options in the build command itself.

Note

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

Examples

Create Polyspace Project from Makefile

This example shows how to create a Polyspace project if you use the command make targetName buildOptions to build your source code. The example creates a Polyspace project that can be opened only in the user interface of the Polyspace desktop products.

Create a Polyspace project specifying a unique project name. Use the -B or -W makefileName option with make so that the all prerequisite targets in the makefile are remade.

polyspaceConfigure  -prog myProject ...
          make -B targetName buildOptions

Open the Polyspace project in the Project Browser.

polyspaceBugFinder('myProject.psprj')

Create Projects That Have Different Source Files from Same Build Trace

This example shows how to create different Polyspace projects from the same trace of your build system. You can specify which source files to include for each project. The example creates a Polyspace project that can be opened only in the user interface of the Polyspace desktop products.

Trace your build system without creating a Polyspace project by specifying the option -no-project. To ensure that all the prerequisite targets in your makefile are remade, use the appropriate make build command option, for instance -B.

polyspaceConfigure -no-project make -B;

polyspace-configure stores the cache information and the build trace in default locations inside the current folder. To store the cache information and build trace in a different location, specify the options -cache-path and -build-trace.

Generate Polyspace projects by using the build trace information from the previous step. Specify a project name and use the -include-sources or -exclude-sources option to select which files to include for each project.

polyspaceConfigure -no-build -prog myProject ...
-include-sources "glob_pattern";

glob_pattern is a glob pattern that corresponds to folders or files you filter in or out of your project. To ensure the shell does not expand the glob patterns you pass to polysapce-configure, enclose them in double quotes.For more information on the supported syntax for glob patterns, see polyspace-configure Source Files Selection Syntax.

If you specified the options -build-trace and -cache-path in the previous step, specify them again.

Delete the trace file and cache folder.

rmdir('polyspace_configure_cache', 's');
delete polyspace_configure_built_trace;
 

If you used the options -build-trace and -cache-path, use the paths and file names from those options.

Run Command-Line Polyspace Analysis from Makefile

This example shows how to run Polyspace analysis if you use a build command such as make targetName buildOptions to build your source code. In this example, you use polyspaceConfigure to trace your build system but do not create a Polyspace project. Instead you create an options file that you can use to run Polyspace analysis from the command-line.

Create a Polyspace options file specifying the -output-options-file command. Use the -B or -W makefileName option with make so that all prerequisite targets in the makefile are remade.

polyspaceConfigure -output-options-file ... 
         myOptions make -B targetName buildOptions

Use the options file that you created to run a Polyspace analysis at the command line:

polyspaceBugFinder -options-file myOptions

Input Arguments

buildCommand — Command for building source code

build command

Build command specified exactly as you use to build your source code.

Example: make -B, make -W makefileName

-option value — Options for changing default operation of polyspaceConfigure

single option starting with -, followed by argument | multiple space-separated option-argument pairs

Basic Options

Option	Argument	Description
-prog	Project name	Project name that appears in the Polyspace user interface. The default is polyspace. If you do not use the option -output-project, the -prog argument also sets the project name. Example: -prog myProject creates a project that has the name myProject in the user interface. If you do not use the option -output-project, the project name is also myProject.psrprj.
-author	Author name	Name of project author. Example: -author jsmith
-output-project	Path	Project file name and location for saving project. The default is the file polyspace.psprj in the current folder. Example: -output-project ../myProjects/project1 creates a project project1.psprj in the folder with the relative path ../myProjects/.
-output-options-file	File name	Option to create a Polyspace analysis options file. Use this file for command-line analysis using one of these commands: polyspace-bug-finder polyspace-code-prover polyspace-bug-finder-server polyspace-code-prover-server polyspace-bug-finder-access
-allow-build-error	None	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 is ignored when you use -compilation-database.
-allow-overwrite	None	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	None	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. These options are ignored if they are used in combination with -easy-debug.
-help	None	Option to display the full list of polyspace-configure (polyspaceConfigure) commands
-debug	None	Option to store debug information for use by MathWorks® technical support. This option has been superseded by the option -easy-debug.
-easy-debug	Path	Option to store debug information for use by MathWorks technical support. After a polyspace-configure (polyspaceConfigure) run, the path provided 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.

Options to Create Multiple Modules

These options are not compatible with -compilation-database.

Option	Argument	Description
-module	None	Option to create a separate options file for each binary created in build system. You can only create separate options files for different binaries. You cannot create multiple modules in a Polyspace project (for running in the Polyspace user interface). Use this option only for build systems that use GNU® and Visual C++® compilers. See also Modularize Polyspace Analysis by Using Build Command.
-output-options-path	Path name	Location where generated options files are saved. Use this option together with the option -module. The options files are named after the binaries created in the build system.

Advanced Options

Option	Argument	Description
-compilation-database	Path and file name	Location and name of JSON compilation database (JSON CDB) file. You generate this file from your build system, for instance by using the flag -DCMAKE_EXPORT_COMPILE_COMMANDS=1 with cmake. The file contains compiler calls for all the translation units in you projects. For more information, see JSON Compilation Database. polyspace-configure uses the content of this file to get information about your build system. The extracted compiler paths in the JSON CDB must be accessible from the path where you run polyspace-configure. You do not specify a build command when you use this option. The build systems and compilers support the generation of a JSON CDB: CMake Bazel Clang Ninja Qbs waf This option is not compatible with -no-project and with the options to create multiple modules. The cache control options, -allow-build-error, and -no-build are ignored when you use this option.
-compiler-config	Path and file name	Location and name of compiler configuration 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 Compiler Not Supported for Project Creation from Build Systems. Example: -compiler-configuration myCompiler.xml
-no-project	None	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	None	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	None	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 (Polyspace Code Prover) -extra-options-file options.txt See also Run Polyspace on AUTOSAR Code Using Build Command (Polyspace Code Prover). 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	Options to use for subsequent Polyspace analysis. For instance, "-stubbed-pointers-are-unsafe".	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: Analysis Options in Polyspace Bug Finder If you are creating an options file instead of a Polyspace project from your build command, do not use this flag.
-tmp-path	Path	Location of folder where temporary files are stored.
-build-trace	Path and file name	Location and name of file where build information is stored. The default is ./polyspace_configure_build_trace.log. Example: -build-trace ../build_info/trace.log
-include-sources -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	None	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	Folder path	Specify a folder path where polyspace-configure looks for or stores the compiler cache files. If the folder does not exist, polyspace-configure creates it. By default, Polyspace looks for and stores compiler caches under these folder paths: Windows® %appdata%\Mathworks\R20xxY\Polyspace Linux® ~/.matlab/R20xxY/Polyspace Mac ~/Library/Application Support/MathWorks/MATLAB/R20xxY/Polyspace R20xxY is the release version of your Polyspace product, for instance R2020b.
-no-compiler-cache	None	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 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 for builds that use the same compiler configuration.
-reset-compiler-cache-entry	None	Use 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	None	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 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-whitelist from-source-tokens	Use this option to specify how polyspace-configure queries the compiler for macro definitions. You can specify: none — Polyspace does not query the compiler for macro definitions. You must provide the macro definitions manually. from-whitelist — Polyspace uses an internal white list to query the compiler for macro definitions. Polyspace uses the white list by default when you use the option -compilation-database. from-source-tokens (default, except if you use -compilation-database ) — Polyspace uses every non-keyword token in your source code to query your compiler for macro definitions.
-options-for-sources-delimiter	A single character	Specify an option separator to use when multiple analysis options are associated with one source file using the -options-for-sources option. Typically, the -options-for-sources option uses a semicolon as separator. See also -options-for-sources.

Cache Control Options

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.

These options are ignored when you use -compilation-database.

Option	Argument	Description
-no-cache -cache-sources (default) -cache-all-text -cache-all-files	None	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	Path	Location 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)	None	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.