padv.builtin.task.AnalyzeModelCode Class

Namespace: padv.builtin.task
Superclasses: padv.Task

Task for checking coding standards or proving code quality with Polyspace

expand all in page

Description

The padv.builtin.task.AnalyzeModelCode class provides a task that you can configure to either:

  • Check coding standards by using Polyspace® Bug Finder™

  • Prove code quality by using Polyspace Code Prover™

You configure which operation the task performs by specifying the VerificationMode property. If you want to use both Bug Finder and Code Prover, add two instances of AnalyzeModelCode to the process model as shown in Add Both Bug Finder and Code Prover Tasks to Process. If you have a Polyspace Access™ license, you can also configure the task to upload your results. For more information, see Upload Results to Polyspace Access.

You can add the task to your process model by using the method addTask. After you add the task, you can run the task from the Process Advisor app or by using the function runprocess.

To view the source code for this built-in task, in the MATLAB® Command Window, enter: 

open padv.builtin.task.AnalyzeModelCode

The padv.builtin.task.AnalyzeModelCode class is a handle class.

Note

Polyspace Bug Finder, Polyspace Code Prover, and this task are not supported on Apple silicon macOS.

Creation

Description

task = padv.builtin.task.AnalyzeModelCode() creates a task for checking coding standards with Polyspace Bug Finder.

example

task = padv.builtin.task.AnalyzeModelCode(PredecessorTask=PredecessorTask) specifies that the task can only execute after the specified predecessor task runs.

When you specify a predecessor task, you must also specify a dependsOn relationship between the AnalyzeModelCode task and the predecessor task in your process model.

task = padv.builtin.task.AnalyzeModelCode(___,Name=Value) sets certain properties using one or more name-value arguments.

For example, task = padv.builtin.task.AnalyzeModelCode(Name = "MyAnalyzeModelCode") creates a task with the specified name.

You can use this syntax to set property values for TreatAsRefModel, Name, Title, DescriptionText, DescriptionCSH, IterationQuery, InputQueries, InputDependencyQuery, LaunchToolAction, and LaunchToolText.

The class also has other properties, but you cannot set those properties during task creation.

example

Input Arguments

expand all

Task that must run before this task, specified as either the:

  • Task name, specified as a string.

  • Task instance, specified as a padv.Task object.

By default, AnalyzeModelCode requires outputs from a task named "padv.builtin.task.GenerateCode". If your code generation task has a different task name, you can use the PredecessorTask argument to provide the task name or instance to the AnalyzeModelCode task.

When you specify a predecessor task, you must also specify in the process model that the AnalyzeModelCode task dependsOn the predecessor task.

Example: "MyCodeGenerationTask"

Properties

expand all

The AnalyzeModelCode class inherits properties from padv.Task. The properties listed in Specialized Inherited Properties are padv.Task properties that the AnalyzeModelCode task overrides.

The task also has properties for specifying:

Specialized Inherited Properties

Unique identifier for task in process, specified as a string.

Example: "MyAnalyzeModelCode"

Data Types: string

Human-readable name that appears in Process Advisor app, specified as a string.

Example: "My Analyze Model Code Task"

Data Types: string

Task description, specified as a string.

When you point to a task in Process Advisor and click the information icon, the tooltip shows the task description.

Example: "This task analyzes generated model code."

Data Types: string

Path to task documentation, specified as a string.

When you point to a task in Process Advisor, click the ellipsis (...), and click Help, Process Advisor opens the task documentation.

Example: fullfile(pwd,"taskHelpFiles","myTaskDocumentation.pdf")

Data Types: string

Type of artifact, specified as one or more of the values listed in this table. To specify multiple values, use an array.

CategoryArtifact TypeDescription

MATLAB

"m_class"MATLAB class
"m_file"MATLAB file
"m_func"MATLAB function
"m_method"MATLAB class method
"m_property"MATLAB class property

Model Advisor

"ma_config_file"Model Advisor configuration file
"ma_justification_file"Model Advisor justification file

Model Finder

"mf_database"Model Finder database file

Process Advisor

"padv_dep_artifacts"

Related artifacts that current artifact depends on

"padv_output_file"

Process Advisor output file

Project

"project"Current project file

Requirements

"mwreq_file"Requirement file (since R2024b)
"mwreq_item"Requirement (since R2024b)

"sl_req"

Requirement (for R2024a and earlier)
"sl_req_file"Requirement file (for R2024a and earlier)
"sl_req_table"Requirements Table

Stateflow®

"sf_chart"Stateflow chart
"sf_graphical_fcn"Stateflow graphical function
"sf_group"Stateflow group
"sf_state"Stateflow state
"sf_state_transition_chart"Stateflow state transition chart
"sf_truth_table"Stateflow truth table

Simulink®

"sl_block_diagram"Block diagram
"sl_data_dictionary_file"Data dictionary file
"sl_embedded_matlab_fcn"MATLAB function
"sl_block_diagram"Block diagram
"sl_library_file"Library file
"sl_model_file"Simulink model file
"sl_protected_model_file"Protected Simulink model file
"sl_subsystem"Subsystem
"sl_subsystem_file"Subsystem file

System Composer™

"zc_block_diagram"System Composer architecture
"zc_component"System Composer architecture component
"zc_file"System Composer architecture file
Tests"harness_info_file"Harness info file
"sl_harness_block_diagram"Harness block diagram
"sl_harness_file"Test harness file
"sl_test_case"Simulink Test™ case
"sl_test_case_result"Simulink Test case result
"sl_test_file"Simulink Test file
"sl_test_iteration"Simulink Test iteration
"sl_test_iteration_result"Simulink Test iteration result
"sl_test_report_file"Simulink Test result report
"sl_test_result_file"Simulink Test result file
"sl_test_resultset"Simulink Test result set
"sl_test_seq"Test Sequence
"sl_test_suite"Simulink Test suite
"sl_test_suite_result"Simulink Test suite result

Example: "sl_model_file"

Example: ["sl_model_file "zc_file"]

Query that finds the artifacts that the task iterates over, specified as a padv.Query object or the name of a padv.Query object. When you specify IterationQuery, the task runs one time for each artifact returned by the query. In the Process Advisor app, the artifacts returned by IterationQuery appear under task title.

By default, this task runs on the generated model code, iterating over either each model in the project or the project itself. If a model does not have generated code, the task skips the model and displays a warning message.

For more information about task iterations, see Overview of Process Model.

Example: padv.builtin.query.FindProjectFile

List of licenses that the task requires, specified as a string.

Data Types: string

Function that launches a tool, specified as the function handle.

When you point to a task in the Process Advisor app, you can click the ellipsis (...) to see more options. For built-in tasks, you have the option to launch a tool associated with the task.

For the task AnalyzeModelCode, you can launch the Polyspace Code Verifier app.

Data Types: function_handle

Description of the action that the LaunchToolAction property performs, specified as a string.

Data Types: string

Inputs to the task, specified as:

  • a padv.Query object

  • the name of padv.Query object

  • an array of padv.Query objects

  • an array of names of padv.Query objects

By default, if the task iterates over the project file and does not specify input queries, the task gets the outputs from the predecessor task, PredecessorTask, and uses those as task inputs. If the task iterates over model files, the task uses the built-in query padv.builtin.query.GetIterationArtifact to use the models as task inputs.

Query that finds artifact dependencies for task inputs, specified as a padv.Query object or the name of a padv.Query object.

The build system runs the query specified by InputDependencyQuery to find the dependencies for the task inputs, since those dependencies can impact if task results are up-to-date.

For more information, see Overview of Process Model.

Example: padv.builtin.query.GetDependentArtifacts

General Polyspace Options

Treat code as code generated by reference model, specified as either "", true, or false.

By default, the task automatically identifies whether a model is a top model or a reference model before analyzing the model code. But you can specify TreatAsRefModel as true or false if you want to override the behavior and only analyze reference model code or top model code.

Example: true

Data Types: logical

Directory where build system stores results from analyzing model code, specified as a string.

Data Types: string

Reports output by task, specified as a string.

Data Types: string

Path to reports output by task, specified as a string.

Data Types: string

Format of output reports, specified as either:

  • "PDF" — PDF file.

  • "HTML" — HTML report.

  • "WORD" — Microsoft® Word document.

  • Combination of these formats, specified as a comma-separate list. For example, "PDF,HTML" generates multiple reports. One in PDF format and one in HTML format.

Example: "HTML"

Data Types: string

Names of output reports, specified as a string.

Data Types: string

Polyspace mode, specified as either:

  • "BugFinder" — Quickly analyze generated model code for many types of run-time defects, coding standards, and code metrics by using Polyspace Bug Finder.

  • "CodeProver" — Check every operation in your code for a set of possible run-time errors and try to prove the absence of the error for all execution paths by using Polyspace Code Prover.

You can use both Bug Finder and Code Prover in your software development process, but each task instance must have a unique Name and you need to configure the tasks to prevent the tasks from overwriting each other.

For information on the differences between Bug Finder and Code Prover, see Differences Between Polyspace Bug Finder and Polyspace Code Prover (Polyspace Bug Finder).

Example: "CodeProver"

Advanced Polyspace Analysis Options

Option to run analysis on server (-batch), specified as a numeric or logical 1 (true) or 0 (false).

Example: true

Data Types: logical

Specify cluster or job scheduler (-scheduler), specified as a string.

Example: "NodeHost"

Data Types: string

Advanced Polyspace Project Options

Save Polyspace project file after analyzing model code, specified as a numeric or logical 1 (true) or 0 (false).

Example: false

Data Types: logical

Polyspace project file path, specified as a string.

The built-in tasks use tokens, like $ITERATIONARTIFACT$, as placeholders for dynamic path resolution during run-time. For more information, see Dynamically Resolve Paths with Tokens.

Data Types: string

Advanced Polyspace Access Configuration Options

Enable task to upload analysis results to Polyspace Access, specified as a numeric or logical 1 (true) or 0 (false).

Note

If you specify PsAccessEnable as true, you must also specify values for the other Polyspace Access Configuration Options. For information, see Upload Results to Polyspace Access.

Example: true

Data Types: logical

Polyspace Access machine host name, specified as a string. You can find the host name in the URL of the Polyspace Access interface, for example, https://hostname:port/metrics/index.html.

Example: my-company-server

Data Types: string

Polyspace Access port, specified as a string. You can find the port number in the URL of the Polyspace Access interface, for example, https://hostname:portNumber/metrics/index.html.

Example: "9999"

Data Types: string

HTTP protocol used to access Polyspace Access, specified as either "http" or "https".

Example: "http"

Full path to text file where you store your login credentials for Polyspace Access, specified as a string.

A credentials file is useful if you do not want to store your credentials in your process model. For information on how to create a credentials file, see Encrypt Password and Store Login Options in a Variable (Polyspace Access).

Alternatively, you can specify an API key (PsAccessApiKey) or a username and password (PsAccessUserName and PsAccessEncryptedPassword) to pass your credentials to Polyspace Access.

Example: "C:\Users\username\myCredentials.txt"

Data Types: string

API key for Polyspace Access, specified as a string.

For information on API keys and how to assign an API key to a user, see login options (Polyspace Access).

Alternatively, you can use a credentials file (PsAccessCredentialsFile) or a username and password (PsAccessUserName and PsAccessEncryptedPassword) to pass your credentials to Polyspace Access.

Example: "keyValue123"

Data Types: string

Username for Polyspace Access, specified as a string.

For information on login credentials, see login options (Polyspace Access).

Alternatively, you can use a credentials file (PsAccessCredentialsFile) or an API key (PsAccessApiKey) to pass your credentials to Polyspace Access.

Data Types: string

Password for Polyspace Access, specified as a string.

For information on login credentials, see login options (Polyspace Access).

Alternatively, you can use a credentials file (PsAccessCredentialsFile) or an API key (PsAccessApiKey) to pass your credentials to Polyspace Access.

Data Types: string

Path of parent folder in Polyspace Access explorer under which you store uploaded results, specified as a string.

For more information, see upload options (Polyspace Access).

Example: "public/myProject"

Data Types: string

Name of uploaded results in Polyspace Access explorer, specified as a string.

The built-in tasks use tokens, like $ITERATIONARTIFACT$, as placeholders for dynamic path resolution during run-time. For more information, see Dynamically Resolve Paths with Tokens.

For more information, see upload options (Polyspace Access).

Example: "$ITERATIONARTIFACT$_CodingStandards"

Data Types: string

Methods

expand all

Examples

collapse all

Add a task that can quickly analyze generated model code for many types of run-time defects, coding standards, and code metrics by using Polyspace Bug Finder.

Open the process model for your project. If you do not have a process model, open the Process Advisor app to automatically create a process model.

In the process model file, add the AnalyzeModelCode task to your process model by using the addTask method. By default, the AnalyzeModelCode task performs Bug Finder analysis.

psbfTask = pm.addTask(padv.builtin.task.AnalyzeModelCode);

You can reconfigure the task behavior by using the task properties. For example, to use a custom configuration from a Polyspace project (.psprj) file and customize the task outputs:

psbfTask.addInputQueries(padv.builtin.query.FindFileWithAddress( ...
    Type='ps_prj_file',Path=fullfile('tools','CodingRulesOnly_config.psprj')));
psbfTask.ResultDir = string(fullfile('$DEFAULTOUTPUTDIR$', ...
    '$ITERATIONARTIFACT$','coding_standards'));
psbfTask.Reports = "CodingStandards";
psbfTask.ReportPath = string(fullfile('$DEFAULTOUTPUTDIR$', ...
    '$ITERATIONARTIFACT$','coding_standards'));
psbfTask.ReportNames = "$ITERATIONARTIFACT$_CodingStandards";
psbfTask.ReportFormat = "PDF";

The AnalyzeModelCode task requires outputs from the GenerateCode task. Specify this dependency in your process model by using the dependsOn method.

To make sure that you run your tasks using the built-in task GenerateCode before you add the task, you can use conditional logic in your process model. For example:

includeGenerateCodeTask = true;
includeAnalyzeModelCode = true && exist('polyspaceroot','file');

%% Generate Code
% Tools required: Embedded Coder
% By default, generating code for each model in the project
if includeGenerateCodeTask
    codegenTask = pm.addTask(padv.builtin.task.GenerateCode);
    % ... Optionally specify task property values
end

%% Check coding standards 
% Tools required: Polyspace Bug Finder
if includeGenerateCodeTask && includeAnalyzeModelCode
    psbfTask = pm.addTask(padv.builtin.task.AnalyzeModelCode);
    % ... Optionally specify task property values
end

% Set task dependencies
if includeGenerateCodeTask && includeAnalyzeModelCode
    psbfTask.dependsOn(codegenTask);
end
This code also makes sure that Polyspace is installed and integrated by checking if the Polyspace installation folder (polyspaceroot) exists before adding the task to the process model.

Add a task that can check every operation in your code for a set of possible run-time errors and try to prove the absence of the error for all execution paths by using Polyspace Code Prover.

Open the process model for your project.

In the process model file, add the AnalyzeModelCode task to your process model by using the addTask function. To have the task use Polyspace Code Prover, specify the VerificationMode as "CodeProver".

pscpTask = pm.addTask(padv.builtin.task.AnalyzeModelCode(Name="ProveCodeQuality"));
    pscpTask.Title = "Prove Code Quality";
    pscpTask.VerificationMode = "CodeProver";

This code also specifies values for the Name and Title properties since the default task name and title refer to Bug Finder analysis. You can use the other task properties to specify the report templates and other task settings.

You can reconfigure the task behavior by using the task properties. For example:

pscpTask.ResultDir = string(fullfile('$DEFAULTOUTPUTDIR$', ...
    '$ITERATIONARTIFACT$','code_quality'));
pscpTask.Reports = ["Developer", "CallHierarchy", "VariableAccess"];
pscpTask.ReportPath = string(fullfile('$DEFAULTOUTPUTDIR$', ...
    '$ITERATIONARTIFACT$','code_quality'));
pscpTask.ReportNames = [...
    "$ITERATIONARTIFACT$_Developer", ...
    "$ITERATIONARTIFACT$_CallHierarchy", ...
    "$ITERATIONARTIFACT$_VariableAccess"];
pscpTask.ReportFormat = "PDF";

The AnalyzeModelCode task requires outputs from the GenerateCode task. Specify this dependency in your process model by using the dependsOn method.

To make sure that you run your tasks using the built-in task GenerateCode before you add the task, you can use conditional logic in your process model. For example:

includeGenerateCodeTask = true;
includeProveCodeQuality = true && (~isempty(ver('pscodeprover')) || ~isempty(ver('pscodeproverserver')));

%% Generate Code
% Tools required: Embedded Coder
% By default, generating code for each model in the project
if includeGenerateCodeTask
    codegenTask = pm.addTask(padv.builtin.task.GenerateCode);
    % ... Optionally specify task property values
end

%% Prove Code Quality 
% Tools required: Polyspace Code Prover
if includeGenerateCodeTask && includeProveCodeQuality
    pscpTask = pm.addTask(padv.builtin.task.AnalyzeModelCode(Name="ProveCodeQuality"));
    pscpTask.Title = "Prove Code Quality";
    pscpTask.VerificationMode = "CodeProver";
    % ... Optionally specify task property values
end

% Set task dependencies
if includeGenerateCodeTask && includeProveCodeQuality
    pscpTask.dependsOn(codegenTask);
end
This code also makes sure that Polyspace Code Prover is available before adding the task to the process model.

You can use both Bug Finder and Code Prover in your software development workflow. Both Polyspace Bug Finder and Polyspace Code Prover detect run-time errors through static analysis.

  • Bug Finder quickly analyzes your code and detects many types of defects.

  • Code Prover checks every operation in your code for a set of possible run-time errors and try to prove the absence of the error for all execution paths.

To include both a Bug Finder task and a Code Prover task in your process model, you must add two separate instances of the AnalyzeModelCode task to the process model. Each instance needs a unique value for the Name property. Use the VerificationMode property to specify whether the task uses Bug Finder (default) or Code Prover ("CodeProver"). You can use the other task properties to specify the report templates and other task settings. For example, in your process model:

%% Check Coding Standards with Polyspace Bug Finder
psbfTask = pm.addTask(padv.builtin.task.AnalyzeModelCode());
% Report Options
psbfTask.ResultDir = fullfile(defaultResultPath,"bug_finder");
psbfTask.ReportPath = fullfile(defaultResultPath,"bug_finder");

%% Prove Code Quality with Polyspace Code Prover
pscpTask = pm.addTask(padv.builtin.task.AnalyzeModelCode(Name="ProveCodeQuality"));
pscpTask.Title = "Prove Code Quality";
pscpTask.VerificationMode = "CodeProver";
% Report Options
pscpTask.ResultDir = string(fullfile(defaultResultPath,"code_prover"));
pscpTask.Reports = ["Developer", "CallHierarchy", "VariableAccess"];
pscpTask.ReportPath = string(fullfile(defaultResultPath,"code_prover"));
pscpTask.ReportNames = [...
    "$ITERATIONARTIFACT$_Developer", ...
    "$ITERATIONARTIFACT$_CallHierarchy", ...
    "$ITERATIONARTIFACT$_VariableAccess"];
Note that this code specifies different result directories and report paths for each task to prevent the task outputs from overwriting each other.

For information on:

If you have a Polyspace Access license, you can reconfigure the AnalyzeModelCode task to automatically upload results to Polyspace Access for your team to review.

Before you reconfigure the task, make sure that you have performed this one-time setup Prerequisites (Polyspace Bug Finder).

To reconfigure the task, update your process model to specify the property PsAccessEnable as true and to specify values for these properties:

  • PsAccessHostName

  • PsAccessPortNumber

  • PsAccessProtocol

  • PsAccessParentFolder

  • And one of the following sets of credentials:

    • PsAccessCredentialsFile

    • PsAccessApiKey

    • PsAccessUserName and PsAccessEncryptedPassword

For example, in your process model:

%% Check coding standards
psTask = pm.addTask(padv.builtin.task.AnalyzeModelCode());
psTask.addInputQueries(padv.builtin.query.FindFileWithAddress( ...
    Type = "ps_prj_file",...
    Path = fullfile("tools","CodingRulesOnly_config.psprj")));
psTask.ResultDir = string(fullfile("$DEFAULTOUTPUTDIR$", ...
    "$ITERATIONARTIFACT$","coding_standards"));
psTask.Reports = "CodingStandards";
psTask.ReportPath = string(fullfile("$DEFAULTOUTPUTDIR$", ...
    "$ITERATIONARTIFACT$","coding_standards"));
psTask.ReportNames = "$ITERATIONARTIFACT$_CodingStandards";
psTask.ReportFormat = "PDF";

% Polyspace Access configuration options
psTask.PsAccessEnable = true;
psTask.PsAccessHostName = "my-polyspace-access";
psTask.PsAccessPortNumber = "9443";
psTask.PsAccessProtocol = "https";
psTask.PsAccessCredentialsFile = "C:\Users\username\myCredentials.txt";
psTask.PsAccessParentFolder = "public/myProject";
psTask.PsAccessResultsName = "$ITERATIONARTIFACT$_CodingStandards";
This code uses a credentials file, myCredentials.txt, to pass credentials to Polyspace Access, but you can also use an API key or a username and password. For information on how to generate and maintain credentials for Polyspace Access, see login options (Polyspace Access).

For more information, see:

Tips

  • This task runs on the generated model code, iterating over either each model in the project or the project itself. If a model does not have generated code, the task skips the model and displays a warning message. You can generate code as part of your process by using the built-in task padv.builtin.task.GenerateCode and then analyze the generated code using the AnalyzeModelCode task. You can add these tasks to your process model by using the method addTask.

  • This task requires that your Polyspace installation is integrated with MATLAB and Simulink. If you have not already integrated your installation, use the function polyspacesetup. For information, see Integrate Polyspace with MATLAB and Simulink (Polyspace Bug Finder).

  • If you start MATLAB with the -batch option, the task requires a Polyspace server product. The required server product depends on the task configuration:

    • Check Coding Standards (default) — Requires the Polyspace Bug Finder Server™ product.

    • Prove Code Quality — Requires the Polyspace Code Prover Server product.

  • You can use both Bug Finder and Code Prover in your software development workflow. For information on how to include both a Bug Finder task and a Code Prover task in your process model, see Add Both Bug Finder and Code Prover Tasks to Process.

    For information on the differences between Bug Finder and Code Prover, see Differences Between Polyspace Bug Finder and Polyspace Code Prover (Polyspace Bug Finder).

See Also

| | | | | |

Topics