Learn more about MATLAB

mex - Compile MEX-function from C/ C++ or Fortran source code

Syntax

mex -help mex -setup mex filenames mex options filenames

Description

mex -help displays the M-file help for mex.

mex -setup lets you select or change the compiler configuration. MATLAB software searches for installed compilers and allows you to choose an options file as the default for future invocations of mex. For more information, see Building MEX-Files and mex.getCompilerConfigurations.

mex filenames compiles and links one or more C/C++ or Fortran source files specified in filenames into a shared library called a binary MEX-file from MATLAB.

mex options filenames compiles and links one or more source files specified in filenames using one or more of the specified command-line options.

The MEX-file has a platform-dependent extension. Use the mexext function to return the extension for the current machine or for all supported platforms.

filenames can be any combination of source files, object files, and library files. Include both the file name and the file extension in filenames. A non-source-code filenames parameter is passed to the linker without being compiled.

All valid command-line options are shown in the MEX Script Switches table. These options are available on all platforms except where noted.

mex also can build executable files for stand alone MATLAB engine and MAT-file applications. For more information, see Engine/MAT Stand Alone Application Details.

You can run mex from the MATLAB Command Prompt, the Microsoft Windows Command Prompt, or the UNIX^[1] shell. mex is a script named mex.bat on Windows systems and mex on UNIX systems. It is located in the matlabroot/bin directory.

The first file listed in filenames becomes the name of the binary MEX-file. You can list other source, object, or library files as additional filenames parameters to satisfy external references.

mex uses an options file to specify variables and values that are passed as arguments to the compiler, linker, and other tools (e.g., the resource linker on Windows systems). For more information, see Options File Details. The default name for the options file is mexopts.bat (Windows systems) or mexopts.sh (UNIX systems).

Command-line options to mex may supplement or override contents of the options file. For more information, see Override Option Details.

For an up-to-date list of supported compilers, see the Supported and Compatible Compilers Web page.

MEX Script Switches

Switch	Function
`@``rsp_file`	(Windows systems only) Include the contents of the text file `rsp_file` as command-line arguments to `mex`.
`-``arch`	Build an output file for architecture `arch`. To determine the value for `arch`, type `computer('arch')` at the MATLAB Command Prompt on the target machine. Valid values for `arch` depend on the architecture of the build platform. You can get this information from the Help menu, as described in Getting Version and License Information in the Desktop Tools and Development Environment documentation.
`-argcheck`	(C functions only) Add argument checking. This adds code so arguments passed incorrectly to MATLAB API functions cause assertion failures.
`-c`	Compile only. Creates an object file, but not a binary MEX-file.
`-compatibleArrayDims`	Build a binary MEX-file using the MATLAB Version 7.2 array-handling API, which limits arrays to 2^31-1 elements. This option is the default, but in the future the `-largeArrayDims` option will be the default.
`-cxx`	(UNIX systems only) Use the C++ linker to link the MEX-file if the first source file is in C and there are one or more C++ source or object files. This option overrides the assumption that the first source file in the list determines which linker to use.
`-D``name`	Define a symbol name to the C preprocessor. Equivalent to a `#define` `name` directive in the source. Do not add a space after this switch.
`-D``name``=``value`	Define a symbol name and value to the C preprocessor. Equivalent to a `#define` `name` `value` directive in the source. Do not add a space after this switch.
`-f` `optionsfile`	Specify location and name of options file to use. Overrides the `mex` default-options-file search mechanism.
`-fortran`	(UNIX systems only) Specify that the gateway routine is in Fortran. This option overrides the assumption that the first source file in the list determines which linker to use.
`-g`	Create a binary MEX-file containing additional symbolic information for use in debugging. This option disables the `mex` default behavior of optimizing built object code (see the `-O` option).
`-h[elp]`	Print help for `mex`.
`-I``pathname`	Add `pathname` to the list of directories to search for `#include` files. Do not add a space after this switch.
`-inline`	Inline matrix accessor functions (`mx*`). This option is deprecated and will be removed in a future release. The generated MEX-function may not be compatible with future versions of MATLAB.
`-l``name`	Link with object library. On Windows systems, `name` expands to `name``.lib` or `lib``name``.lib` and on UNIX systems, to `lib``name``.so` or `lib``name``.dylib`. Do not add a space after this switch.
`-L``directory`	Add `directory` to the list of directories to search for libraries specified with the `-l` option. The `-L` option must precede the `-l` option. On UNIX systems, you must also set the run-time library path, as explained in Setting Run-Time Library Path. Do not add a space after this switch.
`-largeArrayDims`	Build a binary MEX-file using the MATLAB large-array-handling API. This API can handle arrays with more than 2^31–1 elements when compiled on 64-bit platforms. (See also the `-compatibleArrayDims` option.)
`-n`	No execute mode. Print any commands that `mex` would otherwise have executed, but do not actually execute any of them.
`-O`	Optimize the object code. Optimization is enabled by default and by including this option on the command line. If the `-g` option appears without the `-O` option, optimization is disabled.
`-outdir` `dirname`	Place all output files in directory `dirname`.
`-output` `resultname`	Create binary MEX-file named `resultname`. Automatically appends the appropriate MEX-file extension. Overrides the default MEX-file naming mechanism.
`-setup`	Specify the compiler options file to use when calling the `mex` function. When you use this option, all other command-line options are ignored.
`-U``name`	Remove any initial definition of the C preprocessor symbol `name`. (Inverse of the `-D` option.) Do not add a space after this switch.
`-v`	Verbose mode. Print the values for important internal variables after the options file is processed and all command-line arguments are considered. Prints each compile step and final link step fully evaluated.
`name``=``value`	Override an options file variable for variable `name`. For examples, see Override Option Details in the Remarks section of the `mex` reference page.

Remarks

Options File Details

MATLAB provides template options files for the compilers that are supported by mex. These templates are located in the matlabroot\bin\win32\mexopts or the matlabroot\bin\win64\mexopts directories on Windows systems, or the matlabroot/bin directory on UNIX systems. These template options files are used by the -setup option to define the selected default options file.

Override Option Details

Use the name=value command-line argument to override a variable specified in the options file at the command line. When using this option, you may need to use the shell's quoting syntax to protect characters such as spaces, which have a meaning in the shell syntax.

This option is processed after the options file is processed and all command line arguments are considered.

On Windows platforms, at either the MATLAB prompt or the DOS prompt, use double quotes ("). For example:

mex -v COMPFLAGS="$COMPFLAGS -Wall" LINKFLAGS="$LINKFLAGS /VERBOSE" yprime.c

At the MATLAB command line on UNIX platforms, use double quotes ("). Use the backslash (\) escape character before the dollar sign ($). For example:

mex -v CFLAGS="\$CFLAGS -Wall" LDFLAGS="\$LDFLAGS-w" yprime.c

At the shell command line on UNIX platforms, use single quotes ('). For example:

mex -v CFLAGS='$CFLAGS -Wall' LDFLAGS='$LDFLAGS -w' yprime.c

Engine/MAT Stand Alone Application Details

mex can build executable files for stand alone MATLAB engine and MAT-file applications. For these applications, mex does not use the default options file; you must use the -f option to specify an options file.

The options files used to generate stand alone MATLAB engine and MAT-file executables are named *engmatopts.bat on Windows systems, or engopts.sh and matopts.sh on UNIX systems, and are located in the same directory as the template options files referred to above in Options File Details.

Examples

Compiling a C File

The following command compiles yprime.c:

mex yprime.c

Using Verbose Mode

When debugging, it is often useful to use verbose mode, as well as include symbolic debugging information:

mex -v -g yprime.c

Overriding Command Line Options

For examples, see Override Option Details.