padv.builtin.task.RunBuildTool Class

Namespace: padv.builtin.task
Superclasses: padv.Task

Task for executing MATLAB build tool plan

Since R2023b

Description

Starting in R2023b, the padv.builtin.task.RunBuildTool class provides a task that can execute specific tasks in a MATLAB^® build tool plan. With the MATLAB build tool, you can create a build plan that identifies code issues, runs tests, and performs other operations. A build file is a function file named buildfile.m that defines a build plan for the MATLAB build tool. For more information, see Build Automation.

You can add the task to your process model by using the method addTask. After you add the task to your process model, you can run the tasks from the Process Advisor app or by using the function runprocess.

To view the source code for this built-in task, in the MATLAB Command Window, enter:

open padv.builtin.task.RunBuildTool

The padv.builtin.task.RunBuildTool class is a handle class.

Creation

Description

task = padv.builtin.task.RunBuildTool(Tasks=taskNames,CleanTask=cleanTaskName) creates a task for executing specific tasks in the MATLAB build tool plan in the project. The cleanTaskName specifies which task deletes outputs and traces of the other tasks in the build file.

task = padv.builtin.task.RunBuildTool(___,Name=Value) sets certain properties using one or more name-value arguments. For example, task = padv.builtin.task.RunBuildTool(Tasks="",CleanTask="",Name="MyMATLABBuildToolTask") creates a Process Advisor task that can execute the default task for the MATLAB build tool, ignores the clean task in the build plan, and names the task "MyMATLABBuildToolTask".

You can use this syntax to set property values for InputQueries, Name, IterationQuery, InputDependencyQuery, AlwaysRun, and TaskArguments.

The padv.builtin.task.RunBuildTool class also has other properties, but you cannot set those properties during task creation.

Input Arguments

taskNames — MATLAB build tool tasks to run

"" | string vector | character vector | cell vector of character vectors

MATLAB build tool tasks to run, specified as a string vector, character vector, or cell vector of character vectors. The build runner for the MATLAB build tool runs the specified task as well as all the tasks on which it depends. To run the default tasks in the MATLAB build plan, you can specify taskNames as "". For the MATLAB build tool, you specify the default task in the build plan by specifying plan.DefaultTasks in the build file.

For more information on the MATLAB build tool and its tasks, see Build Automation.

Example: ""

Example: "archive"

Example: ["check" "pcode" "archive"]

cleanTaskName — Name of MATLAB build tool task to delete outputs and traces of other tasks in build plan

"" | strings

MATLAB build tool task to delete outputs and traces of other tasks in the build plan, specified as one or more strings. When you delete the outputs or the trace of a task, the build tool does not consider the task as up to date. To ignore the clean task in the build file, you can specify cleanTask as "".

For information on the built-in cleaning task for the MATLAB build tool, see matlab.buildtool.tasks.CleanTask.

Properties

The RunBuildTool class inherits properties from padv.Task. The properties listed in Specialized Inherited Properties are padv.Task properties that the RunBuildTool task overrides.

The task also has properties for specifying MATLAB Build Tool Options. The task uses these properties to specify input arguments for the MATLAB build tool API.

Specialized Inherited Properties

Name — Unique identifier for task in process

"padv.builtin.task.RunBuildTool" (default) | string

Unique identifier for task in process, specified as a string.

Example: "MyMATLABBuildToolTask"

Data Types: string

Title — Human-readable name that appears in Process Advisor app

"Run MATLAB Build Tool Tasks" (default) | string

Human-readable name that appears in Process Advisor app, specified as a string.

Example: "My MATLAB Build Tool Task"

Data Types: string

DescriptionText — Task description

"This task runs one or more MATLAB Build Tool Tasks." (default) | string

Task description, specified as a string.

When you point to a task in Process Advisor and click the information icon, the tooltip shows the task description.

Example: "This task invokes the MATLAB build tool for specific tasks."

Data Types: string

DescriptionCSH — Path to task documentation

path to RunBuildTool documentation (default) | string

Path to task documentation, specified as a string.

When you point to a task in Process Advisor, click the ellipsis (...), and click Help, Process Advisor opens the task documentation.

Example: fullfile(pwd,"taskHelpFiles","myTaskDocumentation.pdf")

Data Types: string

IterationQuery — Find artifacts that task iterates over

"" (default) | padv.Query object | name of padv.Query object

Query that finds the artifacts that the task iterates over, specified as a padv.Query object or the name of a padv.Query object. When you specify IterationQuery, the task runs one time for each artifact returned by the query. In the Process Advisor app, the artifacts returned by IterationQuery appear under task title.

For more information about task iterations, see Overview of Process Model.

InputDependencyQuery — Finds artifact dependencies for task inputs

padv.builtin.query.GetDependentArtifacts (default) | padv.Query object | name of padv.Query object

Query that finds artifact dependencies for task inputs, specified as a padv.Query object or the name of a padv.Query object.

The build system runs the query specified by InputDependencyQuery to find the dependencies for the task inputs, since those dependencies can impact if task results are up-to-date.

For more information about task inputs, see Overview of Process Model.

Example: padv.builtin.query.GetDependentArtifacts

AlwaysRun — Always force task to run, even if the task results are already up to date

trueor 1 (default) | false or 0

Always force task to run, even if the task results are already up to date, specified as a numeric or logical 0 (false) or 1 (true).

The RunBuildTool class specifies AlwaysRun as true to allow the MATLAB build tool to determine whether the tasks in the build plan need to be re-run or can be skipped.

Example: 1

Data Types: logical

MATLAB Build Tool Options

Tasks — MATLAB build tool tasks to run

"" | string vector | character vector | cell vector of character vectors

MATLAB build tool tasks to run, specified as a string vector, character vector, or cell vector of character vectors. The build runner for the MATLAB build tool runs the specified task as well as all the tasks on which it depends. To run the default tasks in the MATLAB build plan, you can specify Tasks as "".

The RunBuildTool class passes the task names to the run method of the matlab.buildtool.Plan class.

For more information on the MATLAB build tool and its tasks, see Build Automation.

Example: ""

Example: "archive"

Example: ["check" "pcode" "archive"]

Data Types: cell | char | string

TaskArguments — Arguments to pass to MATLAB build tool tasks

empty cell array (default) | cell array

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

The RunBuildTool class passes these task arguments to the run method of the matlab.buildtool.Plan class.

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

Example: {arg1,arg2,arg3}

Data Types: cell

IncludeOutputs — Include MATLAB build tool task output files in Process Advisor task results

false or 0 (default) | true or 1

Include MATLAB build tool task output files in Process Advisor task results, specified as a numeric or logical true (1) or false (0).

The RunBuildTool class finds the output files from the MATLAB build tool tasks by using the getOutputFilesForTasks method of the padv.util.MbtHelper utility class.

Example: true

Data Types: logical

CleanTask — Name of MATLAB build tool task to delete outputs and traces of other tasks in build plan

"" | strings

MATLAB build tool task to delete outputs and traces of other tasks in the build plan, specified as one or more strings. When you delete the outputs or the trace of a task, the build tool does not consider the task as up to date. To ignore the clean task in the build file, you can specify cleanTask as "".

For information on the built-in cleaning task for the MATLAB build tool, see matlab.buildtool.tasks.CleanTask.

Data Types: string

ContinueOnFailure — Option to continue running the build upon failure

0 (false) (default) | 1 (true)

Option to continue running the build upon failure, specified as a numeric or logical 0 (false) or 1 (true). By default, RunBuildTool stops executing the MATLAB build tool plan and does not run the subsequent MATLAB build tool tasks if a failure occurs.

Example: true

Data Types: logical

Skip — Names of tasks to skip

string vector

Names of tasks to skip, specified as a string vector.

Example: "test"

Example: ["check" "test"]

Data Types: string

Methods

Specialized Public Methods

This class overrides the following inherited methods.

run	Execute the MATLAB build tool for the specified tasks. Note You do not need to manually invoke this method. When you run a task using the Process Advisor app or the runprocess function, the build system automatically invokes the run method for the task. The run method inside this built-in task runs on a task object obj with task input input and returns a task result taskResult. The task result is a padv.TaskResult object that can store the pass, fail, and error information. If you inherit from this built-in task, make sure to use the same method signature inside your custom task. function taskResult = run(obj,input) ... end
dryRun	Dry run the task to validate task inputs and generate representative task outputs without actually running the task. The dryRun method inside this built-in task runs on a task object obj with task input input and returns a task result taskResult. The task result is a padv.TaskResult object that can store the pass, fail, and error information. If you inherit from this class, make sure to use the same method signature inside your custom task. function taskResult = dryRun(obj, input) ... end For more information, see Dry Run Tasks to Test Process Model.
clean	If you specify CleanTask as "", the RunBuildTool class ignores the clean task in the build plan, clears the Process Advisor task results, and deletes Process Advisor task outputs. Otherwise, the RunBuildTool class runs the specified clean task from the build file. The clean method inside this built-in task runs on a task object obj. If you inherit from this class, make sure to use the same method signature inside your custom task: function clean(obj, ~) ... end

Examples

Execute MATLAB Build Tool Tasks

With the MATLAB build tool, you can create a build plan that identifies code issues, runs tests, and performs other operations. A build file is a function file named buildfile.m that defines a build plan for the MATLAB build tool. Suppose that you define a build file for your project. You can use Process Advisor to invoke the MATLAB build tool by adding the built-in task padv.builtin.task.RunBuildTool to your process model. For more information on the MATLAB build tool, see Overview of MATLAB Build Tool.

Open the process model for your project. If you do not have a process model, open the Process Advisor app to automatically create a process model, processmodel.m, at the root of the project.

Open the process model file and add the RunBuildTool task to your process model by using the addTask method. The task requires that you specify the MATLAB build tool tasks that you want to run and the clean task for the build file. For this example, you can have the task run the default task in the build file and ignore the clean task defined in the build file by specifying Tasks and CleanTask as "".

mbtTask = pm.addTask(padv.builtin.task.RunBuildTool(Tasks="",CleanTask=""));

You can reconfigure the task behavior by using the task properties. For example, to include MATLAB build tool task output files in the Process Advisor task results:

mbtTask.IncludeOutputs = true;

Version History

Introduced in R2023b