run

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

Run build using runner configured for text output

Since R2022b

expand all in page

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.

example

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

example

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.

example

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.

example

Input Arguments

expand all

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

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"]

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

expand all

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)

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.

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

expand all

Open Live Script

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)
           Info: 0 (Threshold: Inf)
** Finished check

** Starting test
...

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

** Starting archive
** Finished archive

Build Successful:
    3 Tasks: 0 Failed, 0 Skipped
    1.8397 sec total build time

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)
           Info: 0 (Threshold: Inf)
** Finished check

** Starting test
...

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

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

Run the default task and its dependencies, excluding the "check" task.

result3 = run(plan,Skip="check");
** Skipped check (user requested)

** Starting test
...

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

** Starting archive
** Finished archive

Build Successful:
    3 Tasks: 0 Failed, 1 Skipped
    1.1644 sec total build time

Display the most recent build result.

disp(result3)
  BuildResult with properties:

         Failed: 0
       Duration: 1.1644 sec
    TaskResults: [1×3 matlab.buildtool.TaskResult]

Return the result for the "check" task by accessing the TaskResults property of the build result. The Skipped property of the corresponding TaskResult object indicates that the task was skipped, and the SkipReason property specifies the reason for skipping the task.

result3.TaskResults(1)
ans = 
  TaskResult with properties:

          Name: "check"
        Failed: 0
      UpToDate: 0
       Skipped: 1
    SkipReason: UserRequested
      Duration: 00:00:00
Open Live Script

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

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

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

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

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

See Also

Functions

Classes

Topics