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","toolbox",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 toolbox 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","toolbox",Options="-R2018a");

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

buildtool mex

** Starting mex
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex

Verify that the MEX file exists in the toolbox 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 toolbox

.               ..              explore.mexw64  

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

• 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