MATLAB Compiler

mcc

Invoke MATLAB Compiler.

Syntax

mcc [-options] mfile1       [mfile2 ... mfileN]
                            [C/C++file1 ... C/C++fileN]

Description

mcc is the MATLAB command that invokes the MATLAB Compiler. You can issue the mcc command either from the MATLAB command prompt (MATLAB mode) or the DOS or UNIX command line (stand-alone mode).

Command Line Syntax

You may specify one or more MATLAB Compiler option flags to mcc. Most option flags have a one-letter name. You can list options separately on the command line, for example,

mcc -m -g myfun

You can group options that do not take arguments by preceding the list of option flags with a single dash (-), for example,

mcc -mg myfun

Options that take arguments cannot be combined unless you place the option with its arguments last in the list. For example, these formats are valid.

mcc -m -A full myfun         % Options listed separately
mcc -mA full myfun           % Options combined, A option last

This format is not valid.

mcc -Am full myfun           % Options combined, A option not last

In cases where you have more than one option that takes arguments, you can only include one of those options in a combined list and that option must be last. You can place multiple combined lists on the mcc command line.

If you include any C or C++ filenames on the mcc command line, the files are passed directly to mex or mbuild, along with any Compiler-generated C or C++ files.

Using Macros to Simplify Compilation

The MATLAB Compiler, through its exhaustive set of options, gives you access to the tools you need to do your job. If you want a simplified approach to compilation, you can use one simple option, i.e., macro, that allows you to quickly accomplish basic compilation tasks. If you want to take advantage of the power of the Compiler, you can do whatever you desire to do by choosing various Compiler options.

This table shows the relationship between the macro approach to accomplish a standard compilation and the multioption alternative.

Table 7-1: Macro Options

Macro Option	Bundle File	Creates	Option Equivalence Translate M to C/C++  | Function Wrapper  |  |         Target Language  |  |           |     Output Stage  |  |           |      |          Helper Functions  |  |           |      |           |  |  |           |      |           |  M-File Library  |  |           |      |           |     |
-m	macro_option_m	Stand-alone C application	-t -W main     -L C   -T link:exe -h     libmmfile.mlib
-p	macro_option_p	Stand-alone C++ application	-t -W main     -L Cpp -T link:exe -h     libmmfile.mlib
-x	macro_option_x	MEX-function	-t -W mex      -L C   -T link:mexlibrary libmatlbmx.mlib
-S	macro_option_S	Simulink S-function	-t -W simulink -L C   -T link:mex        libmatlbmx.mlib
-B sgl	sgl	Stand-alone C graphics library application	-m -W mainhg                             libmwsglm.mlib
-B sglcpp	sglcpp	Stand-alone C++ graphics library application	-p -W mainhg                             libmwsglm.mlib
-B pcode	pcode	MATLAB P-code	-t             -L P
-g	macro_option_g	Enable debug	-G -A debugline:on -O none

Understanding a Macro Option.   The -m option tells the Compiler to produce a stand-alone C application. The -m macro is equivalent to the series of options

-t -W main -L C -T link:exe -h libmmfile.mlib

This table shows the five options that compose the -m macro and the information that they provide to the Compiler.

Table 7-2: The -m Macro 

Option	Function
-t	Translate M code to C/C++ code.
-W main	Produce a wrapper file suitable for a stand-alone application.
-L C	Generate C code as the target language.
-T link:exe	Create an executable as the output.
-h	Automatically, find and compile helper functions included in the source M-file.
libmmfile.mlib	Link to this shared library whenever necessary.

Changing Macro Options.   You can change the meaning of a macro option by editing the corresponding macro_option file bundle file in <matlab>/toolbox/compiler/bundles. For example, to change the -x macro, edit the file macro_option_x in the bundles directory.

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. Your preferences directory ($HOME/.matlab/R12 on UNIX, <system root>\profiles\<user>\application data\mathworks\matlab\R12 on 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.

Note    If you need to change the meaning of a macro to satisfy your individual requirements, you should create or modify your mccstartup file in the preferences directory. Changing the file macro_option_x in the bundles directory changes the option for all Compiler users. To see the name of your preferences directory, type prefdir at the command prompt.

Setting a MATLAB Path in the Stand-Alone MATLAB Compiler

Unlike the MATLAB version of the Compiler, which inherits a MATLAB path from MATLAB, the stand-alone version has no initial path. If you want to set up a default path, you can do so by making an mccpath file. To do this:

1. Create a text file containing the text -I <your_directory_here> for each directory you want on the default path, and name this file mccpath. (Alternately, you can call the MCCSAVEPATH M-function from MATLAB to create an mccpath file.)
2. Place this file in your preferences directory. To do so, run the following commands at the MATLAB prompt.

cd(prefdir); mccsavepath;

These commands save your current MATLAB path to a file named mccpath in your user preferences directory. (Type prefdir to see the name of your preferences directory.)

The stand-alone version of the MATLAB Compiler searches for the mccpath file in your current directory and then your preferences directory. If it finds an mccpath file, it processes the directories specified within the file and uses them to initialize its search path. Note that you may still use the -I option on the command line or in mccstartup files to add other directories to the search path. Directories specified this way are searched after those directories specified in the mccpath file.

Conflicting Options on Command Line

If you use conflicting options, the Compiler resolves them from left to right, with the rightmost option taking precedence. For example, using the equivalencies in Table 7-1, Macro Options,,

mcc -m -W none test.m

is equivalent to

mcc -t -W main -L C -T link:exe -h -W none test.m

In this example, there are two conflicting -W options. After working from left to right, the Compiler determines that the rightmost option takes precedence, namely, -W none, and the Compiler does not generate a wrapper.

Note    Macros and regular options may both affect the same settings and may therefore override each other depending on their order in the command line.

Handling Full Pathnames

If you specify a full pathname to an M-file on the mcc command line, the Compiler:

1. Breaks the full name into the corresponding path- and filenames (<path> and <file>).
2. Replaces the full pathname in the argument list with "-I <path> <file>". For example,

mcc -m /home/user/myfile.m

would be treated as

mcc -m -I /home/user myfile.m

In rare situations, this behavior can lead to a potential source of confusion. For example, suppose you have two different M-files that are both named myfile.m and they reside in /home/user/dir1 and /home/user/dir2. The command

mcc -m -I /home/user/dir1 /home/user/dir2/myfile.m

would be equivalent to

mcc -m -I /home/user/dir1 -I /home/user/dir2 myfile.m

The Compiler finds the myfile.m in dir1 and compiles it instead of the one in dir2 because of the behavior of the -I option. If you are concerned that this might be happening, you can specify the -v option and then see which M-file the Compiler parses. The -v option prints the full pathname to the M-file.

Note    The Compiler produces a warning (specified_file_mismatch) if a file with a full pathname is included on the command line and it finds it somewhere else.

Compiling Embedded 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 -x 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 -x 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.

mbuild

MATLAB Compiler Option Flags