mcc (Compiler 1.2) (MATLAB Compiler 2.0)

Invoke MATLAB Compiler 1.2.

Syntax

mcc -V1.2 [-options] mfile1 [mfile2 ... mfileN]
                            [fun1=feval_arg1 ... funN=feval_argN]

Description

By including the -V1.2 option on the mcc command line, you tell the Compiler that you want to use Compiler 1.2. Compiler 2.0 is the default; not specifying the -V1.2 option automatically uses Compiler 2.0.

Note This reference page provides information on Compiler 1.2. See "mcc (Compiler 2.0)" for the mcc reference page for Compiler 2.0. You can make Compiler 1.2 your default by using an mccstartup file. See "Setting Up Default Options" in this chapter for complete details.

mcc is the MATLAB command that invokes the MATLAB Compiler. You must issue the mcc -V1.2 command from the MATLAB prompt to use Compiler 1.2. When using Compiler 1.2, the only additional required argument to mcc is the name of an M-file. For example, the command to compile the M-file stored in file myfun.m is:

mcc -V1.2 myfun

If you specify a relative pathname for an M-file, the M-file must be in a directory on your MATLAB search path, or in your current directory.

Specifying Options

You may specify one or more MATLAB Compiler option flags to mcc. (The list of options appears later in this reference page.) Most options have a one-letter name. Precede the list of option flags with a single dash (-), or list the options separately. For example, either syntax is acceptable:

mcc -V1.2 -ir myfun
mcc -V1.2 -i -r myfun

Note The -V1.2 option cannot be combined with other options; it must stand by itself. For example, you cannot use

mcc -V1.2ir myfun

You would use

mcc -V1.2 -ir myfun

Setting Up Default Options

If you have some command line options that you wish always to pass to mcc, you can do so by setting up an mccstartup file. Create a text file containing the desired command line options and name the file mccstartup. Place this file in one of two directories:

1.: The current working directory, or

2.: $HOME/matlab (UNIX) or <matlab>\bin (PC)

mcc searches for the mccstartup file in these two directories in the order shown above. If it finds an mccstartup file, it reads it and processes the options within the file as if they had appeared on the mcc command line before any actual command line options. Both the mccstartup file and the -B option are processed the same way.

Building a MEX-File From Multiple M-Files

If the M-file you are compiling calls other M-files, you can list the called M-files on the command line. Doing so causes the MATLAB Compiler to build all the M-files into a single MEX-file, which usually executes faster than separate MEX-files. Note, however, that the single MEX-file has only one entry point regardless of the number of input M-files. The entry point is the first M-file on the command line. For example, suppose that bell.m calls watson.m. Compiling with

mcc -V1.2 bell watson

creates bell.mex. The entry point of bell.mex is the compiled code from bell.m. The compiled version of bell.m can call the compiled version of watson.m. However, compiling as

mcc -V1.2 watson bell

creates watson.mex. The entry point of watson.mex is the compiled code from watson.m. The code from bell.m never gets executed.

As another example, suppose that x.m calls y.m and that y.m calls z.m. In this case, make sure that x.m is the first M-file on the command line. After x.m, it does not matter which order you specify y.m and z.m.

Calling feval

If the M-file you are compiling contains a call to feval, you can use the fun=feval_arg syntax to specify the name of the function to be passed to feval.

Do not put any spaces on either side of the equals sign. Consider these right and wrong ways to specify a feval_arg:

mcc -V1.2 citrus fun1=lemon    % correct
mcc -V1.2 citrus fun1 = lemon  % incorrect

MATLAB Compiler 1.2 Option Flags

Some MATLAB Compiler option flags optimize the generated code, other option flags generate compilation or runtime information, and some option flags are Simulink-specific.

If you use the MATLAB Compiler mcc option flag -p to generate C++ code, then these options are not supported:

-i
-l
-r

-B <filename> (Bundle of Compiler Settings)

Replace -B <filename> on the mcc command line with the contents of the specified file. The file should contain only mcc command line options and corresponding arguments and/or other filenames. The file may contain other
-B options. You can place options that you always set in an mccstartup file. For more information, see "Setting Up Default Options."

-c (C/C++ Code Only)

Generate C/C++ code but do not invoke mex or mbuild, i.e., do not produce a MEX-file.

-e (Stand-Alone External C Code)

Generate C code for stand-alone applications. The resulting C code cannot be used to create MEX-files; it can be linked with the MATLAB C Math Library and executed as a stand-alone application. Stand-alone applications do not require MATLAB at runtime. Stand-alone applications can run even if MATLAB is not installed on the system. See Chapter 4 for complete details on stand-alone applications.

If you specify -e, the MATLAB Compiler does not invoke mex, consequently, it does not produce a MEX-file. However, it does invoke mbuild to create a stand-alone application when the name of the M-file is main.

-f <filename> (Specifying Options File)

Use the specified options file when calling mex or mbuild. This option allows you to use different C or C++ compilers for different invocations of the MATLAB Compiler. This option is a direct pass-through to the mex script. See the Application Program Interface Guide for more information about using this option with the mex script.

Note Although this option works as documented, it is suggested that you use
mex -setup or mbuild -setup to switch compilers.

-g (Debugging Information)

Cause mex or mbuild to invoke the C/C++ compiler with the appropriate C/C++ compiler options for debugging. You should specify -g if you want to debug the MEX-file or stand-alone application with a debugger.

The -g option flag has no influence on the source code that the MATLAB Compiler generates, though it does have some influence on the binary code that the C/C++ compiler generates.

-h (Helper Functions)

Compile helper functions by default. Any helper functions that are called will be compiled into the resulting MEX or stand-alone application.

Using the -h option is equivalent to listing the M-files explicitly on the mcc command line.

The -h option purposely does not include built-in functions or functions that appear in the MATLAB M-File Math Library portion of the C/C++ Math Libraries. This prevents compiling functions that are already part of the C/C++ Math Libraries. If you want to compile these functions as helper functions, you should specify them explicitly on the command line. For example, use

mcc -V1.2 minimize_it fmins

instead of

mcc -V1.2 -h minimize_it

Note Due to MATLAB Compiler 1.2 restrictions, some of the MATLAB 5 versions of the M-files for the C and C++ Math libraries do not compile as is. The MathWorks has rewritten these M-files to conform to the Compiler 1.2 restrictions. The modified versions of these M-files are in

<

matlab>/extern/src/tbxsrc

where <matlab> represents the top-level directory where MATLAB is installed on your system.

-i (Inbounds Code)

Generate C/C++ code that does not:

Check array subscripts to determine if array indexes are within range.
Reallocate the size of arrays when the code requests a larger array. For example, if you preallocate a 10-element vector, the generated code cannot assign a value to the 11th element of the vector.
Check input arguments to determine if they are real or complex.

The -i option flag can make a program run significantly faster, but not every M-file is a good candidate for -i. For instance, you can specify -i only if your M-file preallocates all arrays. You typically preallocate arrays with the zeros or ones function.

If an M-file contains code that causes an array to grow, then you cannot compile with the -i option. Using -i on such an M-file produces a MEX-file that fails at runtime.

Note This option flag has no effect on C++ generated code, i.e., if the -p MATLAB Compiler option flag is used.

-l (Line Numbers)

Generate C/C++ code that prints line numbers on internally detected errors. This option flag is useful for debugging, but causes the MEX-file to run slightly slower.

Note This option flag has no effect on C++ generated code, i.e., if the -p MATLAB Compiler option flag is used.

-m (main Routine)

Generate a C function named main. The name the MATLAB Compiler gives to your C function depends on the combination of option flags.


Option Flags	Resulting Function Name
neither `-m` nor `-e`	`mexFunction`
`-m` only	`main`
`-e` only	`mlfMfile1`
`-m` and `-e`	`main`

If you specify -m and place multiple M-files on the compilation command line:

The MATLAB Compiler applies the -m option to the first M-file only.
The MATLAB Compiler assumes the -e option for all subsequent M-files.

The generated main function reads and writes from the standard input and standard output streams. POSIX-compliant operating systems include UNIX and Microsoft Windows. Other operating systems may require window-system specific changes for this code to work.

If your main M-function includes input or output arguments, the MATLAB Compiler will instantiate the input arguments using the command line arguments passed in by the POSIX shell. It will return the first output value produced by the M-file as the status. In this way, you can compile command line M-files into POSIX-compliant command line applications. For example,

function    sts = echo(a, b, c)
            display(a);
            display(b);
            display(c);
            sts = 0;

This function echoes its three input arguments. It will function as an M-file exactly the same way as it functions as a stand-alone application generated using the -m option. Note that only strings are passed as input variables from the POSIX shell and only a single scalar integer status is returned. Therefore, the -m option does not work well for mathematical M-files.

-M "string" (Direct Pass Through)

Pass string directly to the mex or mbuild script. This provides a useful mechanism for defining compile-time options, e.g., -M "-Dmacro=value".

-p (Stand-Alone External C++ Code)

Generate C++ code for stand-alone applications. The resulting C++ code cannot be used to create MEX-files; it can be linked with the MATLAB C++ Math Library and executed as a stand-alone application. Stand-alone applications do not require MATLAB at runtime. Stand-alone applications can run even if MATLAB is not installed on the system. See Chapter 4 for complete details on stand-alone applications.

-q (Quick Mode)

Quick mode executes only one pass through the type imputation and assumes that complex numbers are contained in the inputs. Use Quick mode if at least one of the parameters to the functions being compiled is complex.

-r (Real)

Generate C code based on the assumption that all input, output, and temporary data in the MEX-file are real (not complex).

The -r option flag can make a program run significantly faster. However, if your program contains any complex data, do not compile with -r.

Placing the %#realonly pragma anywhere in the input M-file has the same effect as compiling with -r.

If you compile with -r but specify complex input data at runtime, the MEX-file issues a fatal error. However, if you compile with both -r and -i, the MEX-file does not check to see if the input data is complex. If the input data is complex, the MEX-file will fail at runtime.

Note This option flag has no effect on C++ generated code, i.e., if the -p MATLAB Compiler option flag is used.

-s (Static)

Translate MATLAB global variables to static C (local) variables. Compiling without -s causes the MATLAB Compiler to generate code that preserves the global status of any variables marked as global in an M-file.

Suppose that you tag n as a global variable in the MATLAB interpreter workspace:

global n
n = 3;

Consider an M-file that accesses global variable n:

function m = earth
global n;
m = magic(n);

Compiling earth.m without -s yields a MEX-file that can access the value of global variable n:

mcc earth
earth
ans =
     8    1    6
     3    5    7
     4    9    2

Compiling earth.m with -s yields a MEX-file that cannot access the value of global variable n:

mcc -s earth
earth
??? Error using ==> magic
Size vector must be a row vector with integer elements.

MEX-files access global variables very slowly because MEX-files have to call back to the MATLAB interpreter to obtain the value of a global variable.

Some programmers tag variables as global solely to recall a value from one invocation of the MEX-file to the next. If you are using global for this reason, then you should consider specifying the -s option flag when you compile. Doing so makes your MEX-file run faster. Compiling with -s causes the MEX-file to store the value of the variable locally; no callback is needed to access the variable's value. The disadvantage to -s is that global variables are no longer really global; other programs cannot access them.

Note This option flag has no effect on C++ generated code, i.e., if the -p MATLAB Compiler option flag is used.

-S (Simulink S-Function)

Output a Simulink S-function with a dynamically sized number of inputs and outputs. You can pass any number of inputs and outputs in or out of the generated S-function. Since the MATLAB Fcn block and the S-Function block are single-input, single-output blocks, only one line can be connected to the input or output of these blocks. However, each line may be a vector signal, essentially giving these blocks multi-input, multi-output capability.

Note The MATLAB Compiler option that generates a C language S-function is a capital S (-S). Do not confuse it with the lowercase -s option that translates MATLAB global variables to static C (local) variables.

-t (Tracing Statements)

Generate tracing print statements. This option flag is useful for debugging, though it tends to generate a significant amount of information.

Note This option flag has no effect on C++ generated code, i.e., if the -p MATLAB Compiler option flag is used.

-u (Number of Inputs)

Provide more control over the number of valid inputs for your Simulink S-function. This option specifically sets the number of inputs for your function. If -u is omitted, the input will be dynamically sized.

-v (Verbose)

Display the steps in compilation, including:

The command that is invoked
The Compiler version number
The invocation of mex/mbuild

The -v flag passes the -v flag to mex or mbuild and displays information about mex or mbuild. This option passes the full pathname of the file being compiled.

-w (Warning) and -ww (Complete Warnings)

Display warning messages indicating where sections of generated code are likely to slow execution (for example, where the code contains callbacks to MATLAB). This option flag does not affect the performance of the generated code.

If you omit -w, the MATLAB Compiler suppresses most warning messages, but still displays serious warning messages.

If you specify -w, the MATLAB Compiler displays up to 30 warning messages. If there are more than 30 warning messages, the MATLAB Compiler suppresses those past the 30th. To see all warning messages, use the -ww option.

-y (Number of Outputs)

Provide more control over the number of valid outputs for your Simulink S-function. This option specifically sets the number of outputs (y) for your function. If -y is omitted, the output will be dynamically sized.

-z <path> (Specifying Library Paths)

Specify the path to use for library and include files. This option uses the specified path for compiler libraries instead of the path returned by matlabroot.

Examples

Compile gazelle.m to create gazelle.mex:

mcc -V1.2 gazelle

Optimize the performance of gazelle.mex by compiling with two optimization option flags:

mcc -V1.2 -ri gazelle

Compile two M-files (gazelle.m and cheetah.m) to create one MEX-file (gazelle.mex):

mcc -V1.2 gazelle cheetah

Compile gazelle.m to create gazelle.c (C source code for a stand-alone application):

mcc -V1.2 -e gazelle

Given leopard.m, an M-file containing a call to feval:

function leopard(fun1,x) 
y = feval(fun1,x); 
plot(x,y,'r+');

Compile leopard.m, telling the MATLAB Compiler that function fun1 corresponds to myfun:

mcc -V1.2 leopard fun1=myfun

Compile myfun.m to create a real, external version that includes a direct call to auxfun1, and replaces feval(afun, . . .) by feval(auxfun2, . . .):

mcc -V1.2 -ire myfun auxfun1 afun=auxfun2

Make a quick-compiled version of myfun.m and compile all of the helper.m functions into a single object:

mcc -V1.2 -q -h myfun