mcc - Invoke MATLAB Compiler

Syntax

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

Description

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

mcc prepares M-file(s) for deployment outside of the MATLAB environment, generates wrapper files in C or C++, optionally builds standalone binary files, and writes any resulting files into the current folder, by default.

If more than one M-file is specified on the command line, MATLAB Compiler generates a C or C++ function for each M-file. If C or object files are specified, they are passed to mbuild along with any generated C files.

Options

-a Add to Archive

Add a file to the CTF archive. Use

-a filename

to specify a file to be directly added to the CTF archive. Multiple -a options are permitted. MATLAB Compiler looks for these files on the MATLAB path, so specifying the full path name is optional. These files are not passed to mbuild, so you can include files such as data files.

If only a folder name is included with the -a option, the entire contents of that folder are added recursively to the CTF archive. For example:

mcc -m hello.m -a ./testdir

In this example, testdir is a folder in the current working folder. All files in testdir, as well as all files in subfolders of testdir, are added to the CTF archive, and the folder subtree in testdir is preserved in the CTF archive.

If a wildcard pattern is included in the file name, only the files in the folder that match the pattern are added to the CTF archive and subfolders of the given path are not processed recursively. For example:

mcc -m hello.m -a ./testdir/*

In this example, all files in ./testdir are added to the CTF archive and subfolders under ./testdir are not processed recursively.

mcc -m hello.m -a ./testdir/*.m

In this example, all files with the extension .m under ./testdir are added to the CTF archive and subfolders of ./testdir are not processed recursively.

Note Currently, * is the only supported wildcard.

All files added to the CTF archive using -a (including those that match a wildcard pattern or appear under a folder specified using -a) that do not appear on the MATLAB path at the time of compilation will cause a path entry to be added to the deployed application's run-time path so that they will appear on the path when the deployed application or component is executed.

When files are included, the absolute path for the DLL and header files is changed. The files are placed in the .\exe_mcr\ folder when the CTF file is expanded. The file is not placed in the local folder. This folder gets created from the CTF file the first time the EXE file is executed. The isdeployed function is provided to help you accommodate this difference in deployed mode.

The -a switch also creates a .auth file for authorization purposes. It ensures that the executable looks for the DLL- and H-files in the exe_mcr\exe folder.

Note If the -a flag is used to include custom Java classes, standalone applications will work without any need to change the classpath as long as the Java class is not a member of a package. The same applies for JAR files. However, if the class being added is a member of a package, the M-code will need to make an appropriate call to javaaddpath that will update the classpath with the parent folder of the package.

-b Generate Excel Compatible Formula Function

Generate a Visual Basic file (.bas) containing the Microsoft Excel Formula Function interface to the COM object generated by MATLAB Compiler. When imported into the workbook Visual Basic code, this code allows the MATLAB function to be seen as a cell formula function. This option requires MATLAB Builder EX.

-B Specify Bundle File

Replace the file on the mcc command line with the contents of the specified file. Use

-B filename[:<a1>,<a2>,...,<an>]

The bundle file filename should contain only mcc command line options and corresponding arguments and/or other file names. The file may contain other -B options. A bundle file can include replacement parameters for Compiler options that accept names and version numbers. See Using Bundle Files for a list of the bundle files included with MATLAB Compiler.

-c Generate C Code Only

When used with a macro option, generate C wrapper code but do not invoke mbuild, i.e., do not produce a standalone application. This option is equivalent to the defunct -T codegen placed at the end of the mcc command line.

-C Do Not Embed CTF Archive by Default

Overrides automatically embedding the CTF archive in C/C++ and main/Winmain shared libraries and standalone binaries by default. See Overriding Default CTF Archive Embedding Using the MCR Component Cache for more information.

-d Specified Directory for Output

Place output in a specified folder. Use

-d directory

to direct the output files from the compilation to the folder specified by the -d option.

-e Suppress MS-DOS Command Window

Suppress appearance of the MS-DOS command window when generating a standalone application. Use -e in place of the -m option. This option is available for Windows only. Use with -R option to generate error logging as such:

 mcc -e -R -logfile -R 'filename' -v function_name

or:

mcc -e -R '-logfile,logfilename' -v function_name

This macro is equivalent to the defunct:

-W WinMain -T link:exe

Note This feature requires the application to successfully compile with a Microsoft Compiler (such as that offered with the free Microsoft Visual Studio Express).

-f Specified Options File

Override the default options file with the specified options file. Use

-f filename

to specify filename as the options file when calling mbuild. This option allows you to use different ANSI compilers for different invocations of MATLAB Compiler. This option is a direct pass-through to the mbuild script.

Note The MathWorks recommends that you use mbuild -setup.

-F Specified Project File

Specify that mcc use settings contained in the specified project file. Use

-F project_name.prj

to specify project_name as the project file name when calling mcc. This option enables the .prj file, along with all of its associated settings, to be fed back to mcc. Project files created using either mcc or deploytool are eligible to use this option. When using -F, no other arguments may be invoked against mcc.

-g Generate Debugging Information

Include debugging symbol information for the C/C++ code generated by MATLAB Compiler. It also causes mbuild to pass appropriate debugging flags to the system C/C++ compiler. The debug option enables you to backtrace up to the point where you can identify if the failure occurred in the initialization of MCR, the function call, or the termination routine. This option does not allow you to debug your M-files with a C/C++ debugger.

-G Debug Only

Same as -g.

-I Add Directory to Include Path

Add a new folder path to the list of included folders. Each -I option adds a folder to the beginning of the list of paths to search. 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 standalone compilation where the MATLAB path is not available.

-l Generate a Function Library

Macro to create a function library. This option generates a library wrapper function for each M-file on the command line and calls your C compiler to build a shared library, which exports these functions. You must supply the name of the library (foo in the following example).

Using

mcc -l foo.m

is equivalent to using:

mcc -W lib:foo -T link:lib foo.m

-m Generate a Standalone Application

Macro to produce a standalone application. This macro is equivalent to the defunct:

-W main -T link:exe

Use the -e option instead of the -m option to generate a standalone application while suppressing the appearance of the MS-DOS Command Window.

Note Using the -e option requires the application to successfully compile with a Microsoft Compiler (such as that offered with the free Microsoft Visual Studio Express).

-M Direct Pass Through

Define compile-time options. Use

-M string

to pass string directly to the 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 rightmost -M option is used.

-N Clear Path

Passing -N effectively clears the path of all folders except the following core folders (this list is subject to change over time):

matlabroot/toolbox/matlab
matlabroot/toolbox/local
matlabroot/toolbox/compiler/deploy

It also retains all subfolders of the above list that appear on the MATLAB path at compile time. Including -N on the command line allows you to replace folders from the original path, while retaining the relative ordering of the included folders. All subfolders of the included folders that appear on the original path are also included. In addition, the -N option retains all folders that the user has included on the path that are not under matlabroot/toolbox.

-o Specify Output Name

Specify the name of the final executable (standalone applications only). Use

-o outputfile

to name the final executable output of MATLAB Compiler. A suitable, possibly platform-dependent, extension is added to the specified name (e.g., .exe for Windows standalone applications).

-p Add Directory to Path

Used in conjunction with required option -N to add specific folders (and subfolders) under matlabroot/toolbox to the compilation MATLAB path in an order sensitive way. Use the syntax:

-N -p directory

where directory is the folder to be included. If directory is not an absolute path, it is assumed to be under the current working folder. The rules for how these folders are included are

If a folder is included with -p that is on the original MATLAB path, the folder and all its subfolders that appear on the original path are added to the compilation path in an order-sensitive context.
If a folder is included with -p that is not on the original MATLAB path, that folder is not included in the compilation. (You can use -I to add it.)

If a path is added with the -I option while this feature is active (-N has been passed) and it is already on the MATLAB path, it is added in the order-sensitive context as if it were included with -p. Otherwise, the folder is added to the head of the path, as it normally would be with -I.

-R Run-Time

Provide MCR run-time options. Use the syntax

-R option

to provide one of these run-time options.

Option	Description
`-logfile filename`	Specify a log file name.
`-nodisplay`	Suppress the MATLAB `nodisplay` run-time warning.
`-nojvm`	Do not use the Java Virtual Machine (JVM).
`-startmsg`	Customizable user message displayed at MCR initialization time. See Displaying MCR Initialization Start-Up and Completion Messages For Users.
`-completemsg`	Customizable user message displayed when MCR initialization is complete. See Displaying MCR Initialization Start-Up and Completion Messages For Users.

Note The -R option is available only for standalone applications. To override MCR options in the other MATLAB Compiler targets, use the mclInitializeApplication and mclTerminateApplication functions. For more information on these functions, see Calling a Shared Library.

Caution When running on Mac, if -nodisplay is used as one of the options included in mclInitializeApplication, then the call to mclInitializeApplication must occur before calling mclRunMain.

-S Create Singleton MCR

Create a singleton MCR when compiling a COM object. Each instance of the component uses the same MCR. Requires MATLAB Builder NE.

-v Verbose

Display the compilation steps, including:

MATLAB Compiler version number
The source file names as they are processed
The names of the generated output files as they are created
The invocation of mbuild

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

Note MCRInstaller.exe has obsoleted the need for the function buildmcr or the creation of MCRInstaller.zip. See Replacement of MCRInstaller.zip and BUILDMCR Functionality for more details including complete file paths to all install programs.

-w Warning Messages

Displays warning messages. Use the syntax

-w option[:<msg>]

to control the display of warnings. This table lists the valid syntaxes.

Syntax	Description
`-w list`	Generates a table that maps `<string>` to warning message for use with `enable`, `disable`, and `error`. Error and Warning Messages, lists the same information.
`-w enable`	Enables complete warnings.
`-w disable[:<string>]`	Disables specific warning associated with `<string>`. Error and Warning Messages, 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>`. Error and Warning Messages, 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.

-W Wrapper Function

Controls the generation of function wrappers. Use the syntax

-W type

to control the generation of function wrappers for a collection of M-files generated by MATLAB Compiler. You provide a list of functions and MATLAB Compiler generates the wrapper functions and any appropriate global variable definitions. This table shows the valid options.

Type	Description
`main`	Produces a POSIX shell `main()` function.
`lib:<string>`	Creates a C interface and 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.
`cpplib:<string>`	Creates a C++ interface and 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. The default is `none`.

-Y License File

Use

-Y license.dat_file

to override the default license.dat file with the specified argument.

-z Specify Path

Specify the path for library and include files. Use

-z path

to specify path to use for the compiler libraries and include files instead of the path returned by matlabroot.

-? Help Message

Display MATLAB Compiler help at the command prompt.

Linux mcc Cache Management Command Options

The Bourne shell front-end interface to MATLAB Compiler uses a cache file to speed execution. The cache file contains precomputed values of critical environment variables. The cache is automatically built whenever the back-end interface is called, providing that the cache file doesn't already exist and the -nocache option is not used. Later executions of mcc will use it unless overridden by -nocache. Special command-line options are available to manage this cache, but they can only be executed on Linux in standalone command-line mode (not through MATLAB). The table summarizes these options.

Linux Command Option	Description
`-cache`	Prints the cache if used as the only argument. Can be used to rebuild the cache when used with other arguments in this table.
`-rmcache`	Removes the cache.
`-nocache`	Ignores the cache.

Examples

Make a standalone executable for myfun.m.

mcc -m myfun

Make a standalone executable for myfun.m, but look for myfun.m in the /files/source folder and put the resulting C files and in the /files/target folder.

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

Make the standalone myfun1 from myfun1.m and myfun2.m (using one mcc call).

mcc -m myfun1 myfun2

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit