padv.builtin.query.GetInputsOfBuildToolTasks Class

Namespace: padv.builtin.query
Superclasses: padv.Query

Query for getting inputs of MATLAB build tool tasks

Since R2023b

Description

The padv.builtin.query.GetInputsOfBuildToolTasks class provides a query that can return the inputs of 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. For more information, see Build Automation.

You can use this query in your process model to find the inputs to your MATLAB build tool tasks. For example, you can use this query as an input query for the built-in task padv.builtin.task.RunBuildTool to pass your MATLAB build tool task inputs as inputs to your Process Advisor tasks.

The padv.builtin.query.GetInputsOfBuildToolTasks class is a handle class.

Creation

Description

query = padv.builtin.query.GetInputsOfBuildToolTasks() creates a query for finding the input files associated with MATLAB build tool tasks.

query = padv.builtin.query.GetInputsOfBuildToolTasks(Name=Value) sets certain properties using one or more name-value arguments. For example, padv.builtin.query.GetInputsOfBuildToolTasks(Tasks=["check" "pcode"]) creates a query that finds the input files for the specified MATLAB build tool tasks for identifying code issues and creating P-code files.

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: padv.builtin.query.GetInputsOfBuildToolTasks(Tasks=["check" "pcode" "archive"])

Name — Unique identifier for query

string

Unique identifier for query, specified as a string.

Example: "FindBuildToolInputs"

Data Types: string

Tasks — MATLAB build tool tasks

string

MATLAB build tool tasks, specified as a string.

When the GetInputsOfBuildToolTasks query runs, the query loads the build plan by using the matlab.buildtool.Plan.load method and validates the tasks that you specify with the Tasks argument against the tasks in the matlab.buildtool.Plan object. For each task that you specified, the query creates padv.Artifact objects for each task input file. By default, these artifacts have the artifact type "other_file" and the digital thread does not track changes to these files.

Example: "check"

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

Data Types: string

Properties

Tasks — MATLAB build tool tasks

string

MATLAB build tool tasks, specified as a string.

When the GetInputsOfBuildToolTasks query runs, the query loads the build plan by using the matlab.buildtool.Plan.load method and validates the tasks that you specify with the Tasks argument against the tasks in the matlab.buildtool.Plan object. For each task that you specified, the query creates padv.Artifact objects for each task input file. By default, these artifacts have the artifact type "other_file" and the digital thread does not track changes to these files.

Example: "check"

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

Data Types: string

Title — Query title

"Input files for MATLAB Build Tool Tasks" (default) | string | character vector

Query title, specified as a string or a character vector.

Example: "Find my build tool task inputs"

Data Types: string

DefaultArtifactType — Default artifact type returned by query

"padv_output_file" (default) | ...

Default artifact type returned by the query, specified as one or more artifact types. To specify multiple values, use an array. For a list of valid digital thread artifact types, see Valid Artifact Types.

Example: "padv_output_file"

Parent — Initial query that runs before iteration query

padv.Query | Name of padv.Query object

Initial query that runs before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify an iteration query for a task, the parent query is the initial query that the build system runs before running the specified iteration query.

By default, the GetInputsOfBuildToolTasks query does not use this property because you cannot use GetInputsOfBuildToolTasks as an iteration query.

Name — Unique identifier for query

string

Unique identifier for query, specified as a string.

Example: "FindBuildToolTaskInputs"

Data Types: string

ShowFileExtension — Show file extensions for returned artifacts

0 (false) | 1 (true)

Show file extensions in the Alias property of returned artifacts, specified as a numeric or logical 1 (true) or 0 (false). The Alias property controls the display name for the artifact in the Tasks column in Process Advisor.

By default, queries strip file extensions from the Alias property of each task iteration artifact. To show file extensions for all artifacts in the Tasks column, select the project setting Show file extensions. To keep file extensions in the results for a specific query, specify the query property ShowFileExtension as true.

Example: true

Data Types: logical

SortArtifacts — Setting for automatically sorting artifacts by address

true or 1 (default) | false or 0

Setting for automatically sorting artifacts by address, specified as a numeric or logical 1 (true) or 0 (false). When a query returns artifacts, the artifacts should be in a consistent order. By default, the build system sorts artifacts by the artifact address.

Alternatively, you can sort artifacts in a different order by overriding the internal sortArtifacts method in a subclass that defines a custom sort behavior. For an example, see Sort Artifacts in Specific Order.

The build system automatically calls the sortArtifacts method when using the process model. The sortArtifacts method expects two input arguments: a padv.Query object and a list of padv.Artifact objects returned by the run method. The sortArtifacts method should return a list of sorted padv.Artifact objects.

Example: SortArtifacts = false

Data Types: logical

FunctionHandle — Handle to function that function-based query runs

function_handle

Handle to the function that a function-based query runs, specified as a function_handle.

If you define your query functionality inside a function and you or the build system call run on the query, the query runs the function specified by the function_handle.

The built-in queries are defined inside classes and do not use the FunctionHandle.

Example: FunctionHandle = @FunctionForQuery

Data Types: function_handle

Methods

Specialized Public Methods

run

Run query to find the artifacts that meet the criteria specified by the query. When the query runs, the query loads the build plan by using the matlab.buildtool.Plan.load method and validates the MATLAB build tool tasks that you specified with the query argument Tasks against the tasks in the matlab.buildtool.Plan object. For each MATLAB build tool task that you specified, the query creates padv.Artifact objects for each task input file. By default, these artifacts have the artifact type "other_file" and the digital thread does not track changes to these files. The query returns a padv.Artifact object or an array of padv.Artifact objects that represent those artifacts. Note You do not need to manually invoke this method inside your process model. The build system automatically invokes the run method to find artifacts. The run method inside this built-in query runs on a query object obj and returns artifacts artifacts. If you inherit from this built-in query, make sure to use the same method signature inside your custom query: function artifacts = run(obj,~) ... end

Examples

Get Inputs of MATLAB Build Tool Tasks

You can use the GetInputsOfBuildToolTasks query in your task definition to find the inputs for MATLAB build tool tasks. For example, you can use this query as an input query for the built-in task padv.builtin.task.RunBuildTool to pass your MATLAB build tool task inputs as inputs to your Process Advisor tasks.

function processmodel(pm)
    % Defines the project's processmodel

    arguments
        pm padv.ProcessModel
    end

    processMBT = pm.addProcess("MBT");
    taskObj = processMBT.addTask(padv.builtin.task.RunBuildTool());
    taskObj.Tasks = ["check" "pcode" "archive"];
    taskObj.Title = taskObj.Title + ": " + strjoin(taskObj.Tasks, ', ');

    taskObj.IncludeOutputs = true;
    taskObj.addInputQueries(padv.builtin.query.GetInputsOfBuildToolTasks(Tasks=taskObj.Tasks));

end

Test GetInputsOfBuildToolTasks Query Outside Process Model

Although you typically use a query inside your process model, you can run an instance of the GetInputsOfBuildToolTasks query outside of your process model to confirm which artifacts the query returns.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

By default, the Process Advisor example project does not contain a build file.

Inside the project root folder, add a file named buildfile.m to the project and add the following content to the build file. This build file code defines a build plan with a task, "pcode", that generates P-code for MATLAB files inside the tools folder of the project. For information on how to define a build plan for the MATLAB build tool, see Build Automation.

function plan = buildfile
plan = buildplan(localfunctions);

plan("pcode").Inputs = "tools/**/*.m";
plan("pcode").Outputs = plan("pcode").Inputs.replace(".m",".p");

end

function pcodeTask(context)
% Create P-code files
filePaths = context.Task.Inputs.paths;
pcode(filePaths{:},"-inplace")
end

Create an instance of the query.

q = padv.builtin.query.GetInputsOfBuildToolTasks(Tasks="pcode");

Run the query to see which artifacts the query returns.

inputFiles = run(q)

inputFiles = 

  Artifact with properties:

               Type: "other_file"
             Parent: [0×0 padv.Artifact]
    ArtifactAddress: [1×1 padv.util.ArtifactAddress]
              Alias: [0×0 string]

You can inspect the artifact by using the object properties, like ArtifactAddress. For this project, the query identifies the project startup file prjCleanup.m in the tools folder as an input for the "pcode" task. This is because the "pcode" task in the build file specifies inputs as "tools/**/*.m".

inputFiles.ArtifactAddress

ans = 

ArtifactAddress

          FileAddress: "tools\prjCleanup.m"
        OwningProject: "ProcessAdvisorExample"
    IsSubFileArtifact: 0

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	Only when the query property InProject is false.
Iteration query for task	No.

Version History

Introduced in R2023b