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

DefaultTasks — Names of default tasks

string vector | character vector | cell vector of character vectors

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 — Tasks in plan

row vector of matlab.buildtool.Task objects

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

Attributes:

GetAccess	public
SetAccess	private

RootFolder — Full path to folder containing the build file

string scalar

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

Public Methods

files	Create file collection
matlab.buildtool.Plan.load	Load plan from file into workspace
run	Run build using runner configured for text output
plot	Plot tasks in plan

Examples

Add Tasks to Plan

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

R2023a: Create file collections for incremental builds

The matlab.buildtool.Plan class has a new method named files that lets you create a FileCollection object to use in incremental builds.