External Interfaces/API

Custom Building on Windows

There are three stages to MEX-file building for both C and Fortran on Windows - 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 remark 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.
1. The switch to create a DLL is required for MEX-files.
2. For stand-alone programs, the switch to create an exe is required.
3. The -c switch (compile only; do not link) is recommended.
4. The switch to specify 8-byte alignment.
5. Any other switch specific to the environment can be used.
• Define preprocessor macro, with -D, MATLAB_MEX_FILE is required.
• Set up optimizer switches and/or debug switches using OPTIMFLAGS and DEBUGFLAGS. These are mutually exclusive: the OPTIMFLAGS are the default, and the DEBUGFLAGS are used if you set the -g switch on the mex command line.

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 MATLAB only. 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. MATLAB and each DLL have corresponding .def files of the same names located in the <matlab>\extern\include directory.

Link Stage

Finally, 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 DIGITAL Visual Fortran.
• The import library(s) created in the PRELINK_CMDS stage.
• Any other link switch specific to the compiler that can be used.
• Define the linking optimization switches and debugging switches in LINKEROPTIMFLAGS and LINKDEBUGFLAGS. As in the compile stage, these two are mutually exclusive: the default is optimization, and the -g switch invokes the debug switches.
• Define the link-file identifier in the LINK_FILE environment variable, if needed. 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 needed. 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, it can be overridden by specifying the mex -output switch.

Linking DLLs to MEX-Files

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

Versioning MEX-Files

The mex 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 will be linked into the MEX-file using the standard link command.
• If a linker command is given, the resource file will be linked 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 MEX-files in the Microsoft Visual C++ (MSVC) 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 MSVC 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 and mexversion.rc into it.
2. Create a .DEF file to export the MEX entry point. For example

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

3. Add the .DEF file to the project.
4. Locate the .LIB files for the compiler version you are using under matlabroot\extern\lib\win32\microsoft. For example, for version 6.0, these files are in the msvc60 subdirectory.
5. From this directory, add libmx.lib, libmex.lib, and libmat.lib to the library modules in the LINK settings option.
6. Add the MATLAB include directory, MATLAB\EXTERN\INCLUDE to the include path in the Settings C/C++ Preprocessor option.
7. Add MATLAB_MEX_FILE to the C/C++ Preprocessor option by selecting Settings from the Build menu, selecting C/C++, and then typing ,MATLAB_MEX_FILE after the last entry in the Preprocessor definitions field.
8. To debug the MEX-file using the IDE, put MATLAB.EXE in the Settings Debug option as the Executable for debug session.

If you are using a compiler other than the Microsoft Visual C/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. For example, for version 5.4 of the Borland C/C++ compiler, look in matlabroot\extern\lib\win32\borland\bc54.

Using the Add-In for Visual Studio

The MathWorks provides a MATLAB add-in for the Visual Studio^® development system that lets you work easily within Microsoft Visual C/C++ (MSVC). The MATLAB add-in for Visual Studio greatly simplifies using M-files in the MSVC environment. The add-in automates the integration of M-files into Visual C++ projects. It is fully integrated with the MSVC environment.

The add-in for Visual Studio is automatically installed on your system when you run either mbuild -setup or mex -setup and select Microsoft Visual C/C++ version 5 or 6. However, there are several steps you must follow in order to use the add-in:

1. To build MEX-files with the add-in for Visual Studio, run the following command at the MATLAB command prompt.

• mex -setup
  

1. Follow the menus and choose either Microsoft Visual C/C++ 5.0 or 6.0. This configures mex to use the selected Microsoft compiler and also installs the necessary add-in files in your Microsoft Visual C/C++ directories.

2. To configure the MATLAB add-in for Visual Studio to work with Microsoft Visual C/C++:
1. Select Tools -> Customize from the MSVC menu.
2. Click on the Add-ins and Macro Files tab.
3. Check MATLAB for Visual Studio on the Add-ins and Macro Files list and click Close. The floating MATLAB add-in for Visual Studio toolbar appears. The checkmark directs MSVC to automatically load the add-in when you start MSVC again.

Configuring on Windows 98 and Windows ME Systems

Windows 98.   To run the MATLAB add-in for Visual Studio on Windows 98 systems, add this line to your config.sys file.

• shell=c:\command.com /e:32768 /p
  

Windows ME.   To run the MATLAB add-in for Visual Studio on Windows ME systems, do the following:

1. Find C:\windows\system\conagent.exe in the Windows Explorer.
2. Right click on the conagent.exe icon.
3. Select Properties from the context menu. This brings up the CONAGENT.EXE Properties window.
4. Select the Memory tab in the CONAGENT.EXE Properties window.
5. Set the Initial Environment field to 4096.
6. Click Apply.
7. Click OK.

For additional information on the MATLAB add-in for Visual Studio:

• See the MATLABAddin.hlp file in the <matlab>\bin\win32 directory, or
• Click on the Help icon in the MATLAB add-in for Visual Studio toolbar.
  
  

Custom Building on UNIX

Troubleshooting