matlab.buildtool.TaskGroup Class

R2026b

Namespace: matlab.buildtool
Superclasses: matlab.buildtool.PlanElement

Group of tasks

Since R2024b

expand all in page

Description

The matlab.buildtool.TaskGroup class provides a way to group tasks into a single unit of work in a build. For example, you can create a TaskGroup object to group all the tasks in your project that build binary MEX files. Then, you can run all these tasks by running the task group. For more information about task groups, see Create Groups of Tasks.

Class Attributes

Sealed
true

For information on class attributes, see Class Attributes.

Creation

You can create a task group by adding a task whose name contains a colon to a build plan. For example, this code adds a task named "mygroup:task1" to the plan. Because the task name includes a colon, the assignment also creates a task group named "mygroup" in the plan. In this example, the "mygroup" task group contains a single task named "mygroup:task1".

import matlab.buildtool.Task

plan = buildplan;
plan("mygroup:task1") = Task;

To add a task to an existing task group, start the task name with the task group name followed by a colon. For example, add the "mygroup:task2" task to the "mygroup" task group.

plan("mygroup:task2") = Task;

For another example of creating a task group by adding tasks to a plan, see Build MEX Files Using Task Group.

Alternatively, you can first group your tasks and then add the task group to the plan. To create a task group without directly adding its tasks to the plan, create a TaskGroup instance using the constructor syntaxes in this section.

Description

group = matlab.buildtool.TaskGroup(tasks) creates a task group from the specified tasks. The constructor names the tasks in the group as "task1", "task2", …, "taskN".

group = matlab.buildtool.TaskGroup(tasks,Name=Value) specifies options using one or more name-value arguments. For example, group = matlab.buildtool.TaskGroup([mexTask1 mexTask2],Description="Build MEX files") creates a group of two tasks with the specified description.

example

Input Arguments

expand all

Tasks to group, specified as a matlab.buildtool.Task array.

This argument sets the Tasks property.

Example: plan("mex") = matlab.buildtool.TaskGroup([myFirstTask mySecondTask]) creates the "mex" task group, including the "mex:task1" and "mex:task2" tasks.

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: group = matlab.buildtool.TaskGroup([mexTask1 mexTask2],Description="Build MEX files")

Names of the tasks, specified as a string array, character vector, or cell array of character vectors. TaskNames must be the same size as tasks, or tasks must be a single object:

  • If TaskNames and tasks are the same size, then the constructor adds each task in tasks to the task group using the corresponding name in TaskNames.

  • If tasks is a single object, then the constructor adds copies of the specified task to the task group using the names in TaskNames.

Note

Do not specify the task group name in TaskNames. The build tool automatically appends the specified names, with a colon, to the name of the task group in the plan.

Example: plan("mex") = matlab.buildtool.TaskGroup([myFirstTask mySecondTask],TaskNames=["explore" "yprime"]) creates the "mex" task group, including the "mex:explore" and "mex:yprime" tasks.

Description of the task group, specified as a string scalar or character vector.

This argument sets the Description property.

Names of the tasks on which the tasks in the task group depend, specified as a string vector, character vector, or cell vector of character vectors. To run all or part of the task group, the build runner first runs all the depended-on tasks.

This argument sets the Dependencies property.

Properties

expand all

Name of the task group, 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 group is nested inside other task groups, its name consists of segments separated by a colon. Each segment must satisfy the conditions listed above.

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

The matlab.buildtool.TaskGroup class inherits the Name property from the matlab.buildtool.PlanElement superclass.

Attributes:

GetAccess
public
SetAccess
Restricts access

Description of the task group, specified as a string scalar or character vector, and stored as a string scalar.

The matlab.buildtool.TaskGroup class inherits the Description property from the matlab.buildtool.PlanElement superclass.

Attributes:

GetAccess
public
SetAccess
public

Names of the tasks on which the tasks in the task group depend, specified as a string vector, character vector, or cell vector of character vectors, and stored as a string row vector. To run all or part of the task group, the build runner first runs all the depended-on tasks.

Attributes:

GetAccess
public
SetAccess
public

Tasks in the task group, represented as a matlab.buildtool.Task row vector. You can use this property to programmatically access the tasks in the task group. For example, you can specify the MEX files produced by MexTask instances in a "mex" task group as the inputs of an "archive" task by using plan("archive").Inputs = [plan("mex").Tasks.MexFile].

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Open Script

Build MEX files by using a group of matlab.buildtool.tasks.MexTask instances. You must have a supported C compiler installed on your system to run this example.

Open the example and then navigate to the task_group_example folder, which contains a build file as well as two C source files named explore.c and yprime.c.

cd task_group_example

This code shows the contents of the build file:

  • The "clean" task deletes outputs and traces of the other tasks in the build file.

  • The "mex" task group contains two tasks named "mex:explore" and "mex:yprime". Each of these tasks compiles a source file into a MEX file and saves the result to a folder named output in your current folder.

function plan = buildfile
import matlab.buildtool.tasks.CleanTask
import matlab.buildtool.tasks.MexTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to delete outputs and traces
plan("clean") = CleanTask;

% Add a task group to build MEX files
plan("mex:explore") = MexTask("explore.c","output");
plan("mex:yprime") = MexTask("yprime.c","output");

plan("mex").Description = "Build MEX files";
end

Run the "mex" task group. The "mex:explore" and "mex:yprime" tasks in the task group build binary MEX files and save them to the output folder. The build run progress includes information specific to your compiler.

buildtool mex

** Starting mex:explore
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:explore

** Starting mex:yprime
mex yprime.c -output output\yprime.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:yprime

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    27.064 sec total build time

Run the "mex:explore" task in isolation. The build tool skips the task because neither its input nor output has changed.

buildtool mex:explore

** Skipped mex:explore (up-to-date)

Build Successful:
    1 Task: 0 Failed, 1 Skipped
    0.32208 sec total build time

Run the "clean" task to delete outputs and traces of the other tasks in the plan. When you delete the outputs or the trace of a task, the build tool no longer considers the task as up to date.

buildtool clean

** Starting clean
Deleted 'C:\work\ExampleManager\user.examples\matlab-ex56352418\task_group_example\output\explore.mexw64'
Deleted 'C:\work\ExampleManager\user.examples\matlab-ex56352418\task_group_example\output\yprime.mexw64'
** Finished clean

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    0.37324 sec total build time

Rerun the "mex:explore" task to build a fresh MEX file.

buildtool mex:explore

** Starting mex:explore
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:explore

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    4.194 sec total build time

Now, run the "mex" task group again. The build tool runs only the "mex:yprime" task in the task group. It skips the "mex:explore" task because the task is up to date.

buildtool mex

** Skipped mex:explore (up-to-date)

** Starting mex:yprime
mex yprime.c -output output\yprime.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:yprime

Build Successful:
    2 Tasks: 0 Failed, 1 Skipped
    4.177 sec total build time
Open Live Script

Create a group of matlab.buildtool.tasks.MexTask instances by using the TaskGroup class constructor. You must have a supported C compiler installed on your system to run this example.

Open the example and then navigate to the task_group_example1 folder, which contains a build file as well as two C source files named explore.c and yprime.c.

cd task_group_example1

This code shows the contents of the build file. The "mex" task group in the build file contains two tasks named "mex:explore" and "mex:yprime". Each of these tasks compiles a source file into a MEX file and saves the result to a folder named output in your current folder.

function plan = buildfile
import matlab.buildtool.TaskGroup
import matlab.buildtool.tasks.MexTask

% Create a plan with no tasks
plan = buildplan;

% Add a task group to build MEX files
plan("mex") = TaskGroup( ...
    [MexTask("explore.c","output") MexTask("yprime.c","output")], ...
    TaskNames=["explore" "yprime"], ...
    Description="Build MEX files");
end

List all the tasks in the build file.

buildtool -tasks all
mex         - Build MEX files
mex:explore - Build explore MEX file
mex:yprime  - Build yprime MEX file

Run the "mex" task group. The "mex:explore" and "mex:yprime" tasks in the task group build binary MEX files and save them to the output folder. The build run progress includes information specific to your compiler.

buildtool mex
** Starting mex:explore
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:explore

** Starting mex:yprime
mex yprime.c -output output\yprime.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:yprime

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    13.675 sec total build time

Tips

  • Operating on a task group affects all the tasks in the group. For example:

    • If you run or skip a task group, the build tool runs or skips all the tasks in the group.

    • If you operate on a task group using a matlab.buildtool.tasks.CleanTask instance, the CleanTask instance deletes the outputs of all the tasks in the group.

    • If you add a dependency to a task group, all the tasks in the group observe that dependency.

  • You can create nested task groups by including more than one colon in a task name. For example, this code creates the "g1" task group that contains the "g1:t1" task as well as the "g1:g2" task group. (The "g1:g2" task group contains the "g1:g2:t2" and "g1:g2:t3" tasks.)

    import matlab.buildtool.Task

plan = buildplan;
plan("g1:t1") = Task;
plan("g1:g2:t2") = Task;
plan("g1:g2:t3") = Task;

  • When tasks in a task group have no dependencies or other constraints, the tasks run serially in the order in which you add them to the task group. During parallel execution, task order is not guaranteed unless you specify dependencies. If a task depends on the outcome of another task, express that relationship using a dependency.

Version History

Introduced in R2024b

expand all

See Also

Functions

Classes

Topics