matlab.buildtool.Task class

Package: 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.

A task has three fundamental characteristics:

• Name — The name of a task uniquely identifies the task in a build plan.

• Dependencies — The dependencies of a task are other tasks in the plan that must run before the task runs.

• Actions — The actions of a task define functions that execute when the task runs.

To run a task, the build runner first runs all its dependencies and then performs actions of the task in the order they appear in the Actions property.

Creation

Description

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

t = matlab.buildtool.Task(Name=Value) sets properties using one or more name-value arguments. However, you cannot use this syntax to set the Name property. For example, t = 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

<missing> (default) | string scalar

Name of the task, returned as a string scalar. The name must be a valid MATLAB^® identifier. A valid MATLAB identifier is a string scalar or character vector of alphanumerics (A–Z, a–z, 0–9) and underscores, where the first character is a letter and the length of the text is less than or equal to namelengthmax.

By default, the property contains a missing value. The build tool sets the property when you assign 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 returned 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 returned 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 returned 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.

Attributes:

GetAccess	public
SetAccess	public

Inputs — Task inputs

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

Task inputs, specified as a string vector, character vector, cell vector of character vectors, or vector of matlab.buildtool.io.FileCollection objects, and returned as a row vector of FileCollection objects. Setting this property lets you run the task as part of an incremental build. For more information, see Improve Performance with Incremental Builds.

Attributes:

GetAccess	public
SetAccess	public

Outputs — Task outputs

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

Task outputs, specified as a string vector, character vector, cell vector of character vectors, or vector of matlab.buildtool.io.FileCollection objects, and returned as a row vector of FileCollection objects. Setting this property lets you run the task as part of an incremental build. For more information, see Improve Performance with Incremental Builds.

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 Task class.

import matlab.buildtool.Task

Create a plan with no tasks.

plan = buildplan;

Add a task named "check" to the plan. This code adds a task that has no description, dependencies, or actions.

plan("check") = Task;

Specify the description and actions of the "check" task by setting its properties. The task identifies code issues in the current folder and its subfolders and fails the build if any issues are found.

plan("check").Description = "Identify code issues";
plan("check").Actions = @check;

Add a task to the plan that runs the tests in the current folder and its subfolders and fails the build if any of the tests fail. Specify the task description and actions during creation of the task.

plan("test") = Task( ...
    Description="Run unit tests", ...
    Actions=@test);

Add another task 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
** Finished check

** Starting test
...
** Finished test

** Starting archive
** Finished archive

Local Functions

This section contains the local functions used to define different task actions.

function check(~)
issues = codeIssues;
assert(isempty(issues.Issues),formattedDisplayText( ...
    issues.Issues(:,["Location" "Severity" "Description"])))
end

function test(~)
results = runtests(IncludeSubfolders=true,OutputDetail="terse");
assertSuccess(results);
end

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

Create and Run Task with Inputs and Outputs

Create and run a task that has inputs and outputs. Tasks with specified inputs or outputs support incremental builds.

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

Version History

Introduced in R2022b

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. For more information on how to run an incremental build, see Improve Performance with Incremental Builds.