run

Class: matlab.buildtool.Plan
Namespace: matlab.buildtool

Run build using runner configured for text output

Since R2022b

Syntax

result = run(plan)

result = run(plan,taskName)

result = run(plan,taskName,taskArgs)

result = run(___,Name=Value)

Description

result = run(plan) runs tasks in the plan using a build runner that is configured for text output. It runs the default tasks in the plan as well as all the tasks on which they depend. The text output includes build progress as well as diagnostics in the event of build failures. The method returns the result of the build as a matlab.buildtool.BuildResult object.

result = run(plan,taskName) runs the task named taskName as well as all the tasks on which it depends.

result = run(plan,taskName,taskArgs) passes the task arguments to the specified task. Use this syntax to customize the actions that tasks perform when they run.

result = run(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, result = run(plan,ContinueOnFailure=true) continues running the build upon a failure.

Input Arguments

plan — Plan

matlab.buildtool.Plan object

Plan, specified as a matlab.buildtool.Plan object.

taskName — Name of task to run

string vector | character vector | cell vector of character vectors

Name of the task to run, specified as a string vector, character vector, or cell vector of character vectors. The build runner runs the specified task as well as all the tasks on which it depends.

Example: "compile"

Example: ["compile" "test"]

taskArgs — Arguments to pass to task

cell vector of cell vectors

Arguments to pass to taskName, specified as a cell vector of cell vectors, where each nested cell vector specifies the arguments of the corresponding element of taskName. If you specify arguments directly within a single cell vector, then the method passes all the arguments in that cell vector to each task in taskName.

Example: {{task1_arg1,task1_arg2},{task2_arg}}

Example: {arg1,arg2,arg3}

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: result = run(plan,ContinueOnFailure=true)

ContinueOnFailure — Option to continue running the build upon failure

false or 0 (default) | true or 1

Option to continue running the build upon a build environment setup or task failure, specified as a numeric or logical 0 (false) or 1 (true). By default, the method terminates the build and does not run the subsequent tasks if a failure occurs.

Skip — Name of task to skip

string vector | character vector | cell vector of character vectors

Name of the task to skip, specified as a string vector, character vector, or cell vector of character vectors. The method skips the specified task and does not run it.

Example: Skip="test"

Example: Skip=["check" "test"]

Examples

Run Tasks and Access Build Result

Run the tasks in a plan and access the build result.

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

cd run_plan_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

Load the plan from the build file.

plan = buildfile

plan = 
  Plan with 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.

result1 = run(plan);

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

** Starting archive
** Finished archive

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

result2 = run(plan,["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.01121 seconds testing time.
                 
** Finished test

Display the most recent build result.

disp(result2)

  BuildResult with properties:

         Failed: 0
       Duration: 0.6687 sec
    TaskResults: [1×2 matlab.buildtool.TaskResult]

Return the result of running the "check" task by using the TaskResults property.

result2.TaskResults(1)

ans = 
  TaskResult with properties:

        Name: "check"
      Failed: 0
     Skipped: 0
    UpToDate: 0
    Duration: 00:00:00

Run Task with Arguments

Run a task that accepts arguments to customize its actions.

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

cd run_plan_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

Load the plan from the build file.

plan = buildfile

plan = 
  Plan with tasks:

    test - Run unit tests

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.

plan.run("test",{"tests"});

** Starting test
...
** Finished test

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

plan.run("test",{"tests","OutputDetail","concise"});

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

** Finished test

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

R2023b: Automatically open MATLAB project when running builds

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: 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 name-value argument.

• To specify a task to skip, use the Skip name-value argument.

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 run tasks that accept arguments. To specify task arguments when you run a task, use the taskArgs input argument. For more information on how to create and run tasks that accept arguments, see Create and Run Tasks That Accept Arguments.