padv.builtin.query.FindBuildfile Class

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

Query for finding build file for MATLAB build tool

Description

The padv.builtin.query.FindBuildfile class provides a query that can return a build file in the current project. A build file is a function file named buildfile.m that defines a build plan for the MATLAB^® build tool. 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. By default, the query finds the buildfile.m file in the project root folder. But you can automatically select a specific build file by using the optional name-value arguments.

If you define a build file for your project, you can use the built-in task padv.builtin.task.RunBuildTool to invoke the build tool. The RunBuildTool task uses the FindBuildfile query to find the build file in your project and use that file as a task input.

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

Creation

Description

query = padv.builtin.query.FindBuildfile() creates a query for finding the MATLAB Build Tool build file in your project.

query = padv.builtin.query.FindBuildfile(Name=Value) sets certain properties using one or more name-value arguments. For example, FindBuildfile(IncludePathRegex="BuildFileFolderName*") creates a query that only includes build files where the file path includes the specified string BuildFileFolderName.

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

Input Arguments

Name — Unique identifier for query

string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMyBuildFile"

Data Types: char | string

ArtifactType — Type of artifact

"m_file" (default) | ...

Type of artifact, specified as one or more artifact types. To specify multiple artifact types, use an array. For a list of valid digital thread artifact types, see Valid Artifact Types.

Since the MATLAB build tool expects the build file to be a function file (.m) in the project root folder, the padv.builtin.query.FindBuildfile query specifies ArtifactType as "m_file".

Example: "m_file"

IncludeLabel — Find build file with specific project label

cell array

Find build file with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

ExcludeLabel — Exclude build file with specific project label

cell array

Exclude build file with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

IncludePath — Find artifacts where path contains specific text

"buildfile.m" (default) | string

Find artifacts where the path contains specific text, specified as a string. Consider using IncludePathRegex instead.

Since the MATLAB build tool expects the build file to be a function file (.m) in the project root folder, the padv.builtin.query.FindBuildfile query specifies IncludePath as "buildfile.m".

Data Types: string

ExcludePath — Exclude artifacts where path contains specific text

string | character vector

Exclude artifacts where the path contains specific text, specified as a string or a character vector. Consider using ExcludePathRegex instead.

Data Types: string

IncludePathRegex — Find build file where path matches regular expression pattern

"buildfile\.m" (default) | string | character vector

Find build file where the path matches a regular expression pattern, specified as a string or character vector. IncludePathRegex expects UNIX^®-style path separators.

If you want to use a literal path, use IncludePath instead. You can specify either IncludePath or IncludePathRegex but not both.

Data Types: char | string

ExcludePathRegex — Exclude build file where path matches regular expression pattern

string | character vector

Exclude build file where the path matches a regular expression pattern, specified as a string or a character vector. ExcludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use ExcludePath instead. You can specify either ExcludePath or ExcludePathRegex but not both.

Data Types: char | string

InProject — Include only artifacts added to current open project or referenced projects

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

Include only artifacts that have been added to the current open project or referenced projects, specified as a numeric or logical 1 (true) or 0 (false).

Note

If you specify InProject as true, you cannot use the query as an input query.

Example: true

Data Types: logical

InCurrentProject — Include only artifacts added to current open project

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

Include only artifacts that have been added to the current open project, specified as a numeric or logical 1 (true) or 0 (false).

Note

If you specify InCurrentProject as true, you cannot use the query as an input query.

Example: true

Data Types: logical

Properties

Name — Unique identifier for query

string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMyBuildFile"

Data Types: char | string

ArtifactType — Type of artifact

"m_file" (default) | ...

Type of artifact, specified as one or more artifact types. To specify multiple artifact types, use an array. For a list of valid digital thread artifact types, see Valid Artifact Types.

Since the MATLAB build tool expects the build file to be a function file (.m) in the project root folder, the padv.builtin.query.FindBuildfile query specifies ArtifactType as "m_file".

Example: "m_file"

IncludeLabel — Find build file with specific project label

cell array

Find build file with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

ExcludeLabel — Exclude build file with specific project label

cell array

Exclude build file with specific project label, specified as a cell array where the first entry is the project label category and the second entry is the project label name.

Example: {"Classification","Design"}

Data Types: cell

IncludePath — Find artifacts where path contains specific text

"buildfile.m" (default) | string

Find artifacts where the path contains specific text, specified as a string. Consider using IncludePathRegex instead.

Since the MATLAB build tool expects the build file to be a function file (.m) in the project root folder, the padv.builtin.query.FindBuildfile query specifies IncludePath as "buildfile.m".

Data Types: string

ExcludePath — Exclude artifacts where path contains specific text

string | character vector

Exclude artifacts where the path contains specific text, specified as a string or a character vector. Consider using ExcludePathRegex instead.

Data Types: string

IncludePathRegex — Find build file where path matches regular expression pattern

"buildfile\.m" (default) | string | character vector

Find build file where the path matches a regular expression pattern, specified as a string or character vector. IncludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use IncludePath instead. You can specify either IncludePath or IncludePathRegex but not both.

Data Types: char | string

ExcludePathRegex — Exclude build file where path matches regular expression pattern

string | character vector

Exclude build file where the path matches a regular expression pattern, specified as a string or a character vector. ExcludePathRegex expects UNIX-style path separators.

If you want to use a literal path, use ExcludePath instead. You can specify either ExcludePath or ExcludePathRegex but not both.

Data Types: char | string

FilterSubFileArtifacts — Filter out sub-file artifacts from query results

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

Filter out sub-file artifacts from query results, specified as a numeric or logical 1 (true) or 0 (false).

A sub-file is a part of a larger file. For example, the function defined inside a MATLAB program file is a sub-file of that MATLAB file.

Example: false

Data Types: logical

InProject — Include only artifacts added to current open project or referenced projects

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

Include only artifacts that have been added to the current open project or referenced projects, specified as a numeric or logical 1 (true) or 0 (false).

Note

If you specify InProject as true, you cannot use the query as an input query.

Example: true

Data Types: logical

InCurrentProject — Include only artifacts added to current open project

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

Include only artifacts that have been added to the current open project, specified as a numeric or logical 1 (true) or 0 (false).

Note

If you specify InCurrentProject as true, you cannot use the query as an input query.

Example: true

Data Types: logical

Title — Query title

"Find the MATLAB Build Tool buildfile" (default) | string | character vector

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

Example: "Find my buildfile"

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 FindBuildfile query does not use this property because you cannot use FindBuildfile as an iteration query.

Name — Unique identifier for query

string | character vector

Unique identifier for query, specified as a string or a character vector.

Example: "FindMyBuildfile"

Data Types: char | string

ShowFileExtension — Show file extensions for returned build file

0 (false) | 1 (true)

Show file extensions in the Alias property of the returned build file, 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

Public Methods

padv.builtin.query.FindBuildfile inherits the run method from padv.builtin.query.FindArtifacts.

run

Run query to find the artifacts that meet the criteria specified by the query. 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 the build file. The run method 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

Find Build File for MATLAB Build Tool

You can use the FindBuildfile query in your task definition to find the build file for the MATLAB build tool. For example, the built-in task padv.builtin.task.RunBuildTool uses the FindBuildfile query to find the build file in your project and use that file as a task input.

Open the source code for the built-in task padv.builtin.task.RunBuildTool.

open padv.builtin.task.RunBuildTool

The task specifies "padv.builtin.query.FindBuildfile" as one of the input queries for the task by using the task property InputQueries.

Test FindBuildfile Query Outside Process Model

Although you typically use a query inside your process model, you can run an instance of the FindBuildfile query outside of your process model to confirm which artifact 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.

For information on how to define a build plan for the MATLAB build tool, see Build Automation.

Create an instance of the query.

q = padv.builtin.query.FindBuildfile();

Run the query and inspect the artifact that the query returns.

run(q)

ans = 

  Artifact with properties:

               Type: "m_file"
             Parent: [0×0 padv.Artifact]
    ArtifactAddress: [1×1 padv.util.ArtifactAddress]
              Alias: "buildfile.m"

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	Only when the query properties InProject and InCurrentProject are false.
Iteration query for task	No.