Main Content

matlab.buildtool.Plan class

Package: matlab.buildtool

Fundamental interface for defining a build

Since R2022b

Description

The matlab.buildtool.Plan class is the fundamental interface used to group a set of tasks and define a build.

A Plan object behaves like a dictionary of tasks, where keys are task names and values are Task objects. To add a task to the plan, modify a task in the plan, or return a copy of a specific task in the plan, index into the Plan object by using the task name.

  • To add a Task object t, use the plan("taskName") = t syntax. "taskName" must be a valid MATLAB® identifier and must not be used by any of the existing tasks in the plan.

  • To modify a Task object, use the plan("taskName").TaskProp = value syntax. TaskProp can be any publicly writable property of a Task object.

  • To return a copy of a Task object, use the t = plan("taskName") syntax. Modifying the returned task does not affect the original task in the plan.

Class Attributes

Sealed
true

For information on class attributes, see Class Attributes.

Creation

To create a Plan object, use the buildplan function.

Properties

expand all

Names of the default tasks, specified as a string vector, character vector, or cell vector of character vectors, and returned as a string row vector. When no tasks are specified for a build run, the build runner runs these default tasks.

Example: "compile"

Example: ["compile" "test"]

Attributes:

GetAccess
public
SetAccess
public

Tasks in the plan, returned as a row vector of matlab.buildtool.Task objects.

Attributes:

GetAccess
public
SetAccess
private

Full path to the folder containing the build file that created the plan, returned as a string scalar. If the plan was created in the Command Window, the property includes the full path to the current folder when the plan was created.

Example: "C:\work\buildfile.m"

Attributes:

GetAccess
public
SetAccess
immutable

Methods

expand all

Examples

collapse all

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

Version History

Introduced in R2022b

expand all