Main Content

Create 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 returns a plan with three tasks named "check", "test", and "archive". Specify the "check" task using the CodeIssuesTask built-in task class, and specify the configurable "test" and "archive" tasks using the testTask and archiveTask local task functions. For information on how to create a build file using built-in task classes and local 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

  • Adds a built-in task to the created plan that identifies code issues in the current folder and its subfolders and fails the build if any errors are found

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

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

function plan = buildfile
import matlab.buildtool.tasks.CodeIssuesTask

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

% Add a task to identify code issues
plan("check") = CodeIssuesTask;

% 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

Add Task Functions

If you cannot use the built-in task classes in the matlab.buildtool.tasks namespace to achieve your goals, specify tasks 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 testTask task function to run the specified tests and fail the build if any of the tests fail. Even though the TestTask class provides a built-in task for running tests, you cannot configure the task at run time. To customize the task action at run time, use an optional argument, tests, as well as a name-value argument, OutputDetail, in the task function. 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
import matlab.buildtool.tasks.CodeIssuesTask

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

% Add a task to identify code issues
plan("check") = CodeIssuesTask;

% 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 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 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
Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
** 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
Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
** 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
Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
** 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"}});

See Also

Functions

Classes

Namespaces

Related Topics