Main Content

matlab.buildtool.io.FileCollection class

Package: matlab.buildtool.io

Collection of files and folders

Since R2023a

expand all in page

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 use a string to specify an argument or property that requires a file collection, MATLAB® automatically converts the string to a FileCollection object. For example, plan("myTask").Inputs = ["file1" "file2"] results in a 1-by-2 FileCollection vector.

To explicitly create a FileCollection object, use the matlab.buildtool.io.FileCollection.fromPaths or files method.

Methods

expand all

Examples

collapse all

Open Live Script

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.

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 = plan("pcode").Inputs.replace(".m",".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

Version History

Introduced in R2023a

expand all

See Also

Functions

Classes

Topics