FMEX(1L)

NAME
fmex - builds a MATLAB MEX-file from Fortran sources

SYNOPSIS
fmex    [ -Dname[=def] -g -Ipathname -llibrary
        -Ldir -O[level] -Uname -v3.5 -v name=[def]
    -ofilename CASE=value -help ]
    sourcefile ... [ objectfile ] ... [ library ] ...

DESCRIPTION
fmex is a shell script that compiles and links MEX source files into a relocatable executable image. This image can be executed only from within MATLAB. The resulting file has a ".mex###" extension, where ### identifies the architecture of the machine. The following list shows the MEX-file extensions for UNIX platforms.

    mex4 - Sun SPARC (SunOS4)
    mexsol - Sun SPARC (Solaris 2)
    mexaxp - DEC Alpha
    mexds - DEC MIPS
    mexhp7 - HP 9000/700
    mexrs6 - IBM RS/6000
        mexsg - SGI IRIS 4D Series
        mexhp3 - HP 9000/300,400

The first file name specified as an argument to fmex (i.e., sourcefile in the SYNOPSIS) is used as the name of the resulting MEX-file (less any file name extension such as .f). You can also specify any additional source, object, or library files to satisfy external references. You can specify both C and Fortran source files.

If MATLAB detects a file with a .mex extension, it loads it before a corresponding M-file in the same directory. Therefore, you should install the MEX-File in a directory that is on your MATLAB search path, as defined by MATLABPATH. The resulting MEX-File generally executes faster than the corresponding M-file.

fmex generally works as supplied. However, there are two ways in which you can control the way fmex works:

    •   By specifying command-line options

    •   By assigning values in the MEX startup file, .mexrc.sh

The file .mexrc.sh is a shell script that contains macro definitions for a number of variables that fmex uses. These variables are defined within fmex, but can be redefined in .mexrc.sh. When called, fmex looks for the first occurance of .mexrc.sh in the current directory, in the $HOME directory, and in the matlab/bin directory (where the template version of .mexrc.sh is located).

You can edit the template file to redefine information used by fmex. You can copy the edited version to your current or home directory if you do not want your changes applied system wide.

The .mexrc.sh file defines the following variables for each supported platform:

    ________________________________________________
    Variable     What It Defines
    ------------------------------------------------
    MATLAB    The MATLAB root directory

    CC    The C compiler to use

    CFLAGS    C compiler options

    FC    The Fortran compiler to use

    FFLAGS    Fortran compiler flags

    LD_CCLIBS    Libraries for ld(1)

    LD_FCLIBS    Libraries for ld(1) that include Fortran 77
            objects
    --------------------------------------------------

To see the default values of these variables, enter the fmex command on the MATLAB command line with no arguments:

    >>!fmex

To see the values of the variables including those read from the file .mexrc.sh and with pathnames fully exapanded, use the -v option:

    >>!fmex -v

OPTIONS

Options specified on the command line with fmex are passed to the Fortran/C compiler and linker. The -D, -I, and -U options are useful with Fortran compilers that first pass the source file through the C preprocessor, cpp(1). Most Berkeley UNIX f77 Fortran compilers automatically do this if the source file extension is ".F" instead of ".f". See the documentation for your Fortran compiler for more information.

Note that you must explicitly specify the -O option to produce optimized code. Different compilers interpret the -O[level] option differently. See your compiler documentation to determine what levels you can specify.

You can pass shell variable names as option values (i.e., the values underlined or highlighted in the following list) by enclosing the entire value in SINGLE quotes. This postpones the evaluation of the value until all options have been read. For example, you can use the variable $MATLAB to specify the MATLAB root directory:

    >>!fmex -L'$MATLAB/extern/lib/sun4' my_sourcefile.f

In this expression, $MATLAB is evaluated within fmex after its value has been determined.

-Dname=[def]
    Defines a symbol name to the C preprocessor cpp(1). Equivalent to a #define directive in the source.

-g  Produce additional symbol table information for debugging.

-Ipathname
    Adds pathname to the list of directories in which to search for #include files with relative filenames (i.e., not beginning with slash /). The preprocessor first searches for #include files in the directory containing sourcefile, then in directories named with -I options (if any), and finally, in system wide directories such as /usr/include.

-llibrary
    Links with the object library specified in library (for ld(1)).

-Ldirectory
    Adds directory to the list of directories containing object-library routines (for linking using ld(1)).

-O[level]
    Enables optimization of the object code. See your compiler documentation to determine what values you can specify for level.

-Uname
    Removes any existing definition of the cpp(1) symbol name. (Inverse of the -D option.)

-v3.5
    This option is required to compile MEX-files developed under MATLAB version 3.5 or earlier.

-v  Prints the values of internal variables after sourcing .mexrc.sh and evaluating all arguments. Prints each compile step and final link step, allowing you to see which options and files were used. This option is useful for debugging purposes.

name=[def]
    Define a variable. Strings must be enclosed in quotes and cannot contain any interior double quotes. This definition overrides any variable already defined in the fmex either by a default value, being set in the .mexrc.sh file, or by passing through the environment.

CASE=value
    This option expands the flexibility of fmex for use in networks with various combinations of OS versions, compilers, and loaders on a given platform. It allows you to add additional case statements to the file .mexrc.sh and specify which branch to take on the command line. See the file matlab/bin/README.mex for an example of how to use this option.

-help
    Returns syntax information on fmex.

EXAMPLES
The following command, when entered at the MATLAB prompt, compiles the source file vdpol.f into the executable MEX-file vdpol.mex4 (on a Sun-4) using the optimizer option.

    >>!fmex -O vdpol.f

DEPENDENCIES
On all platforms except Sun SPARC (SunOS4) and DEC MIPS, MEX-files are object modules that are dynamically loaded by MATLAB. There is no libmex.a to link against. The symbols required by MEX-files are exported by the MATLAB program and resolved when loaded. Libraries other than the default Fortran, math, and C libraries must be specified on the command line and be sharable or contain position independent code.

By default, external symbols declared in MEX-files are not added to the global symbol name space. This is consistent with MEX-file behavior on other platforms. For further information, refer to the man pages for ld.

FILES

.mexrc.sh, $HOME/.mexrc.sh, matlab/bin/.mexrc.sh
    Mex startup file that is sourced from the first file found on the above list. It allows the user to set the values for important directories, files, and environment variables. Use the template file, matlab/bin/.mexrc.sh as a starting point if you need to modify you fmex environment.

matlab/extern/lib/arch/libmex.a
    Library needed to link MEX objects, where arch is replaced by the architecture (e.g., "sun4"). Used only on platforms that do not use shared libraries.

matlab/extern/lib/arch/fmex35.o
    Object file containing the main entry point for 3.5 and earlier MEX-files.

matlab/extern/lib/ibm_rs/exp.ibm_rs
    Text file containing a list of symbols exported by MATLAB. Needed for linking mex files on the IBM RS/6000.

FURTHER INFORMATION

See the MATLAB External Interface Guide for information on using MEX-files. Read the file matlab/bin/README.mex for important up to date information on building MEX-files or contact:

    The MathWorks, Inc.
    Cochituate Place
    24 Prime Park Way
    Natick, MA 01760

    508-653-1415

    info@mathworks.com

SEE ALSO
MATLAB(1), CMEX(1)