buildtool

Invoke build tool

Since R2022b

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.

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.

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.

List Tasks

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

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

List and Run Tasks in Plan

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.CodeIssuesTask
import matlab.buildtool.tasks.TestTask

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

% Add the "check" task to identify code issues
plan("check") = CodeIssuesTask;

% Add the "test" 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

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

buildtool -tasks

archive - Create ZIP file
check   - Identify code issues
test    - Run tests

Run the default task in the plan. The build tool runs the "archive" task as well as both the tasks on which it depends. In this example, the tasks run successfully.

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.063807 seconds testing time.
                 
** Finished test

** Starting archive
** Finished archive

Now, run only the "check" and "test" tasks.

buildtool check test

** 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.037478 seconds testing time.
                 
** Finished test

Run Task with Arguments

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

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

Create and Run Tasks with Inputs and Outputs

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

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)

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

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.031559 seconds

Input Arguments

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 build in parallel (requires Parallel Computing Toolbox™). Currently, this option affects only how matlab.buildtool.tasks.TestTask instances run. If you specify the -parallel option, 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
-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. Example: -verbosity Terse

Example: -buildFile mySubfolder\buildfile.m

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

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.