Overview of MATLAB Build Tool
The MATLAB® build tool is a build system that provides a standard programming interface to create and run tasks in a uniform and efficient way. For example, you can create tasks that identify code issues, run tests, and package a toolbox in a single build file in your project root folder, and then invoke the build tool to run these tasks.
Create Plan with Tasks
To define a build for your project, create a build file in your project root folder. A build file is a function file that creates a plan with tasks. Each task in the plan represents a single unit of work in a build and has three fundamental characteristics:
Name — The name of a task uniquely identifies the task in the plan.
Dependencies — The dependencies of a task are other tasks in the plan that must run before the task runs.
Actions — The actions of a task define functions that execute when the task runs.
To create a plan, include the function call
buildplan(localfunctions)
in the main function of the build
file. Then, add tasks to the plan using built-in task classes or local task functions:
Built-in task classes — In the main function, create tasks from the classes in the
matlab.buildtool.tasks
package and add them to the plan. The classes provide the flexibility to create common tasks tailored to your build requirements.Local task functions — In local task functions, specify the name, optional description, and action of tasks that are not available through built-in task classes. Task functions are local functions in the build file whose names end with the word "Task", which is case insensitive.
For example, in your current folder, create a build file named
buildfile.m
with three tasks. Create the
"check"
and "test"
tasks using built-in
task classes, and create the "archive"
task using a local task
function.
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
For more information on how to create a build file, see Create and Run Tasks Using Build Tool.
Run Tasks in Plan
You can run the tasks in your plan with either the buildtool
command or the run
method of the matlab.buildtool.Plan
class:
buildtool
command — Use this command to run the tasks defined in the filebuildfile.m
in your current folder or its parent folders. You also can use the commandbuildtool -tasks
to list the tasks in your plan. Do not usebuildtool
if you create or modify your plan outside of the filebuildfile.m
, or if you want to programmatically access the result of the build.run
method — Use this method if you create or modify your plan outside of the filebuildfile.m
in your current folder or its parent folders, or if you want to programmatically access the result of the build. The method returns amatlab.buildtool.BuildResult
object, which includes information about the build as well as each task that was part of the build.
To run a task, the build runner first runs all its dependencies and then performs
actions of the task in the order they appear in the Actions
property of the corresponding Task
object.
For example, run the default task in the plan created by the file
buildfile.m
in your current folder. The build tool first runs
the "check"
and "test"
tasks because the
"archive"
task depends on them. Your results might vary,
depending on the files in your current folder and its subfolders.
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.13274 seconds testing time. ** Finished test ** Starting archive ** Finished archive