Configure Polyspace as You Code Plugin in Eclipse

Polyspace^® as You Code allows you to find bugs and coding rule violations while you work in your Eclipse™-based IDE.

After you install the Polyspace as You Code analysis engine and Eclipse plugin, configure the plugin so that a Polyspace analysis runs smoothly when you save your code or explicitly start an analysis. An analysis has run smoothly if results appear as you expect, either as source code markers with tooltips or in a list in the Polyspace Problems view.

To configure the Eclipse plugin, go to Window > Preferences and select the Polyspace as You Code node in the Preferences window. You can also open the Preferences window by pressing Alt+W+P. Under the Polyspace as You Code node, select:

Analysis to configure the analysis options for the projects
Baseline to configure the use of analysis results you download from Polyspace Access™ as a baseline

To save your configuration, click Apply and Close, or click Apply to save your changes and continue making edits to the configuration. To restore default configuration values, click Restore Defaults. All settings retain their current values when you reinstall the plugin.

Specify Polyspace as You Code Preferences

Setting	Description
Polyspace installation folder	Root folder of the Polyspace as You Code installation, for instance, `C:\Program Files\Polyspace as You Code\R2024b`.
Working directory	Folder where analysis results are stored. Each new run overwrites results of the previous run. The default working directory is stored under your system temporary folder, and typically contains `polyspace_eclipse` in the folder name: Windows^® — `%temp%` folder, for example `C:\Users\jsmith\AppData\Local\Temp` Linux^® — `/tmp` folder
Justification catalog	Specify the full file path of the justification catalog JSON file. Use this setting if your team or organization has a predefined set of comments that they use to justify results. You can store these justifications in a catalog file and associate one or more justifications with a specific result or result family. If you use the Polyspace syntax to annotate a result, the annotation comment is autofilled with the justifications that you store in the catalog for that result. For details of the Polyspace syntax, see Annotation Syntax Details (Polyspace Bug Finder). To create a justification catalog, see Use a Justification Catalog to Autocomplete Annotations in Polyspace as You Code plugins.
Debug Mode	Enable or disable debugging. (default) — The Console view shows only errors, warnings, and status messages such as messages about the start and end of analysis. — The Console view shows all debugging information. Enable this setting to troubleshoot issues with the Eclipse plugin.
Help Improve Polyspace as You Code	Enable or disable the sharing of user experience information with MathWorks^®. (default) — Polyspace shares user experience information with MathWorks and uses this information to improve the Eclipse plugin. — Polyspace does not share user experience information.
Port	Specify the port number that the Polyspace as You Code plugin uses on startup to establish an internal connection with the analysis engine. Use this setting if, for example, your machine is configured with a firewall and you want to specify an open port in the firewall. By default, port 0 is specified and Polyspace queries your system for an available port and uses whichever port your system returns. If you run multiple instances of Eclipse that access different workspaces, specify a different port for each instance. If you change this setting, you might need to restart your Eclipse IDE. If you let Polyspace obtain a port number automatically (port 0), the plugin might connect to a different port when you restart your Eclipse IDE and you might need to regenerate your build options.

Configure Analysis Settings

Specify which actions the plugin performs on save and configure how the plugin obtains information about your build system.

Polyspace analyzes only files that are part of the Eclipse workspace. To add a file to a workspace, you add it to a project in that workspace. Polyspace does not analyze files that are not in the workspace even if you add them to the Quality Monitoring list. If a file that you analyze includes a file that is not in the workspace, the Polyspace as You Code analysis runs, but does not report any findings for the included file.

Setting	Description
Add to Quality Monitoring list on save	Select how you add files to the Quality Monitoring list. Polyspace as You Code analyzes only files in this list. (default) — Polyspace adds the current file to the list on save (Ctrl + S). — Add files to the Quality Monitoring list manually. To add a file manually, right-click the file in the editor or the Project Explorer view.
Start analysis on save	Select when Polyspace as You Code runs on files that are in the Quality Monitoring list. — Polyspace as You Code runs each time you save your code (Ctrl + S). (default) — Run the analysis manually. Right-click the source code or a file in the Project Explorer and select Run Polyspace Analysis.
Perform analysis in fast-mode	Toggle on or off fast analysis mode. This option is disabled by default. Fast analysis decreases the duration of your Polyspace as You Code analysis by checking only for specific types of issues. This option enables only checkers for issues that are syntactic and do not require abstraction or data flow calculations. Polyspace excludes checkers that are not syntactic or require abstraction of the code from a fast analysis. These exclusions are in addition to the Checkers Deactivated in Polyspace as You Code Analysis. Use fast analysis to iteratively identify and address bugs that are smaller in scope and addressable earlier in the development process. To take full advantage of the defects that Polyspace as You Code can find, use fast analysis as a precursor to a full Polyspace as You Code analysis of your code. The icon shows next to files you analyze in fast-mode. Enabling fast-mode affects all files in the Quality Monitoring list. The Configuration view shows `Fast analysis mode: On` when the option is enabled. You can toggle the option on or off from this pane by clicking the option.
Analysis Setup	Select between manual setup and a script. `Manual setup` (default) — Set up Polyspace as You Code through extension settings. Specify build-related and other options in the Analysis Setup: Manual setup group of settings. `Script` — Run a script each time you save your code (or right-click a source file and select Run Polyspace Analysis). Specify the path of the script file in the Analysis Setup: Script section.

Set Up Analysis by Using Script

Run a script each time you save your code or you explicitly run an analysis.

Setting Description

Setting	Description
Script file	Use this setting if you choose `Script` for the Analysis Setup setting. Use a script if, for instance, you switch between files from components that have different build configurations or you use a custom tool to set up your build environment. Enter the full path to a script that runs each time you start a Polyspace as You Code analysis. You can write the script in any language. On Windows, the extension supports scripting languages only for scripts that are executable from the Command Prompt window. The plugin passes these setting values as parameters to the script: Path of the current file as the first argument Path of the Working Directory folder as the second argument. Path of the Polyspace Installation folder as the third argument. Optionally, the plugin passes these additional settings to the script if you specify them: The path of the options file from the setting Other Analysis Options File, prefixed by `-options-file`. For instance, if you specify the file `C:\polyspace\myOpts.txt`, the plugin passes `-options-file C:\polyspace\myOpts.txt` as a parameter. The path of the checkers activation XML file from the setting Checkers File, prefixed by `-checkers-activation-file`. For instance, if you specify the file `C:\polyspace\myCheckers.xml`, the extension passes `-checkers-activation-file C:\polyspace\myCheckers.xml` as a parameter. Any additional parameters you specify with the setting Script File Arguments.
Script File Arguments	Use this setting to specify additional parameters that the plugin passes to the script when you run an analysis. For example, you might want to run a command on preprocessed files to work around a compilation error. See `Command/script to apply to preprocessed files (-post-preprocessing-command)` (Polyspace Bug Finder).

Script file

Use this setting if you choose Script for the Analysis Setup setting.

Use a script if, for instance, you switch between files from components that have different build configurations or you use a custom tool to set up your build environment.

Enter the full path to a script that runs each time you start a Polyspace as You Code analysis. You can write the script in any language. On Windows, the extension supports scripting languages only for scripts that are executable from the Command Prompt window.

The plugin passes these setting values as parameters to the script:

Path of the current file as the first argument
Path of the Working Directory folder as the second argument.
Path of the Polyspace Installation folder as the third argument.

Optionally, the plugin passes these additional settings to the script if you specify them:

The path of the options file from the setting Other Analysis Options File, prefixed by -options-file. For instance, if you specify the file C:\polyspace\myOpts.txt, the plugin passes -options-file C:\polyspace\myOpts.txt as a parameter.
The path of the checkers activation XML file from the setting Checkers File, prefixed by -checkers-activation-file. For instance, if you specify the file C:\polyspace\myCheckers.xml, the extension passes -checkers-activation-file C:\polyspace\myCheckers.xml as a parameter.
Any additional parameters you specify with the setting Script File Arguments.

Script File Arguments

Use this setting to specify additional parameters that the plugin passes to the script when you run an analysis. For example, you might want to run a command on preprocessed files to work around a compilation error. See Command/script to apply to preprocessed files (-post-preprocessing-command) (Polyspace Bug Finder).

For example, this Windows batch script assigns the paths of the source file (SOURCES), results folder (RESULTS_FOLDER), and the installation folder (INSTALL_DIR), and assigns any additional parameters to OTHER_PARAMS. The script then analyzes the current file, using any analysis options stored in OTHER_PARAMS, and imports the review information from a previously downloaded baseline:

@echo off

set SOURCES=%1
set RESULTS_FOLDER=%2
set INSTALL_DIR=%3
set ANALYZE=%INSTALL_DIR%\polyspace\bin\polyspace-bug-finder-access.exe
set BASELINE_DIR=%RESULTS_FOLDER%\..\..\..\baseline

set OTHER_PARAMS=
REM loop through additional parameters if any
:loop
    if [%4] == [] (
    goto :done)
    set OTHER_PARAMS=%OTHER_PARAMS% %4
    shift
    goto :loop
:done

"%ANALYZE%" -sources %SOURCES% -import-comments %BASELINE_DIR%^
 -results-dir %RESULTS_FOLDER% %OTHER_PARAMS% 
IF %ERRORLEVEL% NEQ 0 EXIT 1

For more on downloading a baseline and importing its review information at the command line, see Set Baseline Polyspace as You Code Results on Command Line.

If you enable this setting, the plugin ignores the Analysis Setup: Manual setup and Baseline settings.

Note

The Polyspace as You Code plugin does not check the exit status of the commands in your script. Make sure your script checks exit codes (for instance, by using %ERRORLEVEL%) and returns a meaningful exit status.

Typically, the Polyspace binaries return 0 on success and a non zero value on failure.

Set Up Analysis Manually

Setting	Description
Build	`Build options file not required` (default) You do not have to specify Polyspace options related to your build configuration. This is a basic option for simple projects. More... The analysis uses the default Polyspace build options. So that the analysis runs without errors, you typically provide Polyspace as You Code with the specificities of your build configuration. `Get from build command` The analysis traces the build command that you specify and generates a build options file. More... Specify the build command in setting Build Command, for example `make -B` and click in the Configuration view of the Polyspace as You Code perspective. See Get Build Configuration from Build Command. `Get from Eclipse C/C++ project` The analysis extracts the build configuration from the Eclipse project and generates a build options file. If your workspace contains multiple projects, Polyspace extracts the build options for all the projects and then applies only the relevant options when you analyze a file in a specific project. See Get Build Configuration from Eclipse Project. `Get from JSON Compilation Database file` The analysis extracts the build configuration from the JSON compilation database that you specify and generates a build options file. See Get Build Configuration from JSON Compilation Database. More... Specify the full path to the JSON file (typically named `compile_commands.json`) in the JSON Compilation Database file setting. If you use a build system generator such as CMake, you can follow this approach to set up Polyspace as You Code. For instance, if you use CMake projects in Eclipse, CMake also allows you to generate a JSON compilation database with the commands used for building the project. You can then provide the compilation database to this setting. For an example of how to generate this JSON file, see Create Polyspace Options File from JSON Compilation Database (Polyspace Bug Finder). `Get from Polyspace build options file` When you select this setting, you provide an options file that you generate or fill in manually with all the necessary build options. Specify the full path of the options file in the Polyspace Build Options File setting.
Build Command	Specify the build command name exactly as you would enter on a command-line terminal or console. Use a build command that performs a complete build of all files in your workspace and not an incremental build. Fill in this setting if you select `Get from build command` from the Build menu. See Get Build Configuration from Build Command.
JSON Compilation Database file	Specify the full path to a database file (typically named `compile_commands.json`). Use a build command that performs a complete build of all files in your workspace and not an incremental build. Fill in this setting if you select `Get from JSON Compilation Database file` from the Build menu. See Create Polyspace Options File from JSON Compilation Database (Polyspace Bug Finder).
Polyspace Build Options File	Specify the full path to a Polyspace build options file. The options file is a text file with one Polyspace analysis option per line. Fill in this setting if you select `Get from Polyspace build options file` from the Build menu. See Options Files for Polyspace Analysis (Polyspace Bug Finder).
Checkers file	Path to a checkers configuration file. To create this file, click in the Configuration view of the Polyspace as You Code perspective. Select the checkers that you want to enable and save the file. If you set the Analysis Setup setting to `Script`, the plugin passes the checkers configuration file path prefixed with `-checkers-activation-file` as a parameter to the script. See also Configure Checkers for Polyspace as You Code in Eclipse.
Other Analysis Options	Path to an options file. The options file contains one Polyspace analysis option per line. For example: -D _WIN32 -termination-functions exit_handler You typically do not need to specify additional options in an options file. However, in some situations, you might want to use an options file. For instance, if you want to manually specify Polyspace options related to your build command, select `Build options file not required` for the Build setting and enter the options in an options file. If you set the Analysis Setup setting to `Script`, the plugin passes the options file path prefixed with `-options-file` as a parameter to the script. See also Options Files for Polyspace Analysis (Polyspace Bug Finder).

Configure Baseline Settings

Use these settings to select whether you import review information from a baseline run into your analysis and to configure the connection to a Polyspace Access Server from which you download the baseline.

Setting	Description
Show Baseline information	Enable or disable the use of information from the baseline run: `Show local findings only` (default) When you run an analysis, Polyspace does not use information from the baseline run. You see only local findings in the Polyspace Problems pane. `Show local findings and baseline info` When you run an analysis, Polyspace imports review information from the baseline run. Results that are already justified in the baseline run are suppressed in the Polyspace Problems pane. `Show new findings only` When you run an analysis, Polyspace imports review information from the baseline. Results that are already present in the baseline run are suppressed in the Polyspace Problems pane. Use this setting to focus only on new findings. See also Set Baseline Polyspace as You Code Results in Eclipse.
Polyspace Access URL	URL of the Polyspace Access instance from which you get a baseline. After you obtain a baseline from Polyspace Access, subsequent runs of Polyspace as You Code allow you to distinguish between new results and results that are present in existing code. See also Set Baseline Polyspace as You Code Results in Eclipse.
Polyspace Access Login	Specify the username that you use to log in to Polyspace Access. Later, when you click the Download Baseline icon in the Baseline view of the Polyspace as You Code perspective, you are prompted for the password that corresponds to this username.
Project path	Path of the project in the Polyspace Access Project Explorer that you use as a baseline.