Main Content

Overview of MATLAB Build Tool

Since R2022b

The build tool provides a standard programming interface to create and run build 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

The recommended approach to defining a build is to create a build file with a main function and task functions. A build file creates a plan that contains the 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 with tasks using a build file, implement these functions in the build file:

  • Main function — Create a plan containing the tasks that correspond to the task functions with buildplan(localfunctions). Additionally, you can specify any default tasks or task dependencies.

  • Task functions — Specify the name, optional description, and action of each task. 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 the file buildfile.m with a main function and three task functions.

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

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 file buildfile.m in your current folder. You also can use the command buildtool -tasks to list the tasks in your plan. Do not use buildtool if you create or modify your plan outside of the file buildfile.m in your current folder, 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 file buildfile.m in your current folder, 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 expected to run.

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 contained in your current folder and its subfolders.

buildtool
** Starting check
** Finished check

** Starting test
...
** Finished test

** Starting archive
** Finished archive

See Also

Functions

Related Topics