matlab.buildtool.TaskOutputs class

Package: matlab.buildtool

Container for task outputs

Since R2023b

Description

The matlab.buildtool.TaskOutputs class provides a container for defining and grouping outputs of a task. Specifying inputs or outputs for a task enables incremental build support for the task. For more information, see Improve Performance with Incremental Builds.

A TaskOutputs object behaves like a structure, where field names are task output names and field values are task output values. To add, modify, or return a task output, index into the TaskOutputs object by using the output name:

• To add or modify an output, use the outputs.OutputName = value syntax, where OutputName is the name of the output you want to add or modify.

• To return an output, use the value = outputs.OutputName syntax, where OutputName is the name of the output whose value you want to return.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

outputs = matlab.buildtool.TaskOutputs creates a TaskOutputs object that has no outputs.

outputs = matlab.buildtool.TaskOutputs(name1,value1,...,nameN,valueN) creates a TaskOutputs object with the specified output names and values.

Input Arguments

name — Task output name

string scalar | character vector

Task output name, specified as a string scalar or character vector. The name must be a valid MATLAB^® identifier. A valid MATLAB identifier is a string scalar or character vector of alphanumerics (A–Z, a–z, 0–9) and underscores, where the first character is a letter and the length of the text is not greater than namelengthmax.

value — Task output value

matlab.buildtool.io.FileCollection array

Task output value, specified as a matlab.buildtool.io.FileCollection array.

Methods

Public Methods

outputNames

names = outputNames(outputs) Return the names of the task outputs. To call the method, use function syntax. For more information about function syntax, see Choose Command Syntax or Function Syntax. Input Arguments outputs — Task outputs, specified as a matlab.buildtool.TaskOutputs object. Output Arguments names — Names of the task outputs, returned as a string column vector.

Examples

Create Task with Named Inputs and Outputs

Create a task that uses two named inputs to analyze program files and two named outputs to store the lists of files and products required to run the program files. Tasks with specified inputs or outputs support incremental builds.

Open the example and then navigate to the named_io_example folder, which contains a build file.

cd named_io_example

This code shows the contents of the build file. The build file has a task that analyzes program files and stores the lists of files and products required to run the program files:

• To specify the program files and the mode of the dependency analysis, the task uses the inputs named FilesToAnalyze and IncludeIndirectDependencies. The Inputs property of the task is a TaskInputs object that contains the named inputs.

• To specify where to write the lists of required files and products, the task uses the outputs named FileList and ProductList. The Outputs property of the task is a TaskOutputs object that contains the named outputs.

function plan = buildfile
plan = buildplan(localfunctions);

% Specify the program files to analyze and whether to include indirect dependencies
plan("dependencies").Inputs.FilesToAnalyze = files(plan,"source/**/*.m");
plan("dependencies").Inputs.IncludeIndirectDependencies = false;

% Specify where to write the lists of required files and products
plan("dependencies").Outputs.FileList = files(plan,"fileList.txt");
plan("dependencies").Outputs.ProductList = files(plan,"productList.txt");
end

function dependenciesTask(context)
% Determine required files and products
files = context.Task.Inputs.FilesToAnalyze.paths;

if context.Task.Inputs.IncludeIndirectDependencies
    [fList,pList] = matlab.codetools.requiredFilesAndProducts(files);
else
    [fList,pList] = matlab.codetools.requiredFilesAndProducts(files,"toponly");
end

writelines(fList,context.Task.Outputs.FileList.paths)
writelines({pList.Name},context.Task.Outputs.ProductList.paths)
end

Run the "dependencies" task. The task analyzes the code in the source folder and any of its subfolders, and writes the lists of the required files and products to separate text files.

buildtool dependencies

** Starting dependencies
** Finished dependencies

Run the task again. The build tool skips the task because none of the inputs or outputs of the task have changed since the last run.

buildtool dependencies

** Skipped dependencies: up-to-date

Add a file to the source folder, and then rerun the task. The build tool runs the task because one of the inputs of the task has changed between consecutive builds.

fclose(fopen(fullfile("source","newFile.m"),"w"));
buildtool dependencies

** Starting dependencies
** Finished dependencies

Version History

Introduced in R2023b