Create and Run Tasks Using Build Tool
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 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 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
Run Tasks in Build File
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
You can also run the tasks in your build file interactively from the MATLAB® Toolstrip. For more information, see Run Build from Toolstrip. (since R2025a)