matlab.buildtool.Plan Class

Namespace: 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:

• plan("taskName") = t adds the Task object t to the plan.

• plan("taskName").TaskProp = value modifies a property of the specified task.

• t = plan("taskName") returns a copy of the specified task.

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 stored 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, represented as a row vector of matlab.buildtool.Task objects.

Attributes:

GetAccess	public
SetAccess	private

RootFolder — Absolute path to folder containing the build file

string scalar

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

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

Attributes:

GetAccess	public
SetAccess	immutable

Project — Project that contains plan root folder

empty matlab.project.Project array (default) | matlab.project.Project object

Since R2025a

Project that contains the plan root folder, represented as a matlab.project.Project object. If the plan root folder is not in a MATLAB^® project, then the value is an empty matlab.project.Project array. Use this property for programmatic access to the project that contains your build file.

Attributes:

GetAccess	public
SetAccess	immutable

Methods

Public Methods

files	Create file collections
matlab.buildtool.Plan.load	Load plan 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 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

Version History

Introduced in R2022b

R2025a: Programmatically access MATLAB project that contains build file

To programmatically access the MATLAB project that contains your build file, use the Project property.

R2023a: Create file collections for incremental builds

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