MATLAB Compiler

MATLAB Compiler Option Flags

The MATLAB Compiler option flags perform various functions that affect the generated code and how the Compiler behaves. This table shows the categories of the Compiler options.

Table 7-3: Compiler Option Categories  

Category	Purpose
Macros	The macro options simplify the compilation process by combining the most common compilation tasks into single options.
Code Generation	These options affect the actual code that the Compiler generates. For example, -L specifies the target language as either C or C++.
Compiler and Environment	These options provide information to the Compiler such as where to put (-d) and find (-I) particular files.
mbuild/mex	These options provide information for the mbuild and/or mex scripts.

The remainder of this reference page is subdivided into sections that correspond to the Compiler option categories. Each section provides a full description of all of the options in the category.

Macro Options

The macro options provide a simplified way to accomplish basic compilation tasks.

-m (Stand-Alone C).   Produce a stand-alone C application. It includes helper functions by default (-h), and then generates a stand-alone C wrapper (-W main). In the final stage, this option compiles your code into a stand-alone executable and links it to the MATLAB C/C++ Math Library (-T link:exe). For example, to translate an M-file named mymfile.m into C and to create a stand-alone executable that can be run without MATLAB, use

mcc -m mymfile

The -m option is equivalent to the series of options

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

-p (Stand-Alone C++).   Produce a stand-alone C++ application. It includes helper functions by default (-h), and then generates a stand-alone C++ wrapper (-W main). In the final stage, this option compiles your code into a stand-alone executable and links it to the MATLAB C/C++ Math Library (-T link:exe). For example, to translate an M-file named mymfile.m into C++ and to create a stand-alone executable that can be run without MATLAB, use

mcc -p mymfile

The -p option is equivalent to the series of options

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

-S (Simulink S-Function).   Produce a Simulink S-function that is compatible with the Simulink S-function block. For example, to translate an M-file named mymfile.m into C and to create the corresponding Simulink S-function using dynamically sized inputs and outputs, use

mcc -S mymfile

The -S option is equivalent to the series of options

-W simulink -L C -t -T link:mex libmatlbmx.mlib

-x (MEX-Function).   Produce a MEX-function. For example, to translate an M-file named mymfile.m into C and to create the corresponding MEX-file that can be called directly from MATLAB, use

mcc -x mymfile

The -x option is equivalent to the series of options

-W mex -L C -t -T link:mexlibrary libmatlbmx.mlib

-B sgl (Stand-Alone C Graphics Library).   Produce a stand-alone C application that uses Handle Graphics.

The -B sgl option is equivalent to the series of options

-m -W mainhg libmwsglm.mlib

-B sglcpp (Stand-Alone C++ Graphics Library).   Produce a stand-alone C++ application that uses Handle Graphics.

The -B sglcpp option is equivalent to the series of options

-p -W mainhg libmwsglm.mlib

-B pcode (MATLAB P-Code).   Produce MATLAB P-code.

The -B pcode option is equivalent to the series of options

-t -L P

Code Generation Options

-A (Annotation Control for Output Source).   Control the type of annotation in the resulting C/C++ source file. The types of annotation you can control are:

• M-file code and/or comment inclusion (annotation)
• #line preprocessor directive inclusion (line)
• Whether error messages report the source file and line number (debugline)

To control the M-file code that is included in the generated C/C++ source, use

mcc -A annotation:type ...

This table shows the available types of code and comment annotation options.

Table 7-4: Code/Comment Annotation Options

type	Description
all	Provides the complete source of the M-file interleaved with the generated C/C++ source. The default is all.
comments	Provides all of the comments from the M-file interleaved with the generated C/C++ source.
none	No comments or code from the M-file are added to code.

To control the #line preprocessor directives that are included in the generated C/C++ source, use

mcc -A line:setting ...

The table shows the available #line directive settings.

Table 7-5: Line Annotation Options

Setting	Description
on	Adds #line preprocessor directives to the generated C/C++ source code to enable source M-file debugging. Note: The page width option is ignored when this is on.
off	Adds no #line preprocessor directives to the generated C/C++ source code. The default is off.

To control if run-time error messages report the source file and line number, use

mcc -A debugline:on ...

This table shows the available debugline directive settings.

Table 7-6: Run-Time Error Annotation Options

Setting	Description
on	Specifies the presence of source file and line number information in run-time error messages.
off	Specifies no source file and line number information in run-time error messages. The default is off.

For example:

To include all of your M-code, including comments, in the generated file and the standard #line preprocessor directives, use

mcc -A annotation:all -A line:on ...
or
mcc -A line:on ... (The default is all for code/comment inclusion.)

To include none of your M-code and no #line preprocessor directives, use

mcc -A annotation:none -A line:off ...

To include the standard #line preprocessor directives in your generated C/C++ source code as well as source file and line number information in your run-time error messages, use

mcc -A line:on -A debugline:on ...

-F <option> (Formatting).   Control the formatting of the generated code. This table shows the available options.

Table 7-7: Formatting Options  

<Option>	Description
list	Generates a table of all the available formatting options.
expression-indent:n	Sets the number of spaces of indentation for all expressions to n, where n is an integer. The default indent is 4.
page-width:n	Sets maximum width of generated code to n, where n is an integer. The default width is 80.
statement-indent:n	Sets the number of spaces of indentation for all statements to n, where n is an integer. The default indent is 2.

-g (Debug).   This option is a macro that is equivalent to

-G -A debugline:on -O none

In addition to the -G option, the -g option includes the -A debugline:on option. This will have an impact on performance of the generated code. If you wish to have debugging information, but do not want the performance degradation associated with the debug line information, use -g -A debugline:off. The -g option also includes the -O none option, causing all compiler optimizations to be turned off. If you wish to have some optimizations on, you may specify them after the debug option.

-l (Line Numbers) .   Generate C/C++ code that prints filename and line numbers on run-time errors. This option flag is useful for debugging, but causes the executable to run slightly slower. This option is equivalent to

mcc -A debugline:on ...

-L <language> (Target Language).   Specify the target language of the compilation. Possible values for language are C or Cpp. The default is C. Note that these values are case insensitive.

-O <option> (Optimization Options).   Optimizes your M-file source code so that the performance of the generated C/C++ code may be faster than the performance of the M-code in the MATLAB interpreter. This table shows the available options.

Table 7-8: Optimization Options  

<Option>	Description
-O list	Lists all available optimizations.
-O all	Turns on all optimizations; all is the default.
-O none	Turns off all optimizations.
-O <opt option>:[on|off]	Enables or disables individual optimizations, where: <opt option> is: fold_scalar_mxarrays fold_non_scalar_mxarrays array_indexing optimize_integer_for_loops optimize_conditionals

-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 (u) for your function. If -u is omitted, the input will be dynamically sized. (Used with -S option.)

-W <type> (Function Wrapper).   Control the generation of function wrappers for a collection of Compiler-generated M-files. You provide a list of functions and the Compiler generates the wrapper functions and any appropriate global variable definitions. This table shows the valid type options.

Table 7-9: Function Wrapper Types  

<Type>	Description
mex	Produces a mexFunction() interface.
main	Produces a POSIX shell main() function.
simulink	Produces a Simulink C MEX S-function interface.
lib:<string>	Produces an initialization and termination function for use when compiling this Compiler-generated code into a larger application. This option also produces a header file containing prototypes for all public functions in all M-files specified. <string> becomes the base (file) name for the generated C/C++ and header file. Creates a .exports file that contains all nonstatic function names.
none	Does not produce a wrapper file. none is the default.

-y (Number of Outputs).   Provides 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. (Used with -S option.)

Compiler and Environment Options

-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 Code Only).   Generate C code but do not invoke mex or mbuild, i.e., do not produce a MEX-file or stand-alone application. This is equivalent to -T codegen placed at the end of the mcc command line.

-d <directory> (Output Directory).   Place the output files from the compilation in the directory specified by the -d option.

-h (Helper Functions).   Compile helper functions. Any helper functions that are called will be compiled into the resulting MEX or stand-alone application. The -m option automatically compiles all helper functions, so -m effectively calls -h.

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 -m minimize_it fminsearch

instead of

mcc -m -h minimize_it

-I <directory> (Directory Path).   Add a new directory path to the list of included directories. Each -I option adds a directory to the end of the current search path. For example,

-I <directory1> -I <directory2>

would set up the search path so that directory1 is searched first for M-files, followed by directory2. This option is important for stand-alone compilation where the MATLAB path is not available.

-o <outputfile>.   Specify the basename of the final executable output (MEX-file or application) of the Compiler. A suitable, possibly platform-dependent, extension is added to the specified basename (e.g., .exe for PC stand-alone applications, .mexsol for Solaris MEX-files).

-t (Translate M to C/C++).   Translate M-files specified on the command line to C/C++ files.

-T <target> (Output Stage).   Specify the desired output stage. This table gives the possible values of target.

Table 7-10: Output Stage Options  

<Target>	Description
codegen	Translates M-files to C/C++ files. The default is codegen.
compile:<bin>	Translates M-files to C/C++ files; compiles to object form.
link:<bin>	Translates M-files to C/C++ files; compiles to object form; links to executable form (MEX or stand-alone application.)
where <bin> can be mexlibrary, mex, exe, or lib. mex and mexlibrary use the mex script to build a MEX-file; exe uses the mbuild script to build an executable; lib uses mbuild to build a shared library.

-v (Verbose).   Display the steps in compilation, including:

• The Compiler version number
• The source filenames as they are processed
• The names of the generated output files as they are created
• The invocation of mex or mbuild

The -v option passes the -v option to mex or mbuild and displays information about mex or mbuild.

-w (Warning).   Display warning messages. This table shows the various ways you can use the -w option.

Table 7-11: Warning Option  

Syntax	Description
(no -w option)	Default; displays only serious warnings.
-w list	Generates a table that maps <string> to warning message for use with enable, disable, and error. The Error and Warning Messages appendix lists the same information.
-w	Enables complete warnings.
-w disable[:<string>]	Disables specific warning associated with <string>. The Error and Warning Messages appendix lists the valid <string> values. Leave off the optional :<string> to apply the disable action to all warnings.
-w enable[:<string>]	Enables specific warning associated with <string>. The Error and Warning Messages appendix lists the valid <string> values. Leave off the optional :<string> to apply the enable action to all warnings.
-w error[:<string>]	Treats specific warning associated with <string> as error. Leave off the optional :<string> to apply the error action to all warnings.

-Y <license.dat File>.   Use license information in license.dat file when checking out a Compiler license.

mbuild/mex Options

-f <filename> (Specifying Options File).   Use the specified options file when calling mex or mbuild. This option allows you to use different compilers for different invocations of the MATLAB Compiler. This option is a direct pass-through to the mex or mbuild script. See External Interfaces/API 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 (Debug Only).   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.

-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".

Note    Multiple -M options do not accumulate; only the last -M option is used.

-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

Make a C translation and a MEX-file for myfun.m.

mcc -x myfun

Make a C translation and a stand-alone executable for myfun.m.

mcc -m myfun

Make a C++ translation and a stand-alone executable for myfun.m.

mcc -p myfun

Make a C translation and a Simulink S-function for myfun.m (using dynamically sized inputs and outputs).

mcc -S myfun

Make a C translation and a Simulink S-function for myfun.m (explicitly calling for one input and two outputs).

mcc -S -u 1 -y 2 myfun

Make a C translation and stand-alone executable for myfun.m. Look for myfun.m in the /files/source directory, and put the resulting C files and executable in the /files/target directory.

mcc -m -I /files/source -d /files/target myfun

Make a C translation and a MEX-file for myfun.m. Also translate and include all M-functions called directly or indirectly by myfun.m. Incorporate the full text of the original M-files into their corresponding C files as C comments.

mcc -x -h -A annotation:all myfun

Make a generic C translation of myfun.m.

mcc -t -L C myfun

Make a generic C++ translation of myfun.m.

mcc -t -L Cpp myfun

Make a C MEX wrapper file from myfun1.m and myfun2.m.

mcc -W mex -L C myfun1 myfun2

Make a C translation and a stand-alone executable from myfun1.m and myfun2.m (using one mcc call).

mcc -m myfun1 myfun2

Make a C translation and a stand-alone executable from myfun1.m and myfun2.m (by generating each output file with a separate mcc call).

mcc -t -L C myfun1                 % Yields myfun1.c
mcc -t -L C myfun2                 % Yields myfun2.c
mcc -W main -L C myfun1 myfun2     % Yields myfun1_main.c
mcc -T compile:exe myfun1.c        % Yields myfun1.o
mcc -T compile:exe myfun2.c        % Yields myfun2.o
mcc -T compile:exe myfun1_main.c   % Yields myfun1_main.o
mcc -T link:exe myfun1.o myfun2.o myfun1_main.o

Note    On PCs, filenames ending with .o above would actually end with .obj.

mcc

MATLAB Compiler Quick Reference