buildplan

Create build plan

Since R2022b

Syntax

plan = buildplan

plan = buildplan(fcns)

Description

plan = buildplan creates a build plan that you can configure by adding tasks.

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 Built-In Tasks

Create a plan with no tasks, and then add built-in tasks from the matlab.buildtool.tasks namespace to the plan.

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

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.tasks.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

% Create a plan with no tasks
plan = buildplan;

% Add the "check" task to identify code issues
plan("check") = CodeIssuesTask;

% Add the "test" task to run tests
plan("test") = TestTask;

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

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

buildtool -tasks

check - Identify code issues
test  - Run 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
...

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

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    1.667 sec total build time

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.

cd buildplan_example

This code shows the contents of the build file. The task functions in this example are only for illustrative purposes. To define your build more efficiently, use the built-in tasks from the matlab.buildtool.tasks namespace instead.

function plan = buildfile
% Create a plan from 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

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    0.69721 sec total build time

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}

Output Arguments

plan — Build plan

matlab.buildtool.Plan object

Build plan, returned as a matlab.buildtool.Plan object.

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