matlab.buildtool.Task Class
Namespace: matlab.buildtool
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
task = matlab.buildtool.Task
returns a
Task
object whose properties have their default values.
task = matlab.buildtool.Task(
sets properties using
one or more name-value arguments. However, you cannot use this syntax to set the
Name=Value
)Name
property. 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
Name of the task, returned as a string scalar. You can specify the task name as a string scalar or character vector 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("
sets the
taskName
") = taskName
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.
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.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.
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.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.
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.
You can use this property to disable incremental builds for the task. To force the
task to rerun even if it is up to date, set the DisableIncremental
property to true
. 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 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
Version History
Introduced in R2022bR2024b: 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
.
See Also
Functions
Classes
Namespaces
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)