run

Class: matlab.buildtool.Plan
Package: 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)

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.

To maintain valid relative paths in tasks at run time, the build tool first changes the current folder to the root folder of the plan. Once the run is complete, the build tool restores the current folder to its original state.

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.

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 taskName is a string scalar or character vector, you can specify the task arguments directly within a cell vector.

Example: {arg1,arg2,arg3}

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

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.

openExample("matlab/RunTasksAndAccessBuildResultExample")
cd run_plan_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

Load the plan from the build file.

plan = buildfile

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

result1 = run(plan);

** Starting check
** Finished check

** Starting test
...
** Finished test

** Starting archive
** Finished archive

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

result2 = run(plan,["check" "test"]);

** Starting check
** Finished check

** Starting test
...
** Finished test

Display the most recent build result.

disp(result2)

  BuildResult with properties:

         Failed: 0
       Duration: 0.37576 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.

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

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

Version History

Introduced in R2022b

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.