matlab.buildtool.Task Class

Namespace: matlab.buildtool

Single unit of work in a build

Since R2022b

Description

The matlab.buildtool.Task class represents a single unit of work in a build, such as identifying code issues, running tests, and packaging a toolbox. Each task in a build plan is an object of the matlab.buildtool.Task class.

The matlab.buildtool.Task class is the superclass of all task classes, including built-in task classes in the matlab.buildtool.tasks namespace and custom task classes. To specify task actions, inputs, and outputs, subclasses can leverage framework-specific attributes. For more information, see Task Method Attributes and Task Property Attributes.

Creation

Description

task = matlab.buildtool.Task returns a Task object whose properties have their default values.

task = matlab.buildtool.Task(Name=Value) sets writable properties using one or more name-value arguments. For example, task = matlab.buildtool.Task(Actions=@(~)assertSuccess(runtests)) creates a task that runs the tests in your current folder and fails if any of the tests fail.

Properties

Name — Name of task

"" (default) | string scalar | character vector

Name of the task, specified as a string scalar or character vector, and stored as a string scalar. You can specify a value of any length that:

• Contains alphanumerics (A–Z, a–z, 0–9), underscores, dashes, and periods

• Does not start with a dash

If a task belongs to a task group, its name consists of segments separated by a colon. Each segment must satisfy the conditions listed above. For more information about task groups, see Create Groups of Similar Tasks. (since R2024b)

By default, the property contains an empty string. The build tool sets the property when you add the task to a build plan. For example, plan("taskName") = task sets the Name property of task to "taskName".

Attributes:

GetAccess	public
SetAccess	Restricts access

Description — Description of task

string scalar | character vector

Description of the task, specified as a string scalar or character vector, and stored as a string scalar. When the build tool lists the tasks, it also includes task descriptions.

Attributes:

GetAccess	public
SetAccess	public

Dependencies — Names of tasks on which the task depends

string vector | character vector | cell vector of character vectors

Names of the tasks on which the task depends, specified as a string vector, character vector, or cell vector of character vectors, and stored as a string row vector. To run the task, the build runner first runs all the depended-on tasks. The order of task names in Dependencies does not matter.

Attributes:

GetAccess	public
SetAccess	public

Actions — Actions of task

function handle | cell vector of function handles | vector of matlab.buildtool.TaskAction objects

Actions of the task, specified as a function handle, cell vector of function handles, or vector of matlab.buildtool.TaskAction objects, and stored as a row vector of TaskAction objects. The build runner performs actions in the order they appear in this property. Most tasks require no more than one action.

Note

If you specify a function handle, its first input must be a matlab.buildtool.TaskContext object, which provides context-specific information to the action. For an example of how to define a task action, see Specify Task Actions.

Attributes:

GetAccess	public
SetAccess	public

Inputs — Task inputs

string vector | matlab.buildtool.io.FileCollection vector | matlab.buildtool.TaskInputs object | ...

Task inputs, specified as one of these values:

• String vector

• Character vector

• Cell vector of character vectors

• matlab.buildtool.io.FileCollection vector

• matlab.buildtool.TaskInputs object

If you specify a string vector, character vector, or cell vector of character vectors, MATLAB^® automatically converts the value to a FileCollection row vector.

For more information about task inputs and outputs, see Improve Performance with Incremental Builds.

Note

The task inputs in the Inputs property are independent of the task inputs specified using the TaskInput property attribute in a task class definition. (since R2025a)

Attributes:

GetAccess	public
SetAccess	public

Outputs — Task outputs

string vector | matlab.buildtool.io.FileCollection vector | matlab.buildtool.TaskOutputs object | ...

Task outputs, specified as one of these values:

• String vector

• Character vector

• Cell vector of character vectors

• matlab.buildtool.io.FileCollection vector

• matlab.buildtool.TaskOutputs object

If you specify a string vector, character vector, or cell vector of character vectors, MATLAB automatically converts the value to a FileCollection row vector.

For more information about task inputs and outputs, see Improve Performance with Incremental Builds.

Note

The task outputs in the Outputs property are independent of the task outputs specified using the TaskOutput property attribute in a task class definition. (since R2025a)

Attributes:

GetAccess	public
SetAccess	public

DisableIncremental — Option to run task when up to date

false or 0 (default) | true or 1

Since R2024a

Option to run the task when it is up to date, specified as a numeric or logical 0 (false) or 1 (true). By default, the build tool skips an up-to-date task. To force the task to rerun even if it is up to date, set the DisableIncremental property to true.

You can use this property to disable incremental builds for the task. For more information about incremental builds, see Improve Performance with Incremental Builds.

Note

The DisableIncremental property does not affect tasks that do not support incremental builds because these tasks run regardless of whether they are up to date. For example, changing the value of DisableIncremental for a CodeIssuesTask instance does not affect how the build tool handles the task.

Attributes:

GetAccess	public
SetAccess	public

Examples

Add Tasks to Plan

Create tasks and add them to a build plan. Then, run the build.

Import the classes used in this example.

import matlab.buildtool.Task
import matlab.buildtool.tasks.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

Create a plan with no tasks.

plan = buildplan;

Create a task named "check" that identifies code issues in the current folder and its subfolders and fails the build if any errors are found. To create the task, use the CodeIssuesTask built-in class.

plan("check") = CodeIssuesTask;

Create a task named "test" that runs the tests in the current folder and its subfolders and fails the build if any of the tests fail. To create the task, use the TestTask built-in class.

plan("test") = TestTask;

Add another task to the plan that creates an archive of the current folder. Make the task dependent on the "check" and "test" tasks.

plan("archive") = Task( ...
    Description="Create ZIP file", ...
    Dependencies=["check" "test"], ...
    Actions=@archive);

Now, make the "archive" task the default task in the plan.

plan.DefaultTasks = "archive";

Run the default task. The build tool runs the "archive" task as well as both the tasks on which it depends. In this example, the tasks run successfully.

result = run(plan);

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

** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.24699 seconds testing time.
                 
** Finished test

** Starting archive
** Finished archive

Local Function

This code shows the local function used in this example.

function archive(~)
filename = "source_" + ...
    string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
zip(filename,"*")
end

Create and Run Task with Inputs and Outputs

Create and run a task named "pcode" that has inputs and outputs. (For illustrative purposes, the "pcode" task in this example is created using the matlab.buildtool.Task class. The recommended practice is to create the task using the matlab.buildtool.tasks.PcodeTask class.)

Import the Task class.

import matlab.buildtool.Task

Create the files and folders used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

Create a plan with no tasks.

plan = buildplan;

Add a task named "pcode" to the plan that creates P-code files. To specify the inputs and outputs of the task, set the Inputs and Outputs properties. See the code of the local function pcodeAction, which is used in this task definition, at the end of this example.

plan("pcode") = Task( ...
    Description="Create P-code files", ...
    Actions=@pcodeAction, ...
    Inputs="source/**/*.m", ...
    Outputs="source/**/*.p");

Run the "pcode" task. The task obfuscates its inputs and creates the P-code files in the same folders as the inputs.

run(plan,"pcode");

** Starting pcode
** Finished pcode

Run the task again. The build tool skips the task because none of the inputs or outputs of the task have changed since the last run.

run(plan,"pcode");

** Skipped pcode (up-to-date)

Add a file to the source folder, and then rerun the task. The build tool runs the task because the inputs of the task have changed.

createFile(fullfile("source","newFile.m"))
run(plan,"pcode");

** Starting pcode
** Finished pcode

Local Functions

This section contains the local functions used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

function pcodeAction(context)
filePaths = context.Task.Inputs.paths;
pcode(filePaths{:},"-inplace")
end

More About

Task Method Attributes

This method attribute is specific to Task subclasses.

TaskAction

Apply this attribute to a methods block to define the task action. You can specify only a single method with the TaskAction attribute. The method must have public access and must not be static. methods (TaskAction) function action(task,context) % Action code end end Because a TaskAction method is not static, its first input must be a matlab.buildtool.Task object. Its second input must be a matlab.buildtool.TaskContext object, which provides context-specific information to the action. The method can have additional inputs if the task accepts arguments for run-time configuration. The constructor sets the Actions property of the task using the specified TaskAction method. You cannot overwrite or remove this action, but you can specify additional actions after task creation. For example, append an action to the Actions property of your custom task. plan("myTask").Actions(end+1) = @myAction;

Standard attributes also apply to methods of Task subclasses. For details, see Method Attributes.

Task Property Attributes

These property attributes are specific to Task subclasses.

TaskInput

Apply this attribute to a properties block to define task inputs. Properties with the TaskInput attribute can be of any type. They must be nonconstant and have public GetAccess. properties (TaskInput) Data Options (1,:) string end TaskInput properties do not affect the Inputs property of the task. You can use the Inputs property to specify additional inputs after task creation.

TaskOutput

Apply this attribute to a properties block to define task outputs. Properties with the TaskOutput attribute must be of type matlab.buildtool.io.FileCollection. They must be nonconstant and have public GetAccess. properties (TaskOutput) Result matlab.buildtool.io.File {mustBeScalarOrEmpty} end TaskOutput properties do not affect the Outputs property of the task. You can use the Outputs property to specify additional outputs after task creation.

Standard attributes also apply to properties of Task subclasses. For details, see Property Attributes.

Version History

Introduced in R2022b

R2025a: Create custom reusable tasks

You can create your own task class by subclassing the matlab.buildtool.Task class. To specify the task action, inputs, and outputs, use the TaskAction, TaskInput, and TaskOutput framework-specific attributes in the task class definition.

R2024b: Specify task names more flexibly

You can specify the name of a task as a string scalar or character vector of any length that contains alphanumerics (A–Z, a–z, 0–9), underscores, dashes, and periods. In previous releases, the task name must be a valid MATLAB identifier.

R2024a: Disable incremental builds for task

To disable incremental builds for a task so that it runs even if it is up to date, set its DisableIncremental property to true.

R2024a: Default task name is empty string

The default value of the Name property is an empty string. In previous releases, the default value is a missing value.

R2023a: Run builds more efficiently by specifying task inputs and outputs

To support incremental builds, the matlab.buildtool.Task class has two new properties, Inputs and Outputs.