matlab.buildtool.io.FileCollection class

Package: matlab.buildtool.io

Collection of files and folders

Since R2023a

Description

The matlab.buildtool.io.FileCollection class represents a collection of files and folders. You can use this class to specify file-based inputs and outputs of a task. Specifying inputs or outputs of a task enables the build tool to skip the task if it determines that the task inputs and outputs have not changed since the last successful run. For more information, see Improve Performance with Incremental Builds.

Class Attributes

Abstract

true

For information on class attributes, see Class Attributes.

Creation

When you assign a string vector, character vector, or cell vector of character vectors to the Inputs or Outputs properties of a task, MATLAB^® automatically converts the assigned value to a FileCollection vector. For example, plan("myTask").Inputs = ["file1" "file2"] results in a 1-by-2 FileCollection vector.

To explicitly create a FileCollection object, use the files method.

Methods

Public Methods

paths

p = paths(collection) Return the paths to the files in collection. If collection contains paths with the * or ** wildcards, the method resolves them. Input Arguments collection — Collection of files, specified as an array of matlab.buildtool.io.FileCollection objects. Output Arguments p — Paths to the files in collection, returned as a string row vector. Sealed: true

Examples

Run Tasks That Support Incremental Builds

Run tasks that specify inputs and outputs to support incremental builds.

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

openExample("matlab/RunTasksThatSupportIncrementalBuildsExample")
cd incremental_build_example

This code shows the contents of the build file:

• The "pcode" task obfuscates its inputs and creates the P-code files in the same folders as the inputs.

• The "archive" task creates an archive of its inputs.

function plan = buildfile
% Create a plan from the task functions
plan = buildplan(localfunctions);

% Specify the inputs and outputs of the "pcode" task
plan("pcode").Inputs = "source/**/*.m";
plan("pcode").Outputs = "source/**/*.p";

% Specify the inputs and outputs of the "archive" task
plan("archive").Inputs = plan("pcode").Outputs;
plan("archive").Outputs = "source.zip";
end

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

function archiveTask(context)
% Create ZIP file
task = context.Task;
zip(task.Outputs.paths,task.Inputs.paths)
end

Run the "archive" task. Because the inputs of the "archive" task are the outputs of the "pcode" task, the build tool runs the "pcode" task before running the "archive" task.

buildtool archive

** Starting pcode
** Finished pcode

** Starting archive
** Finished archive

Run the "archive" task again. The build tool skips both of the tasks because none of the inputs or outputs of the tasks have changed.

buildtool archive

** Skipped pcode: up-to-date

** Skipped archive: up-to-date

Add a file to the source folder, and then rerun the "archive" task. The build tool runs the "pcode" task because its inputs have changed. The build tool also runs the "archive" task because its inputs have changed.

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

** Starting pcode
** Finished pcode

** Starting archive
** Finished archive

Delete the ZIP file created by the "archive" task, and then run the task. The build tool skips the "pcode" task because none of its inputs or outputs have changed. However, the build tool runs the "archive" task because its output has changed.

delete("source.zip") 
buildtool archive

** Skipped pcode: up-to-date

** Starting archive
** Finished archive

Tips

• If you set the Inputs and Outputs properties of a task using strings, the build tool uses your current folder to resolve any relative paths. If you use the files method instead, the build tool uses the plan root folder to resolve relative paths.

Version History

Introduced in R2023a