Overview of MATLAB Build Tool

Since R2022b

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 namespace 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 using 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 build file for your project. Do not use buildtool if you create or modify your plan outside of the build file 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 build file for your project or if you want to programmatically access the result of the build. The method returns a matlab.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