matlab.buildtool.Plan Class

R2026b

Namespace: matlab.buildtool

Fundamental interface for defining a build

Since R2022b

expand all in page

Description

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

A Plan object behaves like a dictionary, where keys are names and values are PlanElement objects. For example, 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 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

expand all

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 in the plan, represented as a row vector of matlab.buildtool.PlanElement objects. The matlab.buildtool.PlanElement class is the superclass of the matlab.buildtool.Task and matlab.buildtool.TaskGroup classes. Therefore, the Tasks property can contain a combination of Task and TaskGroup objects.

Before R2026b: The Tasks property contains a row vector of matlab.buildtool.Task objects.

Attributes:

GetAccess
public
SetAccess
private

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

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

expand all

Examples

collapse all

Open Live Script

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)
           Info: 0 (Threshold: Inf)
** Finished check

** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.083159 seconds testing time.
                 
** Finished test

** Starting archive
** Finished archive

Build Successful:
    3 Tasks: 0 Failed, 0 Skipped
    4.9989 sec total build time

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

expand all

See Also

Functions

Classes

Namespaces

Topics