buildtool

Invoke build tool

Since R2022b

Syntax

buildtool

buildtool task1 ... taskN

buildtool -tasks

Description

buildtool invokes the build tool on the file buildfile.m in your current folder. It runs the default tasks in the plan returned by the build file as well as all the tasks on which they depend.

buildtool task1 ... taskN runs the tasks task1 ... taskN 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 -tasks lists all the tasks in the build plan. The list includes task names as well as task descriptions.

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.

openExample("matlab/ListAndRunTasksInPlanExample")
cd buildtool_example

This code shows the contents of the build file.

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

% 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 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

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 unit 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
** Finished check

** Starting test
...
** Finished test

** Starting archive
** Finished archive

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

buildtool check test

** Starting check
** Finished check

** Starting test
...
** 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.

openExample("matlab/RunTaskThatAcceptsArgumentsExample")
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 the 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

Run Tasks That Support Incremental Builds

Run tasks that specify inputs and outputs to support incremental builds.

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

openExample("matlab/RunTasksThatSupportIncrementalBuildsExample")
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.

• 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 = "source/**/*.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. 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.

delete("source.zip") 
buildtool archive

** Skipped pcode: up-to-date

** Starting archive
** Finished archive

Input Arguments

task1 ... taskN — Tasks to run

string scalars | character vectors

Tasks to run, specified as one or more string scalars or character vectors. If a task accepts arguments, enclose them in parentheses.

Example: test

Example: compile test

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

Version History

Introduced in R2022b

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 and Run Tasks That Accept Arguments.