matlab.buildtool.tasks.CodeIssuesTask Class

Namespace: matlab.buildtool.tasks
Superclasses: matlab.buildtool.Task

Task for identifying code issues

Since R2023b

Description

The matlab.buildtool.tasks.CodeIssuesTask class provides a task for identifying code issues using the MATLAB^® Code Analyzer.

Tasks that you create with the CodeIssuesTask class do not support incremental builds. If you rerun a build containing a CodeIssuesTask instance, the build tool runs the task.

Creation

Description

task = matlab.buildtool.tasks.CodeIssuesTask creates a task for identifying code issues in the current folder and its subfolders. The task fails if it identifies any code errors.

task = matlab.buildtool.tasks.CodeIssuesTask(sourceFiles) sets the SourceFiles property. The task analyzes the specified source files and folders, including their subfolders.

task = matlab.buildtool.tasks.CodeIssuesTask(___,Name=Value) sets properties using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. You can also set the Description and Dependencies properties, which the class inherits from the Task class, using name-value arguments. For example, task = matlab.buildtool.tasks.CodeIssuesTask(WarningThreshold=0) creates a task that fails if it identifies any warnings.

Properties

This section lists the properties of the CodeIssuesTask class. In addition to these properties, the CodeIssuesTask class inherits properties from the Task class. Of the inherited properties, you can set the Description and Dependencies properties using name-value arguments during task creation.

SourceFiles — Source files and folders to analyze

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

Source files and folders to analyze, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and returned as a matlab.buildtool.io.FileCollection row vector. The files and folders must reside in the plan root folder or any of its subfolders.

Attributes:

GetAccess	public
SetAccess	public

IncludeSubfolders — Option to include subfolders in analysis

true or 1 (default) | false or 0

Option to include subfolders in the analysis, specified as a numeric or logical 1 (true) or 0 (false). By default, the task analyzes the code in the specified folders and their subfolders.

Attributes:

GetAccess	public
SetAccess	public

Configuration — Code Analyzer configuration settings

"active" (default) | "factory" | name of custom configuration file

Code Analyzer configuration settings, specified as one of these values:

• "active" — Use the current active configuration settings. The task uses these settings by default.

• "factory" — Use the default configuration settings.

• filename — Use the settings in the specified custom configuration file.

If the task uses the current active configuration settings, placing a configuration file named codeAnalyzerConfiguration.json in a resources folder in the plan root folder configures the Code Analyzer checks for all the code in your project. For more information on how to configure Code Analyzer messages and add custom checks, see Configure Code Analyzer.

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

ErrorThreshold — Maximum number of errors allowed

0 (default) | nonnegative integer scalar

Maximum number of errors allowed for the task to pass, specified as a nonnegative integer scalar. By default, the error threshold is 0. The task fails if the number of identified errors exceeds the threshold.

Attributes:

GetAccess	public
SetAccess	public

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

WarningThreshold — Maximum number of warnings allowed

Inf (default) | nonnegative integer scalar

Maximum number of warnings allowed for the task to pass, specified as a nonnegative integer scalar. By default, the warning threshold is Inf. The task fails if the number of identified warnings exceeds the threshold.

Attributes:

GetAccess	public
SetAccess	public

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Results — Code analysis results

matlab.buildtool.io.File row vector

Since R2024a

Code analysis results, returned as a matlab.buildtool.io.File row vector. You can set this property during creation of the task using a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.File vector.

The task enables you to export the code issues in various formats. Specify formats by using file extensions:

• .sarif — Export the code issues in SARIF format.

• .mat — Save the codeIssues object to a MAT-file.

Example: task = matlab.buildtool.tasks.CodeIssuesTask(Results="code-issues/results.sarif") creates a task that exports the code issues in SARIF format.

Example: task = matlab.buildtool.tasks.CodeIssuesTask(Results=["code-issues/results.sarif" "code-issues/results.mat"]) creates a task that exports the code issues in both SARIF and MAT-file formats.

Attributes:

GetAccess	public
SetAccess	private

Examples

Identify Code Issues in Project

Identify the code issues in your project by using the CodeIssuesTask class.

Open the example and then navigate to the code_issues_task_example folder, which contains a build file as well as a source file named myfun.m.

cd code_issues_task_example

This code shows the contents of the source file. For illustrative purposes, the call to the eval function intentionally results in a Code Analyzer warning. For more information, see Alternatives to the eval Function.

function myfun(numArrays)
arguments
    numArrays (1,1) {mustBeInteger,mustBePositive}
end
for n = 1:numArrays
    eval(['A',int2str(n),' = magic(n)'])
end
end

This code shows the contents of the build file. The build file contains one task that identifies the code issues in the current folder and its subfolders and fails the build if any code errors are found.

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to identify the code issues in the project
plan("check") = CodeIssuesTask;
end

Run the "check" task. Even though myfun.m issues a warning, the task runs successfully because no code errors are found. A CodeIssuesTask instance fails if the number of identified errors or warnings exceeds the corresponding threshold.

buildtool check

** Starting check
Analysis Summary:
    Total Files: 2
         Errors: 0 (Threshold: 0)
       Warnings: 1 (Threshold: Inf)
** Finished check

Fail Build on Code Analyzer Warnings

Create and run a task that fails if it identifies any code warnings.

First, create a folder in your current folder, and change the current folder to that folder.

mkdir code_issues_task_example1
cd code_issues_task_example1

In a file named myfun.m in your current folder, create the myfun function. For illustrative purposes, the file contains a call to the eval function, which is not recommended and results in a Code Analyzer warning. For more information, see Alternatives to the eval Function.

function myfun(numArrays)
arguments
    numArrays (1,1) {mustBeInteger,mustBePositive}
end
for n = 1:numArrays
    eval(['A',int2str(n),' = magic(n)'])
end
end

In your current folder, create a build file named buildfile.m with a task that identifies the code issues in the current folder and its subfolders. By default, a CodeIssuesTask instance does not fail if it identifies warnings. To perform stricter checks on your code, create the task by specifying the WarningThreshold name-value argument. Additionally, specify the Results name-value argument to export the code issues in SARIF format.

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to identify and export the code issues
plan("check") = CodeIssuesTask(WarningThreshold=0, ...
    Results="code-issues/results.sarif");
end

At the command prompt, run the "check" task. The task identifies the code issues and exports them to the specified location in your current folder. Because the number of identified warnings exceeds the warning threshold, the task fails.

buildtool check

** Starting check
Analysis Summary:
    Total Files: 2
         Errors: 0 (Threshold: 0)
       Warnings: 1 (Threshold: 0)

Results:
    SARIF: code-issues\results.sarif
## -----------------------------------------------------------------------------
## Error occurred in 'check' and it did not run to completion.
##   Identifier: 'MATLAB:buildtool:CodeIssuesTask:ThresholdExceeded'
##      Message: Issues exceed threshold.
##        Stack: matlabroot\toolbox\matlab\buildtool\ext\+matlab\+buildtool\+tasks\CodeIssuesTask.m (CodeIssuesTask.analyze) at 256
## -----------------------------------------------------------------------------
** Failed check

Error using buildtool
Build failed.

Tips

• You cannot overwrite or remove the actions of a built-in task, but you can specify additional task actions. For example, append an action to the Actions property of a built-in task.

  plan("myTask").Actions(end+1) = @myAction;

Version History

Introduced in R2023b

R2024a: Programmatically access code analysis results

You can use the Results property to programmatically access the results of code analysis. For example, you can return the paths to the code analysis results by using p = plan("check").Results.paths'. You can also specify the code analysis results as inputs of other tasks, for instance, plan("archive").Inputs = plan("check").Results.