matlab.buildtool.tasks.MexTask.forEachFile

R2026b

Class: matlab.buildtool.tasks.MexTask
Namespace: matlab.buildtool.tasks

Create task group containing a MexTask instance for each source file

Since R2025a

Syntax

group = matlab.buildtool.tasks.MexTask.forEachFile(sourceFiles,outputFolder)

group = matlab.buildtool.tasks.MexTask.forEachFile(sourceFiles,outputFolder,Name=Value)

Description

group = matlab.buildtool.tasks.MexTask.forEachFile(sourceFiles,outputFolder) creates a task group containing a MexTask instance for each specified source file. Each task in the task group compiles the corresponding source file into a binary MEX file and saves it to the specified output folder.

group = matlab.buildtool.tasks.MexTask.forEachFile(sourceFiles,outputFolder,Name=Value) specifies options using one or more name-value arguments. For example, group = matlab.buildtool.tasks.MexTask.forEachFile(["mymex1.c" "mymex2.c"],"output",Options="-R2018a") creates a task group containing two tasks that build MEX files by using the interleaved complex API (-R2018a).

Input Arguments

sourceFiles — Source files to compile

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

Source files to compile, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector. The task group supports the same file types that you can provide to the mex command.

If sourceFiles includes a pattern with the * or ** wildcard, then the task group contains a MexTask instance for each file that matches the pattern.

Example: group = matlab.buildtool.tasks.MexTask.forEachFile("*.c","output") creates a task group containing a MexTask instance for each C source file in the current folder.

outputFolder — Folder for MEX files

string scalar | character vector | matlab.buildtool.io.File object

Folder for the MEX files, specified as a string scalar, character vector, or matlab.buildtool.io.File object. If the folder does not exist, the task group creates it.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: group = matlab.buildtool.tasks.MexTask.forEachFile(["mymex1.c" "mymex2.c"],"output",Options="-R2018a")

CommonSourceFiles — Source files common to all tasks

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

Source files common to all the tasks in the task group, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector. Each task in the task group builds a MEX file by compiling and linking its corresponding source file in sourceFiles and all the source files in CommonSourceFiles.

Options — Options for customizing mex build configuration

string vector | character vector | cell vector of character vectors

Options for customizing the mex build configuration, specified as a string vector, character vector, or cell vector of character vectors. The task group supports the same release-specific API and build options that you can pass to the mex command when building a MEX file. For example, if you specify Options=["-R2018a" "-v"], each task in the task group builds a MEX file with the -R2018a API in verbose mode.

Dependencies — Names of tasks on which the task group depends

string vector | character vector | cell vector of character vectors

Names of the tasks on which the tasks in the task group depend, specified as a string vector, character vector, or cell vector of character vectors. To run all or part of the task group, the build runner first runs all the depended-on tasks.

Description — Description of task group

string scalar | character vector

Description of the task group, specified as a string scalar or character vector.

Output Arguments

group — Task group

matlab.buildtool.TaskGroup object

Task group, returned as a matlab.buildtool.TaskGroup object.

Attributes

Static

true

To learn about attributes of methods, see Method Attributes.

Examples

Build MEX Files

Build MEX files using a task group created with the matlab.buildtool.tasks.MexTask.forEachFile method. You must have a supported C compiler installed on your system to run this example.

Open the example and then navigate to the mex_task_group_example folder, which contains a build file as well as two C source files named explore.c and yprime.c.

cd mex_task_group_example

This code shows the contents of the build file:

• The "clean" task deletes outputs and traces of the other tasks in the build file.

• The "mex" task group contains two tasks named "mex:explore" and "mex:yprime". Each of these tasks compiles a source file into a MEX file and saves the result to a folder named output in your current folder.

function plan = buildfile
import matlab.buildtool.tasks.CleanTask
import matlab.buildtool.tasks.MexTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to delete outputs and traces
plan("clean") = CleanTask;

% Add a task group to build MEX files
plan("mex") = MexTask.forEachFile(["explore.c" "yprime.c"],"output");
end

Run the "mex" task group. The "mex:explore" and "mex:yprime" tasks in the task group build binary MEX files and save them to the output folder. The build run progress includes information specific to your compiler.

buildtool mex

** Starting mex:explore
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:explore

** Starting mex:yprime
mex yprime.c -output output\yprime.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:yprime

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    27.925 sec total build time

Run the "mex:explore" task in isolation. The build tool skips the task because neither its input nor output has changed.

buildtool mex:explore

** Skipped mex:explore (up-to-date)

Build Successful:
    1 Task: 0 Failed, 1 Skipped
    0.33593 sec total build time

Run the "clean" task to delete outputs and traces of the other tasks in the plan. When you delete the outputs or the trace of a task, the build tool no longer considers the task as up to date.

buildtool clean

** Starting clean
Deleted 'C:\work\ExampleManager\user.examples\matlab-ex84876786\mex_task_group_example\output\explore.mexw64'
Deleted 'C:\work\ExampleManager\user.examples\matlab-ex84876786\mex_task_group_example\output\yprime.mexw64'
** Finished clean

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    0.37454 sec total build time

Rerun the "mex:explore" task to build a fresh MEX file.

buildtool mex:explore

** Starting mex:explore
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:explore

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    5.9809 sec total build time

Now, run the "mex" task group again. The build tool runs only the "mex:yprime" task in the task group. It skips the "mex:explore" task because the task is up to date.

buildtool mex

** Skipped mex:explore (up-to-date)

** Starting mex:yprime
mex yprime.c -output output\yprime.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:yprime

Build Successful:
    2 Tasks: 0 Failed, 1 Skipped
    4.028 sec total build time

Build MEX Files Using Common Source Files

Build two MEX files that depend on a common source file. You must have a supported C compiler installed on your system to run this example.

Open the example and then navigate to the mex_task_group_example1 folder, which contains a build file as well as three C source files named scalarMultiply.c, scalarSquare.c, and shared.c. Both the scalarMultiply.c and scalarSquare.c source files depend on the shared.c source file.

cd mex_task_group_example1

This code shows the contents of the build file. The "mex" task group, created with the matlab.buildtool.tasks.MexTask.forEachFile method, contains a MexTask instance for each C source file whose name starts with "scalar". Each task in the task group builds a MEX file by compiling and linking its corresponding source file and the source file specified using the CommonSourceFiles name-value argument, and saves the result to a folder named output in your current folder.

function plan = buildfile
import matlab.buildtool.tasks.MexTask

% Create a plan with no tasks
plan = buildplan;

% Add a task group to build MEX files
plan("mex") = MexTask.forEachFile("scalar*.c","output", ...
    CommonSourceFiles="shared.c");
end

List all the tasks in the build file. The name and description of each MexTask instance is based on the name of the corresponding source file.

buildtool -tasks all

mex                - Build MEX files
mex:scalarMultiply - Build scalarMultiply MEX file
mex:scalarSquare   - Build scalarSquare MEX file

Run the "mex" task group. The "mex:scalarMultiply" and "mex:scalarSquare" tasks in the task group build binary MEX files by compiling and linking their corresponding source files and the shared.c common source file. A folder named output in your current folder contains the resulting MEX files. The build run progress includes information specific to your compiler.

buildtool mex

** Starting mex:scalarMultiply
mex scalarMultiply.c shared.c -output output\scalarMultiply.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:scalarMultiply

** Starting mex:scalarSquare
mex scalarSquare.c shared.c -output output\scalarSquare.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex:scalarSquare

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    8.7396 sec total build time

Version History

Introduced in R2025a