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 one main function and three local functions. The main function creates a plan of tasks whose actions are specified by the local functions. When you invoke the build tool on the build file, it runs the tasks by taking into account their dependencies.

Create Build File

In your current folder, create a build file named buildfile.m that contains a main function and three local functions. Use the main function to create the plan and specify the default task and task dependencies. Use the local functions to specify the action each task performs when it runs. 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 adds tasks to the plan based on the local task functions you define.

function plan = buildfile
plan = buildplan(localfunctions);
end

The main function of the build file returns a Plan object that contains the Task objects corresponding to the task functions.

Add Task Functions

Specify the tasks in the plan by adding task functions 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 example, add a task function to identify code issues in the current folder and its subfolders and fail the build if any issues are found.

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

Add a task function to run the tests in the current folder and its subfolders and fail the build if any of the tests fail.

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

Add a task function to create an archive of the current folder.

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

Specify Default Tasks and Task Dependencies

After adding the task functions, specify the default task and task dependencies in the main function. The name of the task is the name of the task function without the "Task" suffix. For example, the task function archiveTask results in a task named "archive". 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
plan = buildplan(localfunctions);
plan.DefaultTasks = "archive";
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
plan = buildplan(localfunctions);
plan.DefaultTasks = "archive";
plan("archive").Dependencies = ["check" "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

function archiveTask(~)
% Create ZIP file
zipFileName = "source_" + ...
    string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
zip(zipFileName,"*")
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)

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

When you create a plan with tasks using the file buildfile.m in your current folder, you can list or run the tasks in the plan with the buildtool command.

First, list the available tasks. The list includes task names and descriptions. The build tool treats the first help text line, often called the H1 line, of the task function as the task description.

buildtool -tasks

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

Run the "test" task. The build tool performs the action specified by the testTask task function. In this example, all the tests pass, and the task runs successfully. Your results might vary, depending on the tests contained in your current folder and its subfolders.

buildtool test

** Starting test
...
** 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
** Finished check

** Starting test
...
** 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);