Accelerating the pace of engineering and science
Documentation Center |
| On this page… |
|---|
What You Need to Build MEX-Files Selecting a Compiler on Windows Platforms |
You need a compiler and the mex function to build MEX-files. MATLAB software supports many compilers and provides computer configuration files, called options files, designed specifically for these compilers. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers Web page.
On 32-bit Microsoft Windows platforms, MATLAB provides a C compiler, Lcc. To view Help on using the Lcc compiler, type:
winopen(fullfile(matlabroot, '\sys\lcc\bin\wedit.hlp'))
If you have multiple compilers installed on your system, you can choose which compiler to use, as described in Selecting a Compiler on Windows Platforms or Selecting a Compiler on UNIX Platforms.
To help you configure your system using a sample MEX-file, see Overview of Building the timestwo MEX-File.
If you have difficulty creating MEX-files, see Creating a Source MEX-File, or refer to Troubleshooting MEX-Files.
A selected compiler configuration specifies the compiler and build options MATLAB uses every time you invoke the mex build script. The compiler in this configuration is the selected compiler. It is the program that compiles source code into object code. A configuration is the set of programs and instructions that builds source code into shared libraries and standalone executable files.
To select a configuration, use the mex -setup command. You can set or change the configuration anytime, from either the MATLAB or the system command prompt. After you choose a configuration, it becomes the default and you no longer have to select one to compile MEX-files.
You can view information about the selected compiler configuration using the mex.getCompilerConfigurations function.
You can change the compiler configuration for a single call to the mex script using the -f switch, which specifies an options file. Subsequent calls to mex continue to use the selected compiler configuration.
For more information about these topics, see:
To see the list of supported compilers on the Windows platform, type:
mex -setup
MATLAB displays the following dialog. The text has been formatted to fit the page.
Note: The list of compilers shown in your version of MATLAB might be different from the list shown in this example. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers Web page. |
Please choose your compiler for building external interface (MEX) files: Would you like mex to locate installed compilers [y]/n? N Select a compiler: [1] Intel C++ 9.1 (with Microsoft Visual C++ 2005 linker) [2] Intel Visual Fortran 10.1 (with Microsoft Visual C++ 2005 linker) [3] Intel Visual Fortran 9.1 (with Microsoft Visual C++ 2005 linker) [4] Lcc-win32 C 2.4.1 [5] Microsoft Visual C++ 6.0 [6] Microsoft Visual C++ .NET 2003 [7] Microsoft Visual C++ 2005 [8] Microsoft Visual C++ 2005 Express Edition [9] Microsoft Visual C++ 2008 [10] Open WATCOM C++ [11] Open WATCOM C++ 1.3 [0] None Compiler: 0 Done . . .
MATLAB helps you choose a compiler configuration by generating a list of either:
All supported compilers. This is the same information found on the Supported and Compatible Compilers Web page. To see this list, follow the instructions in Viewing Supported Windows Compilers.
Installed compilers found on your system. Only compilers supported by MATLAB are in this list.
To select a configuration from a list of supported compilers found on your system, type:
mex -setup
MATLAB displays the following dialog. The text has been formatted to fit the page.
Note: The list of compilers shown on your system might be different from the list shown in this example. The path names to your compilers might also be different. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers Web page. |
Please choose your compiler for building external interface (MEX)
files.
Would you like mex to locate installed compilers [y]/n? y
Select a compiler:
[1] Intel Visual Fortran 9.1 (with Microsoft Visual C++ 2005 linker) in
C:\Program Files\Intel\Compiler\Fortran\9.1
[2] Lcc-win32 C 2.4.1 in C:\PROGRA~1\MATLAB\R2007b\sys\lcc
[3] Microsoft Visual C++ 2005 in
C:\Program Files\Microsoft Visual Studio 8
[0] None
Compiler: 2
Please verify your choices:
Compiler: Lcc-win32 C 2.4.1
Location: C:\PROGRA~1\MATLAB\R2007b\sys\lcc
Are these correct?([y]/n): y
Trying to update options file:
C:\WINNT\Profiles\auser\Application Data\MathWorks\MATLAB\R2007b\
mexopts.bat
From template:
C:\PROGRA~1\MATLAB\R2007b\bin\win32\mexopts\lccopts.bat
Done . . .
When to Change the Selected Compiler Configuration. On Windows systems, if you create C/C++ and Fortran MEX-files, you must choose the appropriate compiler for the language you are using. If your selected compiler is the wrong language, it generates error messages. To see the language of your selected compiler, type:
cc = mex.getCompilerConfigurations; cc.Language
You can change the compiler using either mex -setup or by Specifying a Windows Options File.
On Windows systems, there is one compiler configuration. Use the mex.getCompilerConfigurations function to find the selected compiler configuration.
To get information about the selected compiler, type:
cc = mex.getCompilerConfigurations
MATLAB creates a mex.CompilerConfiguration object cc and displays its properties:
cc =
mex.CompilerConfiguration
package: mex
properties:
Name: 'Microsoft Visual C++ 2005'
Manufacturer: 'Microsoft'
Language: 'C++'
Version: '8.0'
Location: 'C:\Program Files\Microsoft Visual Studio 8'
Details: [1x1 mex.CompilerConfigurationDetails]
list of methods
To see the build options used by the selected compiler, type:
ccOptions = cc.Details
MATLAB creates a mex.CompilerConfigurationDetails object ccOptions and displays the options:
ccOptions =
mex.CompilerConfigurationDetails
package: mex
properties:
CompilerExecutable: 'cl'
CompilerFlags: [1x120 char]
OptimizationFlags: '/O2 /Oy- /DNDEBUG'
DebugFlags: '/Zi /Fd"%OUTDIR%%MEX_NAME%%MEX_EXT%.pdb"'
LinkerExecutable: 'link'
LinkerFlags: [1x257 char]
LinkerOptimizationFlags: ''
LinkerDebugFlags: '/DEBUG
/PDB:"%OUTDIR%%MEX_NAME%%MEX_EXT%.pdb"'
list of methodsMATLAB includes template options files you can use with particular compilers. The options files are located in the following folders.
| Platform | Folder |
|---|---|
| 32-bit Windows | matlabroot\bin\win32\mexopts |
| 64-bit Windows | matlabroot\bin\win64\mexopts |
On Windows systems, the options file has a .bat file extension.
For information on how to modify options files for particular systems, see Custom Building MEX-Files.
Use the -f option to specify an options file. To use this option, at the MATLAB prompt, type:
mex filename -f optionsfile
where optionsfile is the full path to the options file.
You might need to specify an options file if you want to use a different compiler (and not use the -setup option), or you want to compile MAT or engine standalone programs.
A selected compiler configuration specifies the compiler and build options MATLAB uses every time you invoke the mex build script. The compiler in this configuration is the selected compiler. It is the program that compiles source code into object code. A configuration is the set of programs and instructions that builds source code into shared libraries and standalone executable files.
To select a configuration, use the mex -setup command. You can set or change the configuration anytime, from either the MATLAB or the system command prompt. After you choose a configuration, it becomes the default and you no longer have to select one to compile MEX-files.
You can view information about the selected compiler configuration using the mex.getCompilerConfigurations function.
You can change the compiler configuration for a single call to the mex script using the -f switch, which specifies an options file. Subsequent calls to mex continue to use the selected compiler configuration.
For more information about these topics, see:
You can set or change your compiler configuration anytime from either the MATLAB command prompt or the UNIX shell, using the command:
mex -setup
MATLAB generates a list of the available compiler configurations, called options files. To choose a compiler, type the number corresponding to your selection. (If you do not want to change your configuration, type 0. MATLAB returns to the command prompt.) MATLAB displays information about the chosen file.
On UNIX systems, there are three configurations, one for each compiler language (C, C++ and Fortran). Use the mex.getCompilerConfigurations function to view details about the compiler configurations.
To get information about the compiler configuration, type:
cc = mex.getCompilerConfigurations
MATLAB creates a mex.CompilerConfiguration object cc and displays its properties:
cc =
1x3 mex.CompilerConfiguration
package: mex
properties:
Name
Manufacturer
Language
Version
Location
Details
list of methods
On the UNIX platform, cc is an array of three CompilerConfiguration objects – one for each language (C, C++, and Fortran). To see the compiler names, type:
disp('Compiler Name')
for i = 1:3; disp(cc(i).Name); end;
MATLAB displays information like:
Compiler Name GNU C GNU C++ g95
MATLAB includes template options files you can use with particular compilers. The options files are located in matlabroot/bin.
The UNIX options file is named *opts.sh, where * is either mex or a specific compiler name.
For information on how to modify options files for particular systems, see Custom Building MEX-Files.
Use the -f option to specify an options file. To use this option, at the MATLAB prompt, type:
mex filename -f optionsfile
where optionsfile is the full path to the options file.
You might need to specify an options file in the following situations:
You want to use a different compiler (and not use the -setup option), or you want to compile MAT or engine standalone programs.
You do not want to use the system C/C++ compiler.
You can combine multiple source files, object files, and file libraries to build a binary MEX-file. To do this, list the additional files, with their file extensions, separated by spaces. The name of the MEX-file is the name of the first file in the list.
The following command combines multiple files of different types into a binary MEX-file called circle.ext, where ext is the extension corresponding to the current platform:
mex circle.c square.obj rectangle.c shapes.lib
For a Fortran files, type:
mex circle.F square.o rectangle.F shapes.o
You may find it useful to use a software development tool like MAKE to manage MEX-file projects involving multiple source files. Create a MAKEFILE that contains a rule for producing object files from each of your source files, and then invoke the mex build script to combine your object files into a binary MEX-file. This way you can ensure that your source files are recompiled only when necessary.
MATLAB provides an example MEX-file, timestwo, for you to use to configure your system. This function takes a scalar input and doubles it.
The C source file is timestwo.c, and the Fortran source file is timestwo.F. These files are in matlabroot\extern\examples\refbook, where matlabroot is the MATLAB root folder, the value returned by the matlabroot command.
To work with these files, copy them to a local folder. For example:
cd('c:\work')
copyfile([matlabroot '\extern\examples\refbook\timestwo.c'])
copyfile([matlabroot '\extern\examples\refbook\timestwo.F'])
To select your compiler, follow the instructions in either Selecting a Compiler on UNIX Platforms or Selecting a Compiler on Windows Platforms.
Use the mex function to build the binary MEX-file. If you are using a C/C++ compiler, type:
mex timestwo.c
If you are using a Fortran compiler, type:
mex timestwo.F
This command creates the file timestwo.ext, where ext is the value returned by the mexext function. You call timestwo as if it were a MATLAB function. For example, at the MATLAB command prompt, type:
timestwo(4)
MATLAB displays:
ans =
8
Note: In a future version of MATLAB, the default mex function will change to use the large-array-handling API. This means the -largeArrayDims option will be the default and you must review your MEX-files, as described in Upgrading MEX-Files to Use 64-Bit API. For information about mex options, see MEX Script Switches. For information about the large-array-handling API, see Handling Large mxArrays. |