MATLAB®

Custom Building Binary MEX-Files

Who Should Read This Chapter

In general, the defaults that come with MATLAB^® software should be sufficient for building most binary MEX-files. Following are reasons that you might need more detailed information:

• You want to use an Integrated Development Environment (IDE), rather than the provided script, to build MEX-files.

• You want to create a new options file, for example, to use a compiler that is not directly supported.

• You want to exercise more control over the build process than the script uses.

The script, in general, uses two stages (or three, for Microsoft^® Windows^® platforms) to build MEX-files. These are the compile stage and the link stage. In between these two stages, Windows compilers must perform some additional steps to prepare for linking (the prelink stage).

Back to Top

MEX Script Switches

The mex script has a set of switches (also called options) that you can use to modify the link and compile stages. The MEX Script Switches table lists the available switches and their uses. Each switch is available on both UNIX^®[1] and Windows systems unless otherwise noted.

For customizing the build process, you should modify the options file, which contains the compiler-specific flags corresponding to the general compile, prelink, and link steps required on your system. The options file consists of a series of variable assignments; each variable represents a different logical piece of the build process.

MEX Script Switches

Back to Top

UNIX^® Default Options File

The default MEX options file provided with MATLAB is located in matlabroot/bin. The mex script searches for an options file called mexopts.sh in the following order:

• The current directory

• The directory specified by matlabroot/bin

• The directory returned by the prefdir function

mex uses the first occurrence of the options file it finds. If no options file is found, mex displays an error message. You can directly specify the name of the options file using the -f switch.

The UNIX options file is written in the Bourne shell script language.

For specific information on the default settings for the MATLAB supported compilers, you can examine the options file in fullfile(matlabroot, 'bin', 'mexopts.sh'), or you can invoke the mex script in verbose mode (-v). Verbose mode prints the exact compiler options, prelink commands (if appropriate), and linker options used in the build process for each compiler. Custom Building on UNIX^® Systems gives an overview of the high-level build process.

Back to Top

Windows^® Default Options File

The default MEX options file is placed in your user profile directory after you configure your system by running mex -setup. The mex script searches for an options file called mexopts.bat in the following order:

• The current directory

• The user profile directory (returned by the prefdir function)

mex uses the first occurrence of the options file it finds. If no options file is found, mex searches your machine for a supported C compiler and automatically configures itself to use that compiler. Also, during the configuration process, it copies the compiler's default options file to the user profile directory. If multiple compilers are found, you are prompted to select one.

On Windows systems, the options file is written in the Perl script language.

For specific information on the default settings for the MATLAB supported compilers, you can examine the options file, mexopts.bat, or you can invoke the mex script in verbose mode (-v). Verbose mode prints the exact compiler options, prelink commands, if appropriate, and linker options used in the build process for each compiler. Custom Building on Windows^® Systems gives an overview of the high-level build process.

The User Profile Directory

The Windows user profile directory is a directory that contains user-specific information such as desktop appearance, recently used files, and Start menu items. The mex and mbuild utilities store their respective options files, mexopts.bat and compopts.bat, which are created during the -setup process, in a subdirectory of your user profile directory, named Application Data\MathWorks\MATLAB.

Back to Top

Custom Building on UNIX^® Systems

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

Compile Stage

The compile stage must

• Add matlabroot/extern/include to the list of directories in which to find header files (-Imatlabroot/extern/include).

• Define the preprocessor macro MATLAB_MEX_FILE (-DMATLAB_MEX_FILE).

• (C source MEX-files only) Compile the source file, which contains version information for the MEX-file, matlabroot/extern/src/mexversion.c.

Link Stage

The link stage must

• Instruct the linker to build a shared library.

• If you link with your own libraries, set the run-time library path, which is explained in Setting Run-Time Library Path.

• Link all objects from compiled source files (including mexversion.c).

• (Fortran source MEX-files only) Link in the precompiled versioning source file, matlabroot/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 lowercase 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 matlabroot/bin. The section UNIX^® Default Options File, 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 you can turn 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 includes the OPTIMFLAGS options in the compile and link stages.

• If you build in debug mode, the mex script includes the DEBUGFLAGS options in the compile and link stages. It does 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 also can provide explicit lists of libraries that must be linked in to all MEX-files containing source files of each language.

The variable summary follows.

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

• Examine the options file in matlabroot/bin/mexopts.sh (or the options file you are using), or

• Invoke the mex script in verbose mode.

Back to Top

Custom Building on Windows^® Systems

There are three stages to MEX-file building for both C and Fortran on Windows systems: compiling, prelinking, and linking.

Compile Stage

For the compile stage, a mex options file must

• Set up paths to the compiler using the COMPILER (e.g., Watcom), PATH, INCLUDE, and LIB environment variables. If your compiler always has the environment variables set (e.g., in AUTOEXEC.BAT), you can comment them out in the options file.

• Define the name of the compiler, using the COMPILER environment variable, if needed.

• Define the compiler switches in the COMPFLAGS environment variable:

  • The switch to create a DLL is required for MEX-files.

  • For stand-alone programs, the switch to create an exe is required.

  • The -c switch (compile only; do not link) is recommended.

  • The switch to specify 8-byte alignment.

  • You can use any other switch specific to the environment.

• Define preprocessor macro, with -D, MATLAB_MEX_FILE is required.

• Set up optimizer switches and/or debug switches using OPTIMFLAGS and DEBUGFLAGS.

  • If you build in optimization mode (the default), the mex script includes the OPTIMFLAGS option in the compile stage.

  • If you build in debug mode, the mex script includes the DEBUGFLAGS options in the compile stage. It does not include the OPTIMFLAGS option.

  • You can include both sets of options by specifying both the optimization and debugging flags to the mex script (OPTIMFLAGS and DEBUGFLAGS, respectively).

Prelink Stage

The prelink stage dynamically creates import libraries to import the required function into the MEX, MAT, or engine file:

• All MEX-files link against libmex.dll (MEX library).

• MAT stand-alone programs link against libmx.dll (array access library) and libmat.dll (MAT-functions).

• Engine stand-alone programs link against libmx.dll (array access library) and libeng.dll for engine functions.

Link Stage

For the link stage, a mex options file must

• Define the name of the linker in the LINKER environment variable.

• Define the LINKFLAGS environment variable that must contain

  • The switch to create a DLL for MEX-files, or the switch to create an exe for stand-alone programs.

  • Export of the entry point to the MEX-file as mexFunction for C or MEXFUNCTION@16 for Fortran.

  • The import library (or libraries) created in the PRELINK_CMDS stage.

  • You can use any other link switch specific to the compiler.

• Set up the linking optimization and debugging switches LINKOPTIMFLAGS and LINKDEBUGFLAGS. Use the same conditions described in the Compile Stage.

• Define the link-file identifier in the LINK_FILE environment variable, if necessary. For example, Watcom uses file to identify that the name following is a file and not a command.

• Define the link-library identifier in the LINK_LIB environment variable, if necessary. For example, Watcom uses library to identify the name following is a library and not a command.

• Optionally, set up an output identifier and name with the output switch in the NAME_OUTPUT environment variable. The environment variable MEX_NAME contains the name of the first program in the command line. This must be set for -output to work. If this environment is not set, the compiler default is to use the name of the first program in the command line. Even if this is set, you can override it by specifying the mex -output switch.

Linking DLL Files to Binary MEX-Files

To link a DLL to a MEX-file, list the DLL's .lib file on the command line.

Versioning Build MEX-Files

The mex build script can build your MEX-file with a resource file that contains versioning and other essential information. The resource file is called mexversion.rc and resides in the extern\include directory. To support versioning, there are two new commands in the options files, RC_COMPILER and RC_LINKER, to provide the resource compiler and linker commands. It is assumed that

• If a compiler command is given, the compiled resource links to the MEX-file using the standard link command.

• If a linker command is given, the resource file links to the MEX-file after it is built using that command.

Compiling MEX-Files with the Microsoft^® Visual C++^® IDE

Note    This section provides information on how to compile source MEX-files in the Microsoft® Visual C++® IDE. It is not totally inclusive. This section assumes that you know how to use the IDE. If you need more information on using the Microsoft Visual C++ IDE, refer to the corresponding Microsoft documentation.

To build MEX-files with the Microsoft Visual C++ integrated development environment:

1. Create a project and insert your MEX source files.

2. Add mexversion.rc from the MATLAB include directory, matlab\extern\include, to the project.

3. Create a .def file to export the MEX entry point. On the Project menu, click Add New Item and select Module-Definition File (.def). For example:

   LIBRARY MYFILE
   EXPORTS mexFunction          <-- for a C MEX-file
      or
   EXPORTS _MEXFUNCTION@16       <-- for a Fortran MEX-file

4. On the Project menu, click Properties for the project to open the property pages.

5. Under C/C++ General properties, add the MATLAB include directory, matlab\extern\include, as an additional include directory.

6. Under C/C++ Preprocessor properties, add MATLAB_MEX_FILE as a preprocessor definition.

7. Under Linker General properties, change the output file extension to .mexw32 if you are building for a 32–bit platform or .mexw64 if you are building for a 64–bit platform.

8. Locate the .lib files for the compiler you are using under matlabroot\extern\lib\win32\microsoft or matlabroot\extern\lib\win64\microsoft. Under Linker Input properties, add libmx.lib, libmex.lib, and libmat.lib as additional dependencies.

9. Under Linker Input properties, add the module definition (.def) file you created.

10. Under Linker Debugging properties, if you intend to debug the MEX-file using the IDE, specify that the build should generate debugging information. For more information about debugging, see Debugging on the Microsoft^® Windows^® Platforms.

If you are using a compiler other than the Microsoft Visual C++ compiler, the process for building MEX files is similar to that described above. In step 4, locate the .lib files for the compiler you are using in a subdirectory of matlabroot\extern\lib\win32 or matlabroot\extern\lib\win64. For example, if you are using an Open Watcom C++ compiler, look in matlabroot\extern\lib\win32\watcom.

^[1] UNIX is a registered trademark of The Open Group in the United States and other countries.

Back to Top

Building Binary MEX-Files

Troubleshooting