Create and Run Tasks That Accept Arguments

Since R2023a

You can create configurable build tasks that accept arguments. Task arguments let you customize the actions that tasks perform when they run. This example shows how to create configurable tasks in a build file and then use the build tool to run the tasks by passing arguments to their actions. In this example, you first create a build file containing one task that does not accept any arguments and two tasks that accept arguments. Then, you use the build tool to run different combinations of these tasks.

Create Build File

In your current folder, create a build file named buildfile.m that contains a main function and three local task functions, named checkTask, testTask, and archiveTask, corresponding to the "check", "test", and "archive" tasks. For information on how to create a build file using task functions, see Create and Run Tasks Using Build Tool. For the complete code in the build file used in this example, see Summary of Build File.

Add Main Function

In the build file, define a main function that:

• Creates a plan from the task functions

• Makes the "archive" task the default task in the plan

• Makes the "archive" task dependent on the "check" and "test" tasks

function plan = buildfile
plan = buildplan(localfunctions);
plan.DefaultTasks = "archive";
plan("archive").Dependencies = ["check" "test"];
end

Add Task Functions

Specify the tasks in the plan by adding local task functions to the build file. Make sure the first input to a task function is a TaskContext object, which the task can ignore if its action does not require it. Specify additional inputs if you want to pass arguments to the task actions. Use argument validation to constrain the size, class, and other aspects of the arguments. For information on how to declare specific restrictions on arguments, see Function Argument Validation.

Add the checkTask task function to identify code issues in the current folder and its subfolders and fail the build if any issues are found. The checkTask function in this example does not accept arguments for customizing the task action. Therefore, the action the task performs is the same every time it runs.

function checkTask(~)
% Identify code issues
issues = codeIssues;
assert(isempty(issues.Issues),formattedDisplayText( ...
    issues.Issues(:,["Location" "Severity" "Description"])))
end

Add the testTask task function to run the specified tests and fail the build if any of the tests fail. To customize the task action at run time, use an optional argument, tests, as well as a name-value argument, OutputDetail. Declare the size and class restrictions as well as the default values using an arguments block.

function testTask(~,tests,options)
% Run unit tests
arguments
    ~
    tests string = pwd
    options.OutputDetail (1,1) string = "terse"
end
results = runtests( ...
    tests, ...
    IncludeSubfolders=true, ...
    OutputDetail=options.OutputDetail);
assertSuccess(results);
end

Add the archiveTask task function to create an archive of the current folder. To have control over the name of the ZIP file, use an optional argument, filename.

function archiveTask(~,filename)
% Create ZIP file
arguments
    ~
    filename (1,1) string = "source_" + ...
        string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
end
zip(filename,"*")
end

Summary of Build File

This code shows the complete contents of the file buildfile.m in your current folder.

function plan = buildfile
plan = buildplan(localfunctions);
plan.DefaultTasks = "archive";
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(~,tests,options)
% Run unit tests
arguments
    ~
    tests string = pwd
    options.OutputDetail (1,1) string = "terse"
end
results = runtests( ...
    tests, ...
    IncludeSubfolders=true, ...
    OutputDetail=options.OutputDetail);
assertSuccess(results);
end

function archiveTask(~,filename)
% Create ZIP file
arguments
    ~
    filename (1,1) string = "source_" + ...
        string(datetime("now",Format="yyyyMMdd'T'HHmmss"));
end
zip(filename,"*")
end

Run Tasks with Arguments

You can run the tasks in the plan created in the build file by using the buildtool command or the run method. This section shows different ways of running tasks with or without arguments. In this example, all the tasks run successfully. Your results might vary, depending on the source code and tests contained in your current folder and its subfolders.

Use buildtool Command

Run the default task in the plan. The build tool runs the "archive" task after running its dependencies. Because you invoke the build tool without specifying any task arguments, the tasks perform their basic actions.

buildtool

** Starting check
** Finished check

** Starting test
.....
** Finished test

** Starting archive
** Finished archive

Customize the action performed by the "archive" task by specifying a name for the ZIP file. In the buildtool command, enclose the task argument in parentheses after the task name.

buildtool archive("source.zip")

** Starting check
** Finished check

** Starting test
.....
** Finished test

** Starting archive
** Finished archive

Run all the tasks again, but override the default behavior of the configurable tasks:

• Configure the "test" task to run the tests in a subfolder named myTests in your current folder and display test run progress at the "concise" level.

• Configure the "archive" task to generate a ZIP file with a specific name.

buildtool check test("myTests",OutputDetail="concise") archive("source1.zip")

** Starting check
** Finished check

** Starting test
Running MyTestClass
...
Done MyTestClass
__________

** Finished test

** Starting archive
** Finished archive

Use run Method

Alternatively, you can run tasks by using the run method. For example, run the default task in the plan.

plan = buildfile;
run(plan);

Customize the action performed by the "archive" task by specifying a name for the ZIP file. To specify the task argument in the run method call, use a cell vector.

run(plan,"archive",{"source2.zip"});

Configure the "test" and "archive" tasks, and run them and the nonconfigurable "check" task. Because you must specify the same number of task names and task argument groups in the run method call, use an empty cell array for the "check" task arguments.

run(plan,["check" "test" "archive"], ...
    {{},{"myTests","OutputDetail","concise"},{"source3.zip"}});