Main Content

mcc

Compile MATLAB functions for deployment

Description

Other mcc Topics

This topic describes mcc options for use with MATLAB® Compiler SDK™ for MATLAB Production Server™. For information on compiling:

  • standalone applications, Excel® add-ins, or Hadoop® jobs, see mcc (MATLAB Compiler)

  • C/C++ shared libraries, .NET assemblies, Java® packages, or Python® packages, see mcc (MATLAB Compiler SDK)

General Usage

mcc options mfilename1 mfilename2 ... mfilenameN compiles the functions as specified by the options. The options used depend on the intended results of the compilation.

mcc('options','mfilename') compiles the function as specified by the options. Specify filenames, options, and option parameters in single quotes.

Deployable Archive for MATLAB Production Server

example

mcc -W CTF:archive_name -U options mfilename1 mfilename2 ... mfilenameN instructs the compiler to create a deployable archive (.ctf file) for use with a MATLAB Production Server instance.

The syntax also creates the server-side deployable archive (.ctf file) for Microsoft® Excel add-ins.

Excel Add-In for MATLAB Production Server

example

mcc -W mpsxl:addin_name,className,version input_marshaling_flags output_marshaling_flags -T link:lib options mfilename1 mfilename2 ... mfilenameN creates a client-side Microsoft Excel add-in from the specified files that can be used to send requests to MATLAB Production Server from Excel. Creating the client-side add-in must be preceded by creating a server-side deployable archive (.ctf file) from the specified files. A purely client side add-in is not viable.

  • addin_name — Specifies the name of the add-in.

  • className — Specifies the name of the class to be created. If you do not specify the class name, mcc uses the addin_name as the default.

  • version — Specifies the version of the add-in specified as major.minor.

    • major — Specifies the major version number. If you do not specify a version number, mcc uses the latest version.

    • minor — Specifies the minor version number. If you do not specify a version number, mcc uses the latest version.

  • input_marshaling_flags — Specifies options for how data is marshaled between Microsoft Excel and MATLAB.

    • -replaceBlankWithNaN — Specifies that a blank in Microsoft Excel is mashaled into NaN in MATLAB. If you do not specify this flag, blanks are marshaled into 0.

    • -convertDateToString — Specifies that dates in Microsoft Excel are marshaled into MATLAB character vectors. If you do not specify this flag, dates are marshaled into MATLAB doubles.

  • output_marshaling_flags — Specifies options for how data is marshaled between MATLAB and Microsoft Excel.

    • -replaceNaNWithZero — Specifies that NaN in MATLAB is marshaled into a 0 in Microsoft Excel. If you do not specify this flag, NaN is marshalled into #QNAN in Visual Basic®.

    • -convertNumericToDate — Specifies that MATLAB numeric values are marshaled into Microsoft Excel dates. If you do not specify this flag, Microsoft Excel does not receive dates as output.

Examples

Create a standalone application and include MATLAB preferences

mcc -m helloWorld.m -a C:\Users\someuser\AppData\Roaming\MathWorks\MATLAB\R2022b\matlab.mlsettings

Create a deployable archive for MATLAB Production Server

mcc -W CTF:myDeployableArchive -U mymagic.m

Create an Excel add-in for MATLAB Production Server

mcc -W 'mpsxl:myDeployableArchive,myExcelClass,version=1.0' mymagic.m

Input Arguments

collapse all

One or more files to be compiled, specified as a space-separated list of file names. The first file is used as the entry point for the compiled artifact.

Options for customizing the output, specified as a list of character vectors or string scalars.

  • -a

    Add files to the deployable archive using -a filepath to specify the files to be added. Multiple -a options are permitted.

    Also, add MATLAB preferences to a deployed application using -a path\to\mymatlab.mlsettings to specify the preferences to be added.

    If a file name is specified with -a, the 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. For more details, see Access Files in Packaged Applications (MATLAB Compiler SDK).

    If a folder name is specified with the -a option, the entire contents of that folder are added recursively to the deployable archive. For example,

    mcc -m hello.m -a ./testdir 

    specifies that all files in testdir, as well as all files in its subfolders, are added to the deployable archive. The folder subtree in testdir is preserved in the deployable archive.

    If the filename includes a wildcard pattern, only the files in the folder that match the pattern are added to the deployable archive and subfolders of the given path are not processed recursively. For example,

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

    specifies that all files in ./testdir are added to the deployable archive and subfolders under ./testdir are not processed recursively.

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

    specifies that all files with the extension .m under ./testdir are added to the deployable archive and subfolders of ./testdir are not processed recursively.

    Note

    * is the only supported wildcard.

    When you add files to the archive using -a that do not appear on the MATLAB path at the time of compilation, a path entry is added to the application's run-time path so that they appear on the path when the deployed code executes.

    When you use the -a option to specify a full path to a resource, the basic path is preserved, with some modifications, but relative to a subdirectory of the runtime cache directory, not to the user's local folder. The cache directory is created from the deployable archive the first time the application is executed. You can use the isdeployed (MATLAB Compiler SDK) function to determine whether the application is being run in deployed mode, and adjust the path accordingly. The -a option also creates a .auth file for authorization purposes.

    Caution

    If you use the -a flag to include a file that is not on the MATLAB path, the folder containing the file is added to the MATLAB dependency analysis path. As a result, other files from that folder might be included in the compiled application.

    Note

    If you use the -a flag to include custom Java classes, standalone applications 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 MATLAB code needs to make an appropriate call to javaaddpath to update the classpath with the parent folder of the package.

  • -A

    Append supported platforms to those detected automatically by the compiler. Use

    -A arch
    

    to add the platform designated by arch to the list of compatible platforms. Valid platforms are win64, maci64, glnxa64, and all. The -A option only applies to Python, C/C++ using the MATLAB data array API, and Java targets.

    Running the component on an incompatible platform will result in an unsupported platform error message and list compatible platforms.

  • -b

    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.

  • -B

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

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

    The bundle filename should contain only mcc command-line options and corresponding arguments and/or other file names. The file might contain other -B options. A bundle can include replacement parameters for compiler options that accept names and version numbers. See Using Bundles to Build MATLAB Code (MATLAB Compiler SDK).

  • -c

    When used in conjunction with the -l option, suppresses compiling and linking of the generated C wrapper code. The -c option cannot be used independently of the -l option.

  • -C

    Do not embed the deployable archive in binaries.

    Note

    The -C flag is ignored for Java libraries.

  • -d

    Place output in a specified folder. Use

    -d outFolder
    

    to direct the generated files to outFolder. The specified folder must already exist.

  • -e

    Use -e in place of the -m option to generate a standalone Windows® application that does not open a Windows command prompt on execution. -e is equivalent to -W WinMain -T link:exe.

    This option works only on Windows operating systems.

  • -f

    Override the default options file with the specified options file. It specifically applies to the C/C++ shared libraries, COM, and Excel targets. Use

    -f filename
    

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

  • -g, -G

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

  • -h

    Specify a custom help text file. This option applies to standalone applications, C/C++ shared libraries, COM, and Excel targets. Use

    -f filename
    

    to include filename as the custom help text file. Display help file contents by calling the application at the command line with the -? or /? argument.

  • -I

    Add a new folder path to the list of included folders. Each -I option appends the folder to the end of the list of paths to search. For example,

    -I <directory1> -I <directory2>
    

    sets up the search path so that directory1 is searched first for MATLAB files, followed by directory2. This option is important for standalone compilation where the MATLAB path is not available.

    If used in conjunction with the -N option, the -I option adds the folder to the compilation path in the same position where it appeared in the MATLAB path rather than at the head of the path.

  • -j

    Automatically convert all .m files to P-files before packaging. The -j option generates a P-code file with a .p extension for each .m file included in the mcc command.

    P-code files are an obfuscated, execute-only form of MATLAB code. For more details, see pcode (MATLAB).

  • -k

    Specify an AES encryption key and a MEX-file loader interface to retrieve the decryption key at runtime.

    Use

    -k "file=<key_file_path>;loader=<mex_file_path>"

    to specify paths to the key file and MEX-file.

    The key file must be in one of the following supported formats:

    • Binary 256-bit AES key, with a 32 byte file size

    • Hex encoded AES key, with a 64 character file size

    The loader MEX-file must be an interface with the following arguments:

    • prhs[0] — Input, char array specified as the static value 'getKey'

    • prhs[1] — Input, char array specified as the CTF component UUID

    • plhs[0] — Output, 32 byte UINT8 numeric array or 64 byte HEX encoded char array

    If you do not specify any arguments after -k, mcc generates a 256-bit AES key and a loader MEX-file that can be used for demonstration purposes.

  • -K

    Direct mcc to not delete output files if the compilation ends prematurely due to error.

    The default behavior of mcc is to dispose of any partial output if the command fails to execute successfully.

  • -l

    Generate a function library. -l is equivalent to -W lib -T link:lib. You cannot use this option in a deploytool app.

  • -m

    Generate a standalone application. -m is equivalent to -W main -T link:exe. You cannot use this option in a deploytool app.

  • -M

    Define compile-time options. Use

    -M string
    

    to pass string directly to mbuild. This option provides a useful mechanism for defining compile-time options, for example, -M "-Dmacro=value".

    Note

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

    To pass options such as /bigobj, delineate the string according to your platform.

    PlatformSyntax

    MATLAB

    -M 'COMPFLAGS=$COMPFLAGS /bigobj'
    Windows command prompt
    -M COMPFLAGS="$COMPFLAGS /bigobj"
    

    Linux® and macOS command line

    -M CFLAGS='$CFLAGS /bigobj'
  • -n

    The -n option automatically identifies numeric command line inputs and treats them as MATLAB doubles.

  • -N

    Passing -N 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

    • matlabroot\toolbox\shared\bigdata

    Passing -N also retains all subfolders in this list that appear on the MATLAB path at compile time. Including -N on the command line lets you 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 you included on the path that are not under matlabroot\toolbox.

    When using the –N option, use the –I option to force inclusion of a folder, which is placed at the head of the compilation path. Use the –p option to conditionally include folders and their subfolders; if they are present in the MATLAB path, they appear in the compilation path in the same order.

  • -o

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

    -o outputfile
    

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

  • -p

    Use in conjunction with the option -N to add specific folders and subfolders under matlabroot\toolbox to the compilation MATLAB path. The files are added in the same order in which they appear in the MATLAB path. 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.

    • 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 the same order.

    • If a folder is included with -p that is not on the original MATLAB path, that folder is ignored. (You can use -I to force its inclusion.)

  • -r

    Embed resource icon in binary. The syntax is as follows:

    -r 'path/to/my_icon.ico'

  • -R

    Provide MATLAB Runtime options that are passed to the application at initialization time.

    Note

    This option is relevant only when building standalone applications or Excel add-ins using MATLAB Compiler. If you specify the -R option for libraries created from MATLAB Compiler SDK, mcc still compiles and generates the results, but the -R option doesn't apply to these libraries and does not do anything.

    The syntax is as follows:

    -R option

    Option

    Description

    Target

    '-logfile,filename'

    Specify a log file name. The file is created in the application folder at runtime and contains information about MATLAB Runtime initialization and all text piped to the command window. Option must be in single quotes. Use double quotes when executing the command from a Windows Command Prompt.

    MATLAB Compiler

    -nodisplay

    Suppress the MATLAB nodisplay run-time warning. On Linux, open MATLAB Runtime without display functionality.

    MATLAB Compiler

    -nojvm

    Do not use the Java Virtual Machine (JVM).

    MATLAB Compiler

    '-startmsg,message'

    Customizable user message displayed at initialization time. For more details, see .

    MATLAB Compiler Standalone Applications

    '-completemsg,message'

    Customizable user message displayed when initialization is complete. For more details, see .

    MATLAB Compiler Standalone Applications

    -singleCompThread

    Limit MATLAB to a single computational thread.

    MATLAB Compiler

    -softwareopenglUse Mesa Software OpenGL® for rendering.

    MATLAB Compiler

    Caution

    When running on macOS, if you use -nodisplay as one of the options included in mclInitializeApplication, then the call to mclInitializeApplication must occur before calling mclRunMain.

  • -s

    Obfuscate folder structures and file names in the deployable archive (.ctf file) from the end user. Optionally encrypt additional file types.

    The -s option directs mcc to place user code and data contained in .m, .p, v7.3 .mat, and MEX files into a user package within the CTF. During runtime, MATLAB code and data is decrypted and loaded directly from the user package rather than extracted to the file system. MEX files are temporarily extracted from the user package before being loaded.

    To manually include additional file types in the user package, add each file type in a separate extension tag to the file matlabroot/toolbox/compiler/advanced_package_supported_files.xml.

    The following is not supported:

    • ver function

    • Out-of-process MATLAB Runtime ( C++ shared library for MATLAB Data Array)

    • Out-of-process MEX file execution (mexhost, feval, matlab.mex.MexHost)

  • -S

    Create a single MATLAB Runtime instance that is shared across all class instances.

    The standard behavior for the MATLAB Runtime is that every instance of a class gets its own MATLAB Runtime context. The context includes a global MATLAB workspace for variables, such as the path, and a base workspace for each function in the class. If multiple instances of a class are created, each instance gets an independent context. This ensures that changes made to the global or base workspace in one instance of the class does not affect other instances of the same class.

    In a singleton MATLAB Runtime, all instances of a class share the context. If multiple instances of a class are created, they use the context created by the first instance which saves startup time and some resources. However, any changes made to the global workspace or the base workspace by one instance impacts all class instances. For example, if instance1 creates a global variable A in a singleton MATLAB Runtime, then instance2 can use variable A.

    Singleton MATLAB Runtime is only supported by the following products on these specific targets:

    Target supported by Singleton MATLAB RuntimeCreate a Singleton MATLAB Runtime by....
    Excel add-inDefault behavior for target is singleton MATLAB Runtime. You do not need to perform other steps.
    .NET assemblyDefault behavior for target is singleton MATLAB Runtime. You do not need to perform other steps.
    COM component
    • Using the Library Compiler app, click Settings and add -S to the Additional parameters passed to MCC field.

    • Using mcc, pass the -S flag.

    Java package
  • -T

    Specify the output target phase and type. If not specified, mcc uses the default type for the target specified by the -W option.

    Use the syntax -T target to define the output type.

    TargetDescription
    compile:exeGenerate a C/C++ wrapper file, and compile C/C++ files to an object form suitable for linking into a standalone application.
    compile:libGenerate a C/C++ wrapper file, and compile C/C++ files to an object form suitable for linking into a shared library or DLL.
    link:exeSame as compile:exe and also link object files into a standalone application.
    link:libSame as compile:lib and also link object files into a shared library or DLL.

  • -u

    Register COM component for the current user only on the development machine. The argument applies only to the generic COM component and Microsoft Excel add-in targets.

  • -U

    Build deployable archive (.ctf file) for MATLAB Production Server.

  • -v

    Display verbose output. Output displays the compilation steps, including:

    • MATLAB Compiler version number

    • Source file names as they are processed

    • Names of the generated output files as they are created

    • Invocation of mbuild

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

  • -w

    Display warning messages. Use the syntax

    -w option [:<msg>]

    to control the display of warnings.

    Syntax

    Description

    -w list

    List the compile-time warnings that have abbreviated identifiers, together with their status.

    -w enable

    Enable all compile-time warnings.

    -w disable[:<string>]

    Disable specific compile-time warnings associated with <string>. Omit the optional <string> to apply the disable action to all compile-time warnings.

    -w enable[:<string>]

    Enable specific compile-time warnings associated with <string>. Omit the optional <string> to apply the enable action to all compile-time warnings.

    -w error[:<string>]

    Treat specific compile-time and runtime warnings associated with <string> as an error. Omit the optional <string> to apply the error action to all compile-time and runtime warnings.

    -w off[:<string>]

    Turn off warnings for specific error messages defined by <string>. Omit the optional <string> to apply the off action to all runtime warnings.

    -w on[:<string>]

    Turn on runtime warnings associated with <string>. Omit the optional <string> to apply the on action to all runtime warnings. This option is enabled by default.

    You can also turn warnings on or off in your MATLAB code.

    For example, to turn off warnings for deployed applications (specified using isdeployed) in startup.m, you write:

    if isdeployed
        warning off
    end
    

    To turn on warnings for deployed applications, you write:

    if isdeployed
        warning on
    end
    

    You can also specify multiple -w options.

    For example, if you want to disable all warnings except repeated_file, you write:

    -w disable -w enable:repeated_file
    When you specify multiple -w options, they are processed from left to right.

  • -W

    Control the generation of function wrappers. Use the syntax

    -W type 

    to control the generation of function wrappers for a collection of MATLAB files generated by the compiler. You provide a list of functions, and the compiler generates the wrapper functions and any appropriate global variable definitions.

    TargetSyntax

    Note

    Replace single quotes with double when executing the command from a Windows Command Prompt.

  • -X

    Use -X to ignore data files read by common MATLAB file I/O functions during dependency analysis. For more information, see Dependency Analysis Using MATLAB Compiler (MATLAB Compiler). For examples on how to use the -X option, see %#exclude (MATLAB Compiler).

  • -Y

    Use

     -Y license.lic

    to override the default license file with the specified argument.

    Note

    The -Y flag works only with the command-line mode.

    >>!mcc -m foo.m -Y license.lic
  • -Z

    Use

    -Z option
    to specify the method of adding support packages to the deployable archive.

    SyntaxDescription
    -Z 'autodetect'The dependency analysis process detects and includes the required support packages automatically. This is the default behavior of mcc.
    -Z 'none'No support packages are included. Using this option can cause runtime errors.
    -Z packagenameOnly the specified support package is included. To specify multiple support packages, use multiple -Z inputs.

    Note

    To list installed support packages or those used by a specific file, see compiler.codetools.deployableSupportPackages (MATLAB Compiler).

Tips