buildplan

Create build plan

Since R2022b

Syntax

plan = buildplan

plan = buildplan(fcns)

Description

plan = buildplan creates a plan and returns it as a matlab.buildtool.Plan object. You can then configure the plan by adding tasks to plan.

To add a Task object t to plan, use the plan("taskName") = t syntax.

plan = buildplan(fcns) creates a plan with tasks corresponding to the list of task functions fcns. You can use this syntax only within a build file.

Examples

Create Plan Using Task Functions

Create a plan with tasks corresponding to local task functions in a build file.

Open the example and then navigate to the buildplan_example folder, which contains a build file.

openExample("matlab/CreatePlanUsingTaskFunctionsExample")
cd buildplan_example

This code shows the contents of the build file.

function plan = buildfile
% Create a plan from the task functions
plan = buildplan(localfunctions);

% Make the "test" task the default task in the plan
plan.DefaultTasks = "test";
end

function checkTask(~)
% Identify code issues
issues = codeIssues;
assert(isempty(issues.Issues),formattedDisplayText( ...
    issues.Issues(:,["Location" "Severity" "Description"])))
end

function testTask(~)
% Run unit tests
results = runtests(IncludeSubfolders=true,OutputDetail="terse");
assertSuccess(results);
end

List the tasks in the plan returned by the main function of the build file.

buildtool -tasks

check - Identify code issues
test  - Run unit tests

Run the default task in the plan. The build tool runs the "test" task. In this example, all the tests pass, and the task runs successfully.

buildtool

** Starting test
...
** Finished test

Create Plan Using Task Objects

Create a plan with no tasks, and then add tasks to the plan.

Open the example and then navigate to the buildplan_example1 folder, which contains a build file.

openExample("matlab/CreatePlanWithNoTasksExample")
cd buildplan_example1

This code shows the contents of the build file. Note that adding a Task object t to plan requires the plan("taskName") = t syntax.

function plan = buildfile
import matlab.buildtool.Task
% Create a plan with no tasks
plan = buildplan;

% Create the "check" task and add it to the plan
plan("check") = Task( ...
    Description="Identify code issues", ...
    Actions=@check);

% Create the "test" task and add it to the plan
plan("test") = Task( ...
    Description="Run unit tests", ...
    Actions=@test);

% Make the "test" task the default task in the plan
plan.DefaultTasks = "test";
end

% Helper functions
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

List the tasks in the plan returned by the build file.

buildtool -tasks

check - Identify code issues
test  - Run unit tests

Run the default task in the plan. The build tool runs the "test" task. In this example, all the tests pass, and the task runs successfully.

buildtool

** Starting test
...
** Finished test

Input Arguments

fcns — List of task functions

cell vector of function handles

List of task functions, specified as a cell vector of function handles. A task function is a local function in the build file whose name ends with the word "Task", which is case insensitive. The build tool takes into account only the elements of fcns that follow the task function naming convention.

To automatically generate a cell vector of function handles from all the task functions in your build file, specify fcns as localfunctions.

Example: localfunctions

Example: {@compileTask,@testTask}

More About

Task Functions

Task functions are local functions in the build file whose names end with the word "Task", which is case insensitive. A task function must accept a TaskContext object as its first input, even if the task ignores it. The build tool automatically creates this object, which includes information about the plan as well as the task being run.

The build tool generates task names from task function names by removing the "Task" suffix. For example, a task function testTask results in a task named "test". Additionally, the build tool treats the first help text line, often called the H1 line, of the task function as the task description. The code in the task function corresponds to the action performed when the task runs.

Version History

Introduced in R2022b