buildtool

Invoke build tool

Since R2022b

collapse all in page

Syntax

buildtool

buildtool tasks

buildtool ___ option1 ... optionN

buildtool -tasks

buildtool -tasks all

buildtool -init

Description

Run Tasks

buildtool invokes the build tool on the build file in your project. It runs the default tasks in the plan defined by the build file as well as all the tasks on which they depend.

By default, the command searches for a build file named buildfile.m in your current folder or its parent folders. If the build file does not exist in your current folder, the command searches through the parent folders until it finds buildfile.m.

example

buildtool tasks runs the specified tasks as well as all the tasks on which they depend. The command runs the tasks in the order specified. It runs each task at most one time and ignores a task in the list that has already run.

example

buildtool ___ option1 ... optionN specifies build options in addition to any of the input argument combinations in previous syntaxes. For example, buildtool -continueOnFailure continues running the build upon a failure.

example

List Tasks

buildtool -tasks lists the tasks in your build file. The list includes task names and descriptions.

example

buildtool -tasks all also lists the tasks in task groups. For more information about task groups, see Create Groups of Similar Tasks. (since R2024b)

Create Build File

buildtool -init creates a build file named buildfile.m in your current folder (if one does not exist). The build file contains tasks created from built-in task classes in the matlab.buildtool.tasks namespace. You can use this build file as a starting point to define your build. (since R2024a)

Examples

collapse all

List and Run Tasks in Plan

Open Live Script

Invoke the build tool to list and run the tasks in the plan returned by a build file.

Open the example and then navigate to the buildtool_example folder, which contains a build file.

cd buildtool_example

This code shows the contents of the build file.

function plan = buildfile
import matlab.buildtool.tasks.*

plan = buildplan(localfunctions);

plan("check") = CodeIssuesTask;    % Task for identifying code issues
plan("test") = TestTask;           % Task for running tests

plan.DefaultTasks = ["check" "test"];
end

List the tasks in the plan returned by the main function of the build file.

buildtool -tasks

check - Identify code issues
test  - Run tests

Run the default tasks in the plan. The build tool runs the "check" and "test" tasks. In this example, the tasks run successfully.

buildtool

** Starting check

Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
           Info: 0 (Threshold: Inf)
** Finished check

** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.60934 seconds testing time.
                 
** Finished test

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    18.376 sec total build time

Now, run only the "test" task.

buildtool test

** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.057125 seconds testing time.
                 
** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    3.4923 sec total build time

Run Task with Arguments

Open Live Script

Run a task that accepts arguments to customize its actions.

Open the example and then navigate to the buildtool_example1 folder, which contains a build file.

cd buildtool_example1

This code shows the contents of the build file. The build file specifies a "test" task that accepts an optional argument, tests, as well as a name-value argument, OutputDetail.

function plan = buildfile
% Create a plan from task functions
plan = buildplan(localfunctions);
end

function testTask(context,tests,options)
% Run unit tests

arguments
    context
    tests string = context.Plan.RootFolder
    options.OutputDetail (1,1) string = "terse"
end

results = runtests(tests, ...
    IncludeSubfolders=true, ...
    OutputDetail=options.OutputDetail);
assertSuccess(results);
end

Use the "test" task to run the tests in the tests subfolder of your current folder. In this example, the tests pass and the task runs successfully.

buildtool test("tests")

** Starting test
...
** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    1.4456 sec total build time

Run the tests again and display test run progress at the "concise" level.

buildtool test("tests",OutputDetail="concise")

** Starting test
Running SolverTest
...
Done SolverTest
__________

** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    1.0156 sec total build time

Create and Run Tasks with Inputs and Outputs

Open Live Script

Create and run tasks that have inputs and outputs.

Open the example and then navigate to the incremental_build_example folder, which contains a build file.

cd incremental_build_example

This code shows the contents of the build file:

The "pcode" task obfuscates its inputs and creates the P-code files in the same folders as the inputs. (For illustrative purposes, the "pcode" task in this example is created using a task function. The recommended practice is to create the task using the matlab.buildtool.tasks.PcodeTask class.)
The "archive" task creates an archive of its inputs.

function plan = buildfile
% Create a plan from the task functions
plan = buildplan(localfunctions);

% Specify the inputs and outputs of the "pcode" task
plan("pcode").Inputs = "source/**/*.m";
plan("pcode").Outputs = plan("pcode").Inputs.replace(".m",".p");

% Specify the inputs and outputs of the "archive" task
plan("archive").Inputs = plan("pcode").Outputs;
plan("archive").Outputs = "source.zip";
end

function pcodeTask(context)
% Create P-code files
filePaths = context.Task.Inputs.paths;
pcode(filePaths{:},"-inplace")
end

function archiveTask(context)
% Create ZIP file
task = context.Task;
zip(task.Outputs.paths,task.Inputs.paths)
end

Run the "archive" task. Because the inputs of the "archive" task are the outputs of the "pcode" task, the build tool runs the "pcode" task before running the "archive" task.

buildtool archive

** Starting pcode
** Finished pcode

** Starting archive
** Finished archive

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    0.37189 sec total build time

Run the "archive" task again. The build tool skips both of the tasks because none of the inputs or outputs of the tasks have changed.

buildtool archive

** Skipped pcode (up-to-date)

** Skipped archive (up-to-date)

Build Successful:
    2 Tasks: 0 Failed, 2 Skipped
    0.11112 sec total build time

Add a file to the source folder, and then rerun the "archive" task. The build tool runs the "pcode" task because its inputs have changed. The build tool also runs the "archive" task because its inputs have changed.

fclose(fopen(fullfile("source","newFile.m"),"w"));
buildtool archive

** Starting pcode
** Finished pcode

** Starting archive
** Finished archive

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    0.34168 sec total build time

Delete the ZIP file created by the "archive" task, and then run the task while displaying build output at the matlab.automation.Verbosity.Detailed level. The build tool skips the "pcode" task because none of its inputs or outputs have changed. However, the build tool runs the "archive" task because its output has changed. When displaying build output at the Detailed level or above, the build tool includes the reason that a task runs.

delete("source.zip") 
buildtool archive -verbosity Detailed

** Skipped pcode (up-to-date)

** Starting archive because:
** --> Outputs modified
**     --> Files deleted: 'source.zip'
**  Evaluating task action: archiveTask
** Finished archive in 0.062955 seconds

Build Successful:
    2 Tasks: 0 Failed, 1 Skipped
    0.56945 sec total build time

Run Tasks in Parallel

Since R2026a

Run the tasks in a build file in parallel (requires Parallel Computing Toolbox™).

Create a build file named buildfile.m with the following code as its contents. For illustrative purposes, this build file has five basic tasks with no actions. The default task, "t1", in the plan depends on the "t2", "t3", and "t5" tasks. Additionally, the "t3" task depends on the "t4" task.

function plan = buildfile
import matlab.buildtool.Task

% Create a plan with no tasks
plan = buildplan;

% Create tasks and add them to the plan
for i = 1:5
    plan("t" + i) = Task;
end

% Specify task dependencies
plan("t1").Dependencies = ["t2" "t3" "t5"];
plan("t3").Dependencies = "t4";

% Make the "t1" task the default task in the plan
plan.DefaultTasks = "t1";
end

Plot the tasks in the build file as a dependency graph. Because of the task dependencies in the build file, the task graph is composed of three branches that can run in parallel.

plot(buildfile)

Dependency graph that shows the five tasks in the build file on three branches

Run the default task and its dependencies in parallel by specifying the -parallel build option. The build tool schedules the tasks to run on different workers in the current parallel pool. Tasks with dependencies start running only after their dependencies have finished.

buildtool -parallel

Connected to parallel pool with 6 workers.
== Scheduled t2 (Worker 1)

== Scheduled t4 (Worker 2)

== Scheduled t5 (Worker 3)

== Completed t2 (Worker 1)
** Done t2

== Completed t5 (Worker 3)
** Done t5

== Completed t4 (Worker 2)
** Done t4

== Scheduled t3 (Worker 1)

== Completed t3 (Worker 1)
** Done t3

== Scheduled t1 (Worker 1)

== Completed t1 (Worker 1)
** Done t1

Build Successful:
    5 Tasks: 0 Failed, 0 Skipped
    1.3501 sec total build time

Input Arguments

collapse all

`tasks` — Tasks to run
strings

Tasks to run, specified as one or more strings. If a task accepts arguments, enclose them in parentheses.

Example: test

Example: compile test

Example: check test("myFolder",OutputDetail="concise") archive("source.zip")

`option1 ... optionN` — Build options
strings

Build options, specified as one or more values in this table. Options can appear in any order.

Option	Description
`-buildFile path` (since R2024b)	Run the build using the specified build file. You can specify a relative path (relative to the current folder) or an absolute path to the build file or the folder that contains the build file. If you specify a folder path, then the build file must be named `buildfile.m` and be directly under the folder. Example: `-buildFile mySubfolder\buildfile.m` Example: `-buildFile C:\work`
`-continueOnFailure` (since R2023b)	Continue running the build upon a build environment setup or task failure. By default, the build runner terminates the build if a failure occurs. Use `-continueOnFailure` to run the subsequent tasks upon a failure.
`-parallel` (since R2024a)	Run the tasks in parallel (requires Parallel Computing Toolbox). The build tool runs the tasks using the process-based parallel pool returned by the `gcp` (Parallel Computing Toolbox) function. The build tool considers task dependencies when scheduling a task to run in parallel. A task starts running in the parallel pool only after its dependencies have finished. Running a build in parallel is most efficient for large task graphs where the number of tasks is high relative to the number of dependencies. For example, a task that is depended on by several other tasks can pose a bottleneck, limiting the number of tasks that can run before it finishes. In general, the build tool schedules tasks in the build to run on MATLAB^® workers. However, certain built-in tasks have special requirements that force them to run on the MATLAB client rather than a worker in the parallel pool. For instance, a `matlab.buildtool.tasks.TestTask` instance implements its own parallelism and always runs on the client in the parallel pool. Before R2026a: This option affects only `TestTask` instances. The build tool runs the tests associated with `TestTask` instances in parallel.
`-skip task` (since R2023b)	Skip the task named `task`. To skip multiple tasks, specify the `-skip` option for each task. Example: `-skip test` Example: `-skip check -skip test`
`-ui` (since R2026a)	Display results from running tasks using the user interface selected in the Run Build section on the MATLAB Toolstrip. For more information about the Run Build section and the available build options that you can control interactively, see Run Build from Toolstrip. Currently, the only supported user interface is the Test Browser app, which corresponds to the Use Test Browser option from the toolstrip. If Use Test Browser is selected, then the `-ui` option enables the results of tests associated with `matlab.buildtool.tasks.TestTask` instances to appear in the test browser. For example, `buildtool test -ui` displays test results from a `TestTask` instance named `"test"` in the test browser, provided that the Use Test Browser option is already selected from the toolstrip.
`-verbosity level` (since R2024b)	Display build output at the specified verbosity level. You can control the amount of information displayed during a build run by specifying `level` as `None`, `Terse`, `Concise`, `Detailed`, or `Verbose`. These levels correspond to the members of the `matlab.automation.Verbosity` enumeration class. By default, the build tool displays build output at the `Concise` level. Example: `-verbosity Terse`

Example: -buildFile mySubfolder\buildfile.m -ui

Example: -continueOnFailure -skip check -skip test

Example: -parallel -verbosity Terse

Tips

To maintain valid relative paths in tasks at run time, the build tool changes the current folder to the plan root folder before running the build and restores the current folder to its original state after running the build. To prevent a task from affecting subsequent tasks by changing the current folder, the build tool also restores the current folder after running each task.

Version History

Introduced in R2022b

expand all

R2026a: Run tasks in parallel

If you specify the -parallel build option, the buildtool command runs tasks on the MATLAB client and workers in the current parallel pool (requires Parallel Computing Toolbox).

In previous releases, if you specify the -parallel option, all the tasks run in serial on the MATLAB client and the option affects only the behavior of matlab.buildtool.tasks.TestTask instances. If you specify the -parallel option in previous releases, TestTask instances use the parallelism of the MATLAB unit testing framework to run their tests in parallel.

R2026a: Display test results in Test Browser

To display the results of tests associated with matlab.buildtool.tasks.TestTask instances in the Test Browser app, specify the -ui build option. To display test results using this option, you must first opt in to using the test browser from the Run Build section on the MATLAB Toolstrip.

R2026a: View summary of build

When you run a build using the buildtool command, the build output concludes with a build summary. The summary includes the outcome and duration of the build. If you display build output at the matlab.automation.Verbosity.Concise level or above, the build summary also provides an overview of task execution.

R2025a: Automatically open MATLAB project when loading build file

If your build file is in a MATLAB project folder, including any subfolder, and that project is not already open, then the buildtool command automatically opens the project before running the main function of the build file and leaves the project open after running the build.

In previous releases, the command opens the project only if the build file is in the project root folder. It opens the project after running the main function of the build file and closes the project after running the build.

R2025a: Display why tasks run

If you display build output using the -verbosity option at the Detailed or Verbose level, then the build tool includes the reason for running each task.

R2024b: Specify build file and verbosity level

You can specify additional options when running a build:

To run a build using a specified build file, use the -buildFile option.
To control the amount of information displayed during a build run, use the -verbosity option.

R2024b: List tasks in task groups

To display a list of tasks in your build file including the tasks in task groups, execute buildtool -tasks all.

R2024a: Run tests in parallel

To run the tests associated with matlab.buildtool.tasks.TestTask instances in parallel, use the -parallel option (requires Parallel Computing Toolbox).

R2024a: Create initial build file

To create a build file named buildfile.m in your current folder, execute buildtool -init.

R2023b: Automatically open MATLAB project when running build

If your build file is in the root folder of a MATLAB project that is not already open, the build tool automatically opens the project before running the build and then closes the project after the build runs.

R2023b: Invoke build tool from project subfolders

You can call the buildtool command from the folder containing the build file or any of its subfolders. In previous releases, you can call buildtool only when the build file is in your current folder.

R2023b: Run tasks using build options

You can use build options to run tasks:

To run the subsequent tasks upon a build environment setup or task failure, use the -continueOnFailure option.
To specify a task to skip, use the -skip option.

R2023b: Build tool restores the current folder after running each task

To prevent a task from affecting subsequent tasks by changing the current folder, the build tool restores the current folder after running each task. In previous releases, the build tool does not restore the current folder after running each task.

R2023a: Specify task arguments

The build tool lets you create and run tasks that accept arguments. You can use task arguments to customize the actions that tasks perform when they run. For more information, see Create Tasks That Accept Arguments.

buildtool

Syntax

Description

Run Tasks

List Tasks

Create Build File

Examples

List and Run Tasks in Plan

Run Task with Arguments

Create and Run Tasks with Inputs and Outputs

Run Tasks in Parallel

Input Arguments

`tasks` — Tasks to run
strings

`option1 ... optionN` — Build options
strings

Tips

Version History

R2026a: Run tasks in parallel

R2026a: Display test results in Test Browser

R2026a: View summary of build

R2025a: Automatically open MATLAB project when loading build file

R2025a: Display why tasks run

R2024b: Specify build file and verbosity level

R2024b: List tasks in task groups

R2024a: Run tests in parallel

R2024a: Create initial build file

R2023b: Automatically open MATLAB project when running build

R2023b: Invoke build tool from project subfolders

R2023b: Run tasks using build options

R2023b: Build tool restores the current folder after running each task

R2023a: Specify task arguments

See Also

Functions

Classes

Namespaces

Topics

buildtool

Syntax

Description

Run Tasks

List Tasks

Create Build File

Examples

List and Run Tasks in Plan

Run Task with Arguments

Create and Run Tasks with Inputs and Outputs

Run Tasks in Parallel

Input Arguments

tasks — Tasks to run strings

option1 ... optionN — Build options strings

Tips

Version History

R2026a: Run tasks in parallel

R2026a: Display test results in Test Browser

R2026a: View summary of build

R2025a: Automatically open MATLAB project when loading build file

R2025a: Display why tasks run

R2024b: Specify build file and verbosity level

R2024b: List tasks in task groups

R2024a: Run tests in parallel

R2024a: Create initial build file

R2023b: Automatically open MATLAB project when running build

R2023b: Invoke build tool from project subfolders

R2023b: Run tasks using build options

R2023b: Build tool restores the current folder after running each task

R2023a: Specify task arguments

See Also

Functions

Classes

Namespaces

Topics

`tasks` — Tasks to run
strings

`option1 ... optionN` — Build options
strings