|
External Interfaces MATLAB Data Custom Building MEX-Files
Building MEX-Files
This section covers the following topics:
*
Compiler Requirements
*
Testing Your Configuration on UNIX
*
Testing Your Configuration on Windows
*
Specifying an Options File
Compiler Requirements
Your installed version of MATLAB contains all the tools you need to work with the API. MATLAB includes a C compiler for the PC called Lcc, but does not include a Fortran compiler. If you choose to use your own C compiler, it must be an ANSI C compiler. Also, if you are working on a Microsoft Windows platform, your compiler must be able to create 32-bit windows dynamically linked libraries (DLLs).
MATLAB supports many compilers and provides preconfigured files, called options files, designed specifically for these compilers. The purpose of supporting this large collection of compilers is to provide you with the flexibility to use the tool of your choice. However, in many cases, you simply can use the provided Lcc compiler with your C code to produce your applications.
The MathWorks maintains a list of compilers supported by MATLAB at the following location on the Web: http://www.mathworks.com/support/tech-notes/1600/1601.html.
Note The MathWorks provides an option called -setup for the mex script that lets you easily choose or switch your compiler.
The following sections contain configuration information for creating MEX-files on UNIX and Windows systems. More detailed information about the mex script is provided in Custom Building MEX-Files. In addition, there is a section on Troubleshooting, if you are having difficulties creating MEX-files.
Testing Your Configuration on UNIX
The quickest way to check if your system is set up properly to create MEX-files is by trying the actual process. There is C source code for an example, yprime.c, and its Fortran counterpart, yprimef.F and yprimefg.F, included in the matlabroot/extern/examples/mex directory, where matlabroot represents the top-level directory where MATLAB is installed on your system.
To compile and link the example source files, yprime.c or yprimef.F and yprimefg.F, on UNIX, you must first copy the file(s) to a local directory, and then change directory (cd) to that local directory.
At the MATLAB prompt, type
mex yprime.c
This uses the system compiler to create the MEX-file called yprime with the appropriate extension for your system.
You can now call yprime as if it were an M-function:
yprime(1,1:4)
ans =
2.0000 8.9685 4.0000 -1.0947
To try the Fortran version of the sample program with your Fortran compiler, at the MATLAB prompt, type
mex yprimef.F yprimefg.F
In addition to running the mex script from the MATLAB prompt, you can also run the script from the system prompt.
Selecting a Compiler
To change your default compiler, you select a different options file. You can do this anytime by using the command
mex -setup
Using the 'mex -setup' command selects an options file that is
placed in ~/matlab and used by default for 'mex'. An options
file in the current working directory or specified on the
command line overrides the default options file in ~/matlab.
Options files control which compiler to use, the compiler and
link command options, and the runtime libraries to link
against.
To override the default options file, use the 'mex -f' command
(see 'mex -help' for more information).
The options files available for mex are:
1: matlabroot/bin/gccopts.sh :
Template Options file for building gcc MEXfiles
2: matlabroot/bin/mexopts.sh :
Template Options file for building MEXfiles using the
system ANSI compiler
Enter the number of the options file to use as your default
options file:
Select the proper options file for your system by entering its number and pressing Enter. If an options file doesn't exist in your MATLAB directory, the system displays a message stating that the options file is being copied to your user-specific matlab directory. If an options file already exists in your matlab directory, the system prompts you to overwrite it.
Note The -setup option creates a user-specific matlab directory in your individual home directory and copies the appropriate options file to the directory. (If the directory already exists, a new one is not created.) This matlab directory is used for your individual options files only; each user can have his or her own default options files (other MATLAB products may place options files in this directory). Do not confuse these user-specific matlab directories with the system matlab directory, where MATLAB is installed. To see the name of this directory on your machine, use the MATLAB command prefdir.
Using the setup option resets your default compiler so that the new compiler is used every time you use the mex script.
Testing Your Configuration on Windows
Before you can create MEX-files on the Windows platform, you must configure the default options file, mexopts.bat, for your compiler. The -setup option provides an easy way for you to configure the default options file. To configure or change the options file at anytime, run
mex -setup
from either the MATLAB or DOS command prompt.
Lcc Compiler
MATLAB includes a C compiler called Lcc that you can use to create C MEX-files. Help on using the Lcc compiler is available in a help file that ships with MATLAB. To view this file, type in the MATLAB command window
!matlabroot\sys\lcc\bin\wedit.hlp
replacing the term matlabroot with the path to the directory in which MATLAB is installed on your system. (Type matlabroot in the Command Window to get the path for this directory.)
Selecting a Compiler
The mex script uses the Lcc compiler by default if you do not have a C or C++ compiler of your own already installed on your system and you try to compile a C MEX-file. If you need to compile Fortran programs, you must supply your own supported Fortran compiler.
The mex script uses the filename extension to determine the type of compiler to use for creating your MEX-files. For example,
mex test1.F
uses your Fortran compiler and
mex test2.c
uses your C compiler.
On Systems without a Compiler. If you do not have your own C or C++ compiler on your system, the mex utility automatically configures itself for the included Lcc compiler. So, to create a C MEX-file on these systems, you can simply enter
mex filename.c
This simple method of creating MEX-files works for the majority of users.
If using the included Lcc compiler satisfies your needs, you can skip ahead in this section to Building the MEX-File on Windows.
On Systems with a Compiler. On systems where there is a C, C++, or Fortran compiler, you can select which compiler you want to use. Once you choose your compiler, that compiler becomes your default compiler and you no longer have to select one when you compile MEX-files. To select a compiler or change to existing default compiler, use mex -setup.
This example shows the process of setting your default compiler to the Microsoft Visual C++ Version 6.0 compiler:
mex -setup
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] Compaq Visual Fortran version 6.6
[2] Lcc C version 2.4
[3] Microsoft Visual C/C++ version 6.0
[0] None
Compiler: 3
Your machine has a Microsoft Visual C/C++ compiler located at
D:\Applications\Microsoft Visual Studio. Do you want to use this
compiler [y]/n? y
Please verify your choices:
Compiler: Microsoft Visual C/C++ 6.0
Location: C:\Program Files\Microsoft Visual Studio
Are these correct?([y]/n): y
The default options file:
"C:\WINNT\Profiles\username\ApplicationData\MathWorks\MATLAB\R1
3\mexopts.bat" is being updated from ...
If the specified compiler cannot be located, you are given the message:
The default location for compiler-name is directory-name,
but that directory does not exist on this machine.
Use directory-name anyway [y]/n?
Using the setup option sets your default compiler so that the new compiler is used every time you use the mex script.
Building the MEX-File on Windows
There is example C source code, yprime.c, and its Fortran counterpart, yprimef.F and yprimefg.F, included in the matlabroot\extern\examples\mex directory, where matlabroot represents the top-level directory where MATLAB is installed on your system.
To compile and link the example source file on Windows, at the MATLAB prompt, type
cd([matlabroot '\extern\examples\mex'])
mex yprime.c
This should create the MEX-file called yprime with the .mexw32 extension, which corresponds to the 32-bit Windows platform.
You can now call yprime as if it were an M-function:
yprime(1,1:4)
ans =
2.0000 8.9685 4.0000 -1.0947
To try the Fortran version of the sample program with your Fortran compiler, switch to your Fortran compiler using mex -setup. Then, at the MATLAB prompt, type
cd([matlabroot '\extern\examples\mex'])
mex yprimef.F yprimefg.F
In addition to running the mex script from the MATLAB prompt, you can also run the script from the system prompt.
Specifying an Options File
You can use the -f option to specify an options file on either UNIX or Windows. To use the -f option, at the MATLAB prompt type
mex filename -f <optionsfile>
and specify the name of the options file along with its pathname.
There are several situations when it may be necessary to specify an options file every time you use the mex script. These include
*
(Windows and UNIX) You want to use a different compiler (and not use the -setup option), or you want to compile MAT or engine stand-alone programs.
*
(UNIX) You do not want to use the system C compiler.
Preconfigured Options Files
MATLAB includes some preconfigured options files that you can use with particular compilers. The options files are located in the directory matlabroot\bin\win32\mexopts on Windows, matlabroot\bin\win64\mexopts on Windows x64, and matlabroot/bin on UNIX, wherematlabroot stands for the MATLAB root directory as returned by the matlabroot command. On Windows and Windows x64, the options files are named *.bat, where * stands for the compiler type and version. On UNIX, the options file is named *opts.sh, where * stands for mex or a specific compiler.
For a list of all the compilers supported by MATLAB, see the following location on the Web: http://www.mathworks.com/support/tech-notes/1600/1601.html.
Note The next section, Custom Building MEX-Files, contains specific information on how to modify options files for particular systems.
MATLAB Data MATLAB Data Custom Building MEX-Files Custom Building MEX-Files
© 1984-2007 The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
|