Single unit of work in a build
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
t = matlab.buildtool.Task returns a
Task object whose properties have their default values.
t = matlab.buildtool.Task(
sets properties using
one or more name-value arguments. However, you cannot use this syntax to set the
Name property. For example,
Task(Actions=@(~)assertSuccess(runtests)) creates a task that runs the tests
in your current folder and fails if any of the tests fail.
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
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(" sets the
taskName") = task
Name property of
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.
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.
Actions — Actions of task
function handle | cell vector of function handles | vector of
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.
Add Tasks to Plan
Create tasks and add them to a build plan. Then, run the build.
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 for sharing. Make the task dependent on the
plan("archive") = Task( ... Description="Create archive for sharing", ... 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
This section contains the local functions used to define different task actions.
function check(~) issues = codeIssues; assert(isempty(issues.Issues),formattedDisplayText(issues.Issues)) 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
Introduced in R2022b