Main Content

matlab.buildtool.io.FileCollection Class

Namespace: 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. For more information about task inputs and outputs, 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

Create and run tasks that have inputs and outputs.

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. (For illustrative purposes, the "pcode" task in this example is created using a task function. The recommended practice is to create the task using the matlab.buildtool.tasks.PcodeTask class.)

  • 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