Main Content

padv.builtin.task.RunBuildTool Class

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

Task for executing MATLAB build tool plan

Since R2023b

Description

This class requires CI/CD Automation for Simulink Check.

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.

example

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

expand all

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

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

expand all

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

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

Example: "MyMATLABBuildToolTask"

Data Types: string

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

Example: "My MATLAB Build Tool Task"

Data Types: 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

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

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.

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

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

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

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

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

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.

Methods

expand all

Examples

collapse all

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