matlab.buildtool.tasks.MexTask.forEachFile

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

Create task group containing a MexTask instance for each source file

Since R2025a

expand all in page

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 and returns the task group as a matlab.buildtool.TaskGroup object. Each task in the task group compiles the corresponding source file into a binary MEX file and saves it to the specified output folder.

example

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).

example

Input Arguments

expand all

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.

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

expand all

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")

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 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.

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 of the task group, specified as a string scalar or character vector.

Attributes

Statictrue

To learn about attributes of methods, see Method Attributes.

Examples

expand all

Open Script

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

** Done mex

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)

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\mex_task_group_example\output\explore.mexw64' successfully
Deleted 'C:\work\mex_task_group_example\output\yprime.mexw64' successfully
** Finished clean

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

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

** Done mex
Open Live Script

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

** Done mex

Version History

Introduced in R2025a

See Also

Functions

Classes

Topics