matlab.buildtool.tasks.MexTask Class

Namespace: matlab.buildtool.tasks
Superclasses: matlab.buildtool.Task

Task for building MEX file

Since R2024a

Description

The matlab.buildtool.tasks.MexTask class provides a build task for compiling and linking source files into a binary MEX file. To build a MEX file, the task runs the mex command. You must have a supported compiler installed on your system to run this task.

Tasks that you create with the MexTask class support incremental builds. For more information, see Up-To-Date Check.

Creation

Description

task = matlab.buildtool.tasks.MexTask(sourceFiles,outputFolder) creates a task for building a MEX file, and sets the SourceFiles and OutputFolder properties. The task compiles and links the specified source files into a binary MEX file and saves it to the specified output folder.

task = matlab.buildtool.tasks.MexTask(sourceFiles,outputFolder,Name=Value) sets the Filename and Options properties using one or more name-value arguments. You can also set the Description and Dependencies properties, which the class inherits from the Task class, using name-value arguments. For example, task = matlab.buildtool.tasks.MexTask("mymex.c","output",Options="-R2018a") creates a task that builds a MEX file by using the interleaved complex API (-R2018a).

Properties

This section lists the properties of the MexTask class. In addition to these properties, the MexTask class inherits properties from the Task class. Of the inherited properties, you can set the Description and Dependencies properties using name-value arguments during task creation.

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, and returned as a matlab.buildtool.io.FileCollection row vector. The task supports the same file types that you can provide to the mex command.

Attributes:

GetAccess	public
SetAccess	public

OutputFolder — Folder for MEX file

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

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

Attributes:

GetAccess	public
SetAccess	public

Filename — Name of MEX file

string scalar | character vector

Name of the MEX file to build, specified as a string scalar or character vector, and returned as a string scalar. If you do not specify a MEX file extension, the task includes the appropriate platform-dependent extension.

If you do not set the Filename property, the task names the MEX file based on the first filename in SourceFiles.

Attributes:

GetAccess	public
SetAccess	public

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, and returned as a string row vector. The task supports the same release-specific API and build options that you can pass to the mex command when building a MEX file. For example, specify Options=["-R2018a" "-v"] to build a MEX file with the -R2018a API in verbose mode.

Attributes:

GetAccess	public
SetAccess	public

MexFile — Binary MEX file to build

matlab.buildtool.io.File object

Binary MEX file to build, returned as a matlab.buildtool.io.File object. You can use this property to programmatically access the MEX file. For example, you can return the path to the MEX file by using p = plan("mex").MexFile.Path. You can also specify the MEX file as the input of other tasks, for instance, plan("archive").Inputs = plan("mex").MexFile.

Attributes:

GetAccess	public
SetAccess	private

Examples

Build MEX File

Build a MEX file by using the MexTask class. 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_example folder, which contains a build file as well as a C source file named explore.c.

cd mex_task_example

This code shows the contents of the build file. The build file has a task that compiles explore.c into a MEX file and saves the result to a folder named output in your current folder. The task builds the MEX file by using the interleaved complex API (-R2018a).

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

% Create a plan with no tasks
plan = buildplan;

% Add a task to build a MEX file
plan("mex") = MexTask("explore.c","output",Options="-R2018a");

Run the "mex" task. The task builds a binary MEX file and saves it to the output folder. The build run progress includes information specific to your compiler.

buildtool mex

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

Verify that the MEX file exists in the output folder. Because the build file does not specify the Filename property of the task, the task names the MEX file based on the source file using the appropriate platform-dependent extension.

dir output

.               ..              explore.mexw64  

Build MEX Files Using Task Group

Since R2024b

Build MEX files by using a group of matlab.buildtool.tasks.MexTask instances. You must have a supported C compiler installed on your system to run this example.

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

cd 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:explore") = MexTask("explore.c","output");
plan("mex:yprime") = MexTask("yprime.c","output");

plan("mex").Description = "Build MEX files";
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\task_group_example\output\explore.mexw64' successfully
Deleted 'C:\work\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

More About

Up-To-Date Check

To avoid redundant work, the build tool does not run a MexTask instance if it is up to date and its DisableIncremental property is false. The build tool runs the task if the source files, MEX file, or mex build configuration have changed since the last run:

• Source files — If you modify the source files or change the value of the SourceFiles property, the build tool runs the task.

• MEX file — If you modify or remove an existing MEX file or change the value of the OutputFolder or Filename property, the build tool runs the task.

• Build configuration — If you change the value of the Options property, the build tool runs the task.

Tips

• A MexTask instance respects the build output verbosity level specified at run time using the -verbosity option of the buildtool command. The run-time verbosity level takes precedence over any value specified in the Options property. (since R2024b)

• You cannot overwrite or remove the actions of a built-in task, but you can specify additional task actions. For example, append an action to the Actions property of a built-in task.

  plan("myTask").Actions(end+1) = @myAction;

Version History

Introduced in R2024a