matlab.buildtool.TaskGroup Class

Namespace: matlab.buildtool
Superclasses: matlab.buildtool.Task

Group of similar tasks

Since R2024b

Description

The matlab.buildtool.TaskGroup class provides a way to group tasks that perform similar actions into a single unit of work in the build tool. 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 Similar 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.

Input Arguments

tasks — Tasks to group

matlab.buildtool.Task array

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

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")

TaskNames — Names of tasks

string array | character vector | cell array of character vectors

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 — Description of task group

string scalar | character vector

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

Dependencies — Names of tasks on which the task group depends

string vector | character vector | cell vector of character vectors

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.

Properties

In addition to the following property, the TaskGroup class inherits properties from the Task class. Of the inherited properties, you can set the Description and Dependencies properties using name-value arguments during group creation. You cannot set the Actions, Inputs, or Outputs property of a TaskGroup instance.

Tasks — Tasks in group

matlab.buildtool.Task row vector

Tasks in the task group, returned 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

Build MEX Files Using Task Group

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

** Done mex

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)

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\task_group_example\output\explore.mexw64' successfully
Deleted 'C:\work\task_group_example\output\yprime.mexw64' successfully
** Finished clean

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

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

** Done mex

Create Task Group Using Constructor

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. Because the matlab.buildtool.TaskGroup class subclasses the matlab.buildtool.Task class, the "mex" task group itself is a task.

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

** Done mex

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 delete the outputs of 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 "t1" task as well as the "g2" task group. (The "g2" task group contains the "t2" and "t3" tasks.)

  import matlab.buildtool.Task
  
  plan = buildplan;
  plan("g1:t1") = Task;
  plan("g1:g2:t2") = Task;
  plan("g1:g2:t3") = Task;

Version History

Introduced in R2024b