Create and Run Tasks Using Build Tool

Since R2022b

The build tool provides a standard programming interface to create and run build tasks, such as identifying code issues, running tests, and packaging a toolbox. This example shows how to use the build tool to create a simple plan with tasks, visualize task dependencies, and then run the tasks. In this example, you create a build file containing a main function and a local function. The main function creates a plan with tasks specified by the local task function as well as built-in task classes in the matlab.buildtool.tasks namespace. When you invoke the build tool on the build file, it runs the tasks in an order that accounts for their dependencies.

Create Build File

In your current folder, create a build file named buildfile.m that contains a main function and a local function. Use the main function to create a plan with tasks and specify the default task and task dependencies. Use the local function to specify a task that is not available through built-in task classes. For the complete code in the build file, see Summary of Build File.

Add Main Function

In the build file, define a main function that creates a plan using the buildplan function. Call the buildplan function with localfunctions as the input so that the build tool automatically adds the tasks corresponding to any local task functions to the plan.

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

The classes in the matlab.buildtool.tasks namespace provide the flexibility to create common tasks tailored to your build requirements. Create tasks from these classes and add them to the plan:

Use the CodeIssuesTask class to add a task that identifies code issues in the current folder and its subfolders and fails the build if any errors are found.
Use the TestTask class to add a task that runs the tests in the current folder and its subfolders and fails the build if any of the tests fail.

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

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

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

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

The main function of the build file returns a Plan object that contains the Task objects corresponding to the tasks in the plan.

Add Task Function

If a task is not available through built-in task classes, specify it by adding a task function to the build file. Task functions are local functions in the build file whose names end with the word "Task", which is case insensitive. Make sure the first input to the task function is a TaskContext object, which the task can ignore if its action does not require it. The build tool automatically creates this object, which includes information about the plan as well as the task being run.

For instance, add a task function to create an archive of the current folder. The name of the task is the name of the task function without the "Task" suffix. In this example, the task function archiveTask results in a task named "archive". Additionally, the build tool treats the first help text line, often called the H1 line, of the task function as the task description.

function archiveTask(~)
% Create ZIP file
filename = "source_" + ...
    string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
zip(filename,"*")
end

Specify Default Task and Task Dependencies

After adding the tasks, specify the default task and task dependencies in the main function. Make the "archive" task the default task in the plan. Also, make the "archive" task dependent on the "check" and "test" tasks. The order of task names does not matter. Before the build tool runs a task, it first runs its depended-on tasks.

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

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

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

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

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

% Make the "archive" task dependent on the "check" and "test" tasks
plan("archive").Dependencies = ["check" "test"];
end

Summary of Build File

This code shows the complete contents of the file buildfile.m in your current folder.

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

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

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

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

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

% Make the "archive" task dependent on the "check" and "test" tasks
plan("archive").Dependencies = ["check" "test"];
end

function archiveTask(~)
% Create ZIP file
filename = "source_" + ...
    string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
zip(filename,"*")
end

Visualize Task Dependencies

To visualize the task dependencies, you can create a dependency graph of the plan using the plot method. Graph nodes represent tasks and edges represent dependencies. In this case, there are three tasks and two dependencies.

plan = buildfile;
plot(plan)

Graph representing the "check", "test", and "archive" tasks and their dependencies

When calling the main function of the build file directly, make sure your current folder is the folder containing the build file so that any relative paths used by the main function resolve correctly. Alternatively, use the load static method to load a plan from the build file.

Run Tasks in Plan

You can run the tasks in the plan defined by a build file using the buildtool command.

First, list the tasks in the file buildfile.m in your current folder. The list includes task names and descriptions.

buildtool -tasks

archive - Create ZIP file
check   - Identify code issues
test    - Run tests

Run the "test" task. In this example, all the tests pass, and the task runs successfully. Your results might vary, depending on the tests in your current folder and its subfolders.

buildtool test

** Starting test
...

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

Now, run the default task in the plan. When you invoke the build tool without specifying a task, the build tool runs the default tasks. In this example, the build tool first runs both dependencies of the "archive" task and then performs the action specified by the archiveTask task function.

buildtool

** 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.02066 seconds testing time.
                 
** Finished test

** Starting archive
** Finished archive

Alternatively, if you want to programmatically access the result of the build, use the run method to run the plan.

result = run(plan);