External Interfaces/API

Custom Building on UNIX

On UNIX systems, there are two stages in MEX-file building: compiling and linking.

Compile Stage

The compile stage must:

• Add <matlab>/extern/include to the list of directories in which to find header files (-I<matlab>/extern/include)
• Define the preprocessor macro MATLAB_MEX_FILE (-DMATLAB_MEX_FILE)
• (C MEX-files only) Compile the source file, which contains version information for the MEX-file, <matlab>/extern/src/mexversion.c

Link Stage

The link stage must:

• Instruct the linker to build a shared library
• Link all objects from compiled source files (including mexversion.c)
• (Fortran MEX-files only) Link in the precompiled versioning source file, <matlab>/extern/lib/$Arch/version4.o
• Export the symbols mexFunction and mexVersion (these symbols represent functions called by MATLAB)

For Fortran MEX-files, the symbols are all lower case and may have appended underscores. For specific information, invoke the mex script in verbose mode and examine the output.

Build Options

For customizing the build process, you should modify the options file. The options file contains the compiler-specific flags corresponding to the general steps outlined above. The options file consists of a series of variable assignments; each variable represents a different logical piece of the build process. The options files provided with MATLAB are located in <matlab>/bin. The section, Default Options File on UNIX, describes how the mex script looks for an options file.

To aid in providing flexibility, there are two sets of options in the options file that can be turned on and off with switches to the mex script. These sets of options correspond to building in debug mode and building in optimization mode. They are represented by the variables DEBUGFLAGS and OPTIMFLAGS, respectively, one pair for each driver that is invoked (CDEBUGFLAGS for the C compiler, FDEBUGFLAGS for the Fortran compiler, and LDDEBUGFLAGS for the linker; similarly for the OPTIMFLAGS).

• If you build in optimization mode (the default), the mex script will include the OPTIMFLAGS options in the compile and link stages.
• If you build in debug mode, the mex script will include the DEBUGFLAGS options in the compile and link stages, but will not include the OPTIMFLAGS options.
• You can include both sets of options by specifying both the optimization and debugging flags to the mex script (-O and -g, respectively).

Aside from these special variables, the mex options file defines the executable invoked for each of the three modes (C compile, Fortran compile, link) and the flags for each stage. You can also provide explicit lists of libraries that must be linked in to all MEX-files containing source files of each language.

The variables can be summed up as follows.

Variable	C Compiler	Fortran Compiler	Linker
Executable	CC	FC	LD
Flags	CFLAGS	FFLAGS	LDFLAGS
Optimization	COPTIMFLAGS	FOPTIMFLAGS	LDOPTIMFLAGS
Debugging	CDEBUGFLAGS	FDEBUGFLAGS	LDDEBUGFLAGS
Additional libraries	CLIBS	FLIBS	----

For specifics on the default settings for these variables, you can:

• Examine the options file in <matlab>/bin/mexopts.sh (or the options file you are using), or
• Invoke the mex script in verbose mode

Default Options File on Windows

Custom Building on Windows