files

Class: matlab.buildtool.Plan
Namespace: matlab.buildtool

Create file collections

Since R2023a

Syntax

fc = files(plan,p)

Description

fc = files(plan,p) creates file collections from the specified paths p and returns the file collections as a matlab.buildtool.io.FileCollection array the same size as p. If p contains relative paths, the method uses the root folder of plan to convert them to absolute paths.

Input Arguments

plan — Plan

matlab.buildtool.Plan object

Plan, specified as a matlab.buildtool.Plan object.

p — Paths to files and folders

string array | character vector | cell array of character vectors

Paths to files and folders, specified as a string array, character vector, or cell array of character vectors. The paths can include the * and ** wildcards:

• The * wildcard can appear in both filenames and pathnames. It matches any number of characters, including zero characters.

• The ** wildcard can appear in pathnames, but not in filenames. Characters next to a ** wildcard must be file separators. ** matches any number of characters, including zero characters. You can use this wildcard to represent subfolders of a specified folder recursively.

When you specify a path using wildcards, the path does not match any files or folders that start with a dot (.) unless the path itself starts with a dot. In addition, a path that ends with a file separator matches only folders.

Example: "src" represents the file or folder named src.

Example: "src/*.m" matches all the .m files in the src folder.

Example: "src/**/*.m" matches all the .m files in the src folder and any of its subfolders.

Examples

Create Task Using File Collections

Specify the inputs of a task named "pcode" by using the files method. (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.)

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

cd files_plan_example

This code shows the contents of the build file. The main function of the build file calls the files method to create a FileCollection object from the specified path.

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

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

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

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

buildtool pcode

** Starting pcode
** Finished pcode

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 pcode

** Skipped pcode: up-to-date

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

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

** Starting pcode
** Finished pcode

Version History

Introduced in R2023a

R2023b: files converts relative paths to absolute paths

When you create file collections with the files method, the paths of the file collections are absolute paths. Previously, the method did not convert any relative paths that you specified to absolute paths. To create file collections with relative paths, use the fromPaths static method, or use a string vector to specify an argument or property that requires file collections.