Main Content

mcc

Compile MATLAB functions for deployment

Description

You can use mcc to package and deploy MATLAB® programs as standalone applications, Excel® add-ins, Spark™ applications, or Hadoop® jobs.

If you have a MATLAB Compiler SDK™ license, you can use mcc to create C/C++ shared libraries, .NET assemblies, Java® packages, Python® packages, MATLAB Production Server™ deployable archives, or Excel add-ins for MATLAB Production Server.

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. The first file acts as the entry point to the compiled artifact.

You can also call this syntax from a system command prompt.

Note

Arguments that contain special characters (such as period or space) must be surrounded by single quotes. Use double quotes when executing from a Windows® command prompt.

mcc(options,mfilename) compiles the function as specified by the options. Specify file names and options as character vectors or strings. This syntax allows you to use MATLAB variables as input arguments.

Standalone Application

example

mcc -m [options] mfilename compiles the function into a standalone application. The executable type is determined by your operating system.

As an alternative, the compiler.build.standaloneApplication function supports most common workflows.

example

mcc -e [options] mfilename compiles the function into a standalone application that does not open a Windows command prompt on execution. The -e option works only on Windows operating systems.

As an alternative, the compiler.build.standaloneWindowsApplication function supports most common workflows.

Excel Add-In

example

mcc -W 'excel:addin_name,class_name,version=version_number' [options] mfilename1 mfilename2 ... mfilenameN creates a Microsoft® Excel add-in using the specified files. Before creating Excel add-ins, install a supported compiler.

You can only create Excel add-ins on Windows.

  • addin_name — Specifies the name of the add-in. If you do not specify the name, mcc uses mfilename1 as the default.

  • class_name — Specifies the name of the class to be created. If you do not specify the class name, mcc uses addin_name as the class name. If specified, class_name must be different from mfilename1.

  • version_number — Specifies the version number of the add-in file as major.minor.bug.build in the file system. You are not required to specify a version number. If you do not specify a version number, mcc sets the version number to 1.0.0.0 by default.

    • major — Specifies the major version number. If you do not specify a number, mcc sets major to 1.

    • minor — Specifies the minor version number. If you do not specify a number, mcc sets minor to 0.

    • bug— Specifies the bug fix maintenance release number. If you do not specify a number, mcc sets bug to 0.

    • build— Specifies the build number. If you do not specify a number, mcc sets build to 0.

As an alternative, the compiler.build.excelAddIn function supports most common workflows.

MapReduce Applications on Hadoop

Linux® only

example

mcc -W 'hadoop:archive_name,CONFIG:config_file' mfilename generates a deployable archive from mfilename that can be run as a job by Hadoop.

Simulink Simulations

Requires Simulink® Compiler™

example

mcc -m [options] mfilename compiles a MATLAB application that contains a Simulink simulation into a standalone application. For more information, see Create and Deploy a Script with Simulink Compiler (Simulink Compiler).

Python Package

Requires MATLAB Compiler SDK

example

mcc -W python:package_name [options] mfilename1 mfilename2 ... mfilenameN creates a Python package using the specified files.

  • package_name — Specifies the name of the Python package preceded by an optional namespace, which is a period-separated list such as companyname.groupname.component.

As an alternative, the compiler.build.pythonPackage (MATLAB Compiler SDK) function supports most common workflows.

.NET Assembly

example

mcc -W 'dotnet:assembly_name,api=api_type,class_name,framework_version,security,remote_type' [options] mfilename1 mfilename2 ... mfilenameN creates a .NET assembly with a single class using the specified files. Before creating .NET assemblies, see MATLAB Compiler SDK .NET Target Requirements (MATLAB Compiler SDK).

  • assembly_name — Specifies the name of the assembly preceded by an optional namespace, which is a period-separated list such as companyname.groupname.component.

  • api_type — Specifies the API type of the assembly. Values are matlab-data and mwarray. The default value is mwarray.

  • class_name — Specifies the name of the .NET class to be created.

  • framework_version — Specifies the version of the Microsoft .NET Framework you want to use to compile the assembly. Specify either:

    • 0.0 — Use the latest supported version on the target machine.

    • version_major.version_minor — Use a specific version of the framework.

    Features are often version-specific. Consult the documentation for the feature you are implementing to get the Microsoft .NET Framework version requirements.

  • security — Specifies whether the assembly to be created is a private assembly or a shared assembly.

    • To create a private assembly, specify Private.

    • To create a shared assembly, specify the full path to the encryption key file used to sign the assembly.

  • remote_type — Specifies the remoting type of the assembly. Values are remote and local.

mcc -W 'dotnet:assembly_name,api=api_type,class_name,framework_version,security,remote_type' [options] 'class{class_name:mfilename1,mfilename2,...,mfilenameN}' creates a .NET assembly with multiple classes using the specified files. You can include additional class specifiers by adding class{___} arguments.

As an alternative, the compiler.build.dotNETAssembly (MATLAB Compiler SDK) function supports most common workflows.

Java Package

Requires MATLAB Compiler SDK

example

mcc -W 'java:package_name,class_name' [options] mfilename1 mfilename2 ... mfilenameN creates a Java package from the specified files. Before creating Java packages, see Configure Your Java Environment (MATLAB Compiler SDK).

  • package_name — Specifies the name of the Java package preceded by an optional namespace, which is a period-separated list such as companyname.groupname.component.

  • class_name — Specifies the name of the class to be created. If you do not specify the class name, mcc uses the last item in package_name.

mcc -W 'java:package_name,class_name' [options] 'class{class_name:mfilename1,mfilename2,...,mfilenameN}' creates a Java package with multiple classes from the specified files. You can include additional class specifiers by adding class{___} arguments.

As an alternative, the compiler.build.javaPackage (MATLAB Compiler SDK) function supports most common workflows.

C Shared Library

Requires MATLAB Compiler SDK

example

mcc -l [options] mfilename1 mfilename2 ... mfilenameN compiles the listed functions into a C shared library and generates C wrapper code for integration with other applications.

As an alternative, the compiler.build.cSharedLibrary (MATLAB Compiler SDK) function supports most common workflows.

C++ Shared Library

Requires MATLAB Compiler SDK

example

mcc -W 'cpplib:library_name[,{all|legacy|generic}]' [options] mfilename1 mfilename2 ... mfilenameN compiles the listed functions into a C++ shared library and generates C++ wrapper code for integration with other applications.

  • library_name — Specifies the name of the shared library.

  • all— Generates shared libraries using both the mwArray API and the generic interface that uses the MATLAB Data API. This is the default behavior.

  • legacy— Generates shared libraries using the mwArray API.

  • generic— Generates shared libraries using the MATLAB Data API.

As an alternative, the compiler.build.cppSharedLibrary (MATLAB Compiler SDK) function supports most common workflows.

COM Component

Requires MATLAB Compiler SDK

example

mcc -W 'com:component_name,class_name' [options] mfilename1 mfilename2 ... mfilenameN compiles the listed functions into a generic Microsoft COM component.

  • component_name — Specifies the name of the COM component.

  • class_name — Specifies the name of the class.

As an alternative, the compiler.build.comComponent (MATLAB Compiler SDK) function supports most common workflows.

mcc -W 'com:component_name,class_name' [options] 'class{class_name:mfilename1,mfilename2,...,mfilenameN}' creates a Microsoft COM component with multiple classes from the specified files. You can include additional class specifiers by adding class{___} arguments.

Deployable Archive for MATLAB Production Server

Requires MATLAB Compiler SDK

example

mcc -U -W 'CTF:archive_name[,DISCOVERY:FunctionSignatures.json][,ROUTES:ArchiveRoutes.json]' [options] mfilename1 mfilename2 ... mfilenameN creates a deployable archive (.ctf file) for use with a MATLAB Production Server instance.

  • archive_name — Specifies the name of the deployable archive.

  • FunctionSignatures.json — Specifies the JSON file that contains information about your MATLAB functions, specified as an absolute or relative path. This options is relevant only for RESTful clients using the discovery API. For more information, see MATLAB Function Signatures in JSON (MATLAB Production Server).

  • ArchiveRoutes.json — Specifies the JSON file that contains URL routes for mapping client requests to MATLAB web handler functions within the archive. Use this option to organize routes by deployable archive name instead of defining them all in the server-level routes file specified by the routes-file (MATLAB Production Server) server configuration property. For more information on web request handlers, see Handle Custom Routes and Payloads in HTTP Requests (MATLAB Production Server).

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

As an alternative, the compiler.build.productionServerArchive (MATLAB Compiler SDK) function supports most common workflows, but it does not support creating archive-specific routes.

Excel Add-In for MATLAB Production Server

Requires MATLAB Compiler SDK

example

mcc -W 'mpsxl:addin_name,class_name,version' input_marshaling_flags output_marshaling_flags [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.

  • class_name — 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 marshaled 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.

As an alternative, the compiler.build.excelClientForProductionServer (MATLAB Compiler SDK) function supports most common workflows.

Examples

collapse all

Create a standalone application and include the data file data.mat.

In MATLAB, locate the MATLAB code that you want to deploy as a standalone application. For this example, compile using the file magicsquare.m located in matlabroot\extern\examples\compiler.

appFile = fullfile(matlabroot,'extern','examples','compiler','magicsquare.m');

Build a standalone application with a reference to appFile using the MATLAB command syntax. Use this command at the MATLAB command prompt.

mcc('-m',appFile,'-a','data.mat','-v')

The function generates a standalone application named magicsquare. The executable file type depends on the operating system on which the application is created.

As an alternative, the compiler.build.standaloneApplication function supports most common workflows.

Create a standalone application on Windows that does not open a command prompt window on execution.

You can use the mcc command at the MATLAB command prompt or the Windows command window.

mcc -e myapp.mlapp -o VisualApp

The function generates a standalone Windows application named VisualApp.

As an alternative, the compiler.build.standaloneWindowsApplication function supports most common workflows.

Create an Excel add-in on Windows with the system level version number 5.2.1.7.

To generate the Excel add-in file (.xla), you must enable "Trust access to the VBA project object model" in your Excel settings. If you do not do this, you can manually create the add-in by importing the generated .bas file into Excel.

mcc -W 'excel:magicExcel,myClass,version=5.2.1.7' -b mymagic.m

The function generates an Excel add-in named magicExcel.

As an alternative, the compiler.build.excelAddIn function supports most common workflows.

Create a MapReduce application on a Linux system that can be run as a job by Hadoop.

Create a configuration file named config.txt in your work folder that specifies configuration info.

mw.ds.in.type = tabulartext
mw.ds.in.format = infoAboutDataset.mat
mw.ds.out.type = keyvalue
mw.mapper = maxArrivalDelayMapper
mw.reducer = maxArrivalDelayReducer
For more information, see Configuration File for Creating Deployable Archive Using the mcc Command.

Copy the example files maxArrivalDelayMapper.m, maxArrivalDelayReducer.m, and airlinesmall.csv located in the folder matlabroot/toolbox/matlab/demos to your work folder.

Compile the files using the mcc command.

mcc -W 'hadoop:maxArrivalDelay,CONFIG:config.txt' maxArrivalDelayMapper.m maxArrivalDelayReducer.m

The function generates a shell script named run_maxarrivaldelay.sh, a deployable archive named maxArrivalDelayMapper.ctf, and a readme file with usage details.

For more details, see Include MATLAB Map and Reduce Functions into Hadoop Job.

Create a standalone application that runs a Simulink Simulation.

Create a Simulink model using Simulink. This example uses the model sldemo_suspn_3dof.

Create a MATLAB application that uses APIs from Simulink Compiler to simulate the model. For more information, see Deploy Simulations with Tunable Parameters (Simulink Compiler).

function deployParameterTuning(outputFile, mbVariable)
 
    if ischar(mbVariable) || isstring(mbVariable)
        mbVariable = str2double(mbVariable);
    end
     
    if isnan(mbVariable) || ~isa(mbVariable, 'double') || ~isscalar(mbVariable)
        disp('mb must be a double scalar or a string or char that can be converted to a double scalar');
    end
     
    in = Simulink.SimulationInput('sldemo_suspn_3dof');   
    in = in.setVariable('Mb', mbVariable);
    in = simulink.compiler.configureForDeployment(in);
    out = sim(in);
     
    save(outputFile, 'out');
  
end

Use mcc to create a standalone application from the MATLAB application.

mcc -m deployParameterTuning.m

The function generates an executable named deployParameterTuning.

For more information, see Create and Deploy a Script with Simulink Compiler (Simulink Compiler).

Requires MATLAB Compiler SDK

Create a Python package using the file mymagic.m located in the subfolder pymagic.

mcc -W python:magicPython pymagic/mymagic.m

The function generates a Python package named magicPython.

As an alternative, the compiler.build.pythonPackage (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a MATLAB Data API .NET assembly using the file mymagic.m. Specify a namespace, class name, framework version, security, and remoting type in the -W argument.

mcc -W 'dotnet:company.group.magic,api=matlab-data,dotnetClass,0.0,Private,local' mymagic.m

The function generates a .NET assembly archive named magic.ctf.

As an alternative, the compiler.build.dotNETAssembly (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a mwArray .NET assembly using the file mymagic.m. Specify a class name and framework version using the -W argument.

 mcc -W 'dotnet:magic,magicClass,5.0' mymagic.m

The function generates a .NET assembly named magic.dll.

As an alternative, the compiler.build.dotNETAssembly (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a Java package using the file mymagic.m. Specify a class name and namespace using the -W argument.

mcc -W 'java:company.group.javamagic,magicClass' mymagic.m

The function generates a Java package named magic.jar.

As an alternative, the compiler.build.javaPackage (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a C shared library using the file mymagic.m.

mcc -W lib:magiclibrary mymagic.m

The function generates a C shared library named magic.dll.

As an alternative, the compiler.build.cSharedLibrary (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a C++ shared library that uses the MATLAB Data API using the file mda_magic.m.

mcc -W 'cpplib:matlabmagiccpp,generic' mda_magic.m

The function generates a C++ shared library archive named matlabmagiccpp.ctf.

As an alternative, the compiler.build.cppSharedLibrary (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a C++ shared library that uses the mwArray API using the file mwa_magic.m.

mcc -W 'cpplib:mwarraymagiccpp,legacy' mwa_magic.m

The function generates a C++ shared library named mwarraymagiccpp.dll.

As an alternative, the compiler.build.cppSharedLibrary (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a COM component using the files mymagic.m, data2.m, and data2.m. Use the class argument to map the magic function to a class named MagicClass and the data functions to a class named DataClass.

mcc -W com:magicCOM 'class{MagicClass:mymagic.m}' 'class{DataClass:data1.m,data2.m}'

The function generates a COM component named magicCOM_1_0.dll.

As an alternative, the compiler.build.comComponent (MATLAB Compiler SDK) function supports most common workflows.

Requires MATLAB Compiler SDK

Create a MATLAB Production Server archive using the file mymagic.m. Use the -W argument to specify JSON files that define function signatures and web handler route mappings. For more details on function signatures, see MATLAB Function Signatures in JSON (MATLAB Production Server). For more details on web handlers, see Handle Custom Routes and Payloads in HTTP Requests (MATLAB Production Server).

mcc -U -W 'CTF:mps_magic,DISCOVERY:magicFunctionSignatures.json,ROUTES:magicRoutes.json' mymagic.m

The function generates a deployable archive named mps_magic.ctf.

As an alternative, the compiler.build.productionServerArchive (MATLAB Compiler SDK) function supports most common workflows, but it does not support the ROUTES options for specifying archive-specific route mappings to web request handlers.

Requires MATLAB Compiler SDK

Create a MATLAB Production Server archive using the file mymagic.m.

mcc -U -W CTF:mps_magic mymagic.m

Next, create an Excel add-in for MATLAB Production Server.

To generate the Visual Basic files, enable Trust access to the VBA project object model in Excel. If you do not do this, you can manually create the add-in by importing the .bas file into Excel.

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

The function generates an Excel add-in named magicAddin.

As an alternative, the compiler.build.excelClientForProductionServer (MATLAB Compiler SDK) function supports most common workflows.

Input Arguments

collapse all

Tip

To view a table of mcc input arguments in alphabetical order, see mcc Command Arguments Listed Alphabetically.

File to be compiled, specified as a character vector or string scalar.

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.

One or more files to be included in the class class_name, specified as a comma-separated list of file names. You can include multiple class specifiers by adding additional class{___} arguments. The argument applies only to the COM component, Java package, and .NET assembly targets.

Target and Platform

Build target and associated options, specified as one of the syntaxes listed below.

The compiler generates wrapper functions that allow another programming language to run the corresponding MATLAB function and any necessary global variable definitions. You cannot use this option in a deploytool app.

TargetSyntaxEquivalent Option
Standalone Application-W 'main:app_name,version=version'-m
Standalone Application (no Windows console)-W 'WinMain:app_name,version=version'-e
Excel Add-In-W 'excel:addin_name,class_name,version=version'

None

Hadoop MapReduce Application-W 'hadoop:archive_name,CONFIG:configFile'

None

Spark Application-W 'spark:app_name,version'

None

The following targets require MATLAB Compiler SDK.

TargetSyntaxEquivalent Option
C Shared Library-W 'lib:library_name'-l
C++ Shared Library-W 'cpplib:library_name[,{all|legacy|generic}]'

None

COM Component-W 'com:component_name,class_name'

None

.NET Assembly-W 'dotnet:assembly_name,api={matlab-data|mwarray},
class_name,framework_version,security,{remote|local}'

None

Java Package-W 'java:package_name,class_name'

None

Python Package-W 'python:package_name,class_name'

None

MATLAB Production Server Deployable Archive

-W 'CTF:archive_name'

None

MATLAB Production Server Excel Add-In

-W 'mpsxl:addin_name,class_name,version'

None

Note

-W values that contain special characters, such as commas or periods, must be surrounded by single quotes. Use double quotes when executing from a Windows command prompt.

Output target phase and type, specified as one of the following options. If not specified, mcc uses the default type for the target specified by the -W option.

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.

Example: -T link:lib

Add the platform designated by arch to the list of compatible platforms detected automatically by the compiler. Valid platforms are win64, maci64, glnxa64, and all. Apple silicon-based macOS (maca64) is not supported.

The -A option only applies to the Python, Java, and C++ MATLAB Data API targets.

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

Specify an options bundle file, where bundle is the name of a file that contains a set of mcc command line options, arguments, filenames, and/or other -B options. MathWorks® included bundle files are located in matlabroot\toolbox\compiler\bundles.

A bundle can include replacement parameters for compiler options that accept names and version numbers. If more than one parameter is passed, you must enclose the expression that follows the -B in single quotes. For example, mcc -B 'cexcel:component,class,1.0' ....

In general, each %n% in the bundle will be replaced with the corresponding option specified to the bundle. Use %% to include a literal % character. It is an error to pass too many or too few options to the bundle. For more details, see Using Bundles to Build MATLAB Code (MATLAB Compiler SDK).

Available Bundle Files

Bundle File

TargetContents
ccom

COM component

-W com:%1%,%2%,%3% -T link:lib
cexcel

Excel Add-in

-W excel:%1%,%2%,%3% -T link:lib -b -S
cjava

Java package

-W java:%1%,%2%
cmpsxlExcel Add-In for MATLAB Production Server-W mpsxl:%1%,%2%,%3% -T link:lib
cpplib

C++ library

-W cpplib:%1% -T link:lib
csharedlib

C library

-W lib:%1% -T link:lib
dotnet

.NET assembly

-W dotnet:%1%,%2%,%3%,%4%,%5% -T link:lib

Standalone Applications

Generate a standalone application. -m is equivalent to -W main -T link:exe. On Windows, the command prompt opens on execution of the application.

You cannot use this option in a deploytool app.

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. You cannot use this option in a deploytool app.

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

Example: -o myexecutable

Add icon resource to the executable of a standalone application. Paths can be relative to the current working directory or absolute.

Example: -r path\to\icon.ico

Interpret command line inputs as MATLAB doubles. If you do not specify this option, command line inputs are treated as MATLAB character vectors.

Excel Add-Ins and COM Components

Generate a Visual Basic file (.bas) and an Excel add-in file (.xla). The .bas file contains the Microsoft Excel Formula Function interface to the COM object generated by MATLAB Compiler. When imported into a workbook, this Visual Basic code allows the MATLAB function to be used as a cell formula function.

Note

To generate the Excel add-in file (.xla), you must enable "Trust access to the VBA project object model" in your Excel settings.

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.

C Shared Libraries

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

Suppress compiling and linking the generated C wrapper code. The -c option cannot be used independently of the -l option.

MATLAB Production Server

Generate a MATLAB Production Server archive (.ctf file). This argument must be before mfilename, and you must also specify the option -W 'CTF:archive_name'.

Additional Files

Add file or folder to the deployable archive. File paths can be relative or absolute. For additional details, see Access Files in Packaged Applications.

To add multiple files, use multiple -a options, specify a folder, or use wildcards.

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 file name includes the 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, the following command adds all files in ./testdir to the deployable archive, and subfolders under ./testdir are not processed recursively.

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

The following command adds all files with the extension .m in ./testdir, and subfolders of ./testdir are not processed recursively.

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

Including Java Classes

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.

Add a custom help text file. Paths can be relative to the current working directory or absolute. This option applies to standalone applications, C/C++ shared libraries, COM, and Excel targets.

Display help file contents by calling the application at the command line with the -? or /? argument.

Example: -h path\to\helpfile

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

Specify the method of adding support packages to the deployable archive as one of the following options.

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

Example: -Z 'Deep Learning Toolbox Converter for TensorFlow Models'

mcc Build Options

Place build output in the specified folder outputfolder. Paths can be relative to the current directory or absolute.

Do not embed the deployable archive in binaries. This option is ignored for Java libraries.

Override the default license file with the specified file licensefile. This option can only be used on the system command line.

Display mcc help text in the console. This option cannot be used in a deploytool app.

Protect Source Code

Since R2022b

Obfuscate .m files. This option generates a P-code file with a .p extension for each .m file included in the mcc command before packaging.

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

Since R2022b

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

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 byte file size

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

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

  • 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, depending on the key format

Avoid sharing the same key across multiple CTFs.

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.

For C++ shared libraries, as an alternative to specifying both key and MEX loader at compile time, you can specify only the encryption key (since R2023b). You then provide the hex encoded 64 byte decryption key at runtime in your C++ application as an argument for the initMATLABLibrary (MATLAB Compiler SDK) function using the MATLAB Data API or the <library>InitializeWithKey (MATLAB Compiler SDK) function using the MWArray API. For this workflow, the syntax is -k '<keyfile>'.

Example: -k 'file=path\to\encryption.key;loader=path\to\loader_interface.mexw64'

Since R2021b

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, .mlapp, .p, v7.3 .mat, MLX, SFX, 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 are not supported:

  • ver function

  • Calling external libraries such as DLLs

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

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

MATLAB Runtime

Provide MATLAB Runtime options that are passed to the application at initialization time. This option is only used when building standalone applications or Excel add-ins.

You can specify multiple -R options. When you specify multiple -R options, they are processed from left to right. For example, specify initialization start and end messages.

mcc -R '-startmsg,MATLAB Runtime initialized' -R '-completemsg,Initialization complete'

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 Display MATLAB Runtime Initialization Messages.

MATLAB Compiler Standalone Applications

'-completemsg,message'

Customizable user message displayed when initialization is complete. For more details, see Display MATLAB Runtime Initialization Messages.

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.

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 for the following specific targets.

Target supported by Singleton MATLAB RuntimeUsage Instructions
Excel add-inSingleton MATLAB Runtime is the default behavior. You do not need to perform other steps.
.NET assemblySingleton MATLAB Runtime is the default behavior. 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
MATLAB Compiler Search Path

Add a new folder to the search path used by MATLAB Compiler during dependency analysis. Each -I option appends the folder to the end of the list of paths. For example, the following syntax sets up the search path so that directory1 is searched first for MATLAB files, followed by directory2.

-I <directory1> -I <directory2>

This option is important for compilation environments 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.

Clear the search 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

-N also retains all subfolders in this list that appear on the MATLAB path at compile time. This option 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.

Conditionally 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. You must use this option in conjunction with the option -N.

Use the syntax -N -p directory, where directory is a relative or absolute path to the folder to be included.

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

mbuild Options

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

This option specifically applies to the C/C++ shared libraries, COM, and Excel targets.

Define mbuild compile-time options. The options argument is passed directly to mbuild. This option provides a 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 prompt

-M CFLAGS='$CFLAGS /bigobj'

Complex Number Representation

Since R2018a, MATLAB uses an interleaved storage representation, where the real and imaginary parts of each number are stored together. However, when you generate C shared libraries based on mxArray, or C++ shared libraries based on mwArray using the mcc command, these libraries default to a separate storage representation for complex numbers, a representation that can degrade performance.

To use interleaved representation in these shared libraries, utilize the -M R2018a option.

For an optimal approach when generating C++ shared libraries, choose the MATLAB Data Array for C++, which inherently uses the interleaved storage representation.

When integrating shared libraries generated by mcc using the mbuild (MATLAB Compiler SDK) command, the flags should match. If -M -R2018a is passed to the mcc command, -R2018a should be passed to mbuild.

Debugging

Include debugging symbol information for the C/C++ code generated by MATLAB Compiler SDK. This option 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.

Keep partial 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.

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 also passes the -v option to mbuild and displays information about mbuild.

Control the display of warning messages.

Syntax

Description

-w list

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

-w enable[:<warning>]

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

-w disable[:<warning>]

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

-w error[:<warning>]

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

-w on[:<warning>]

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

-w off[:<warning>]

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

The <warning> argument can be either a full identifier, such as Compiler:compiler:COM_WARN_OPTION_NOJVM, or one of the abbreviated identifiers listed by -w list.

You can display the full identifier that corresponds to a warning by issuing the following statement in your MATLAB code after the warning takes place.

[msg, warnID] = lastwarn

If you specify multiple -w options, they are processed from left to right.

For example, disable all warnings except repeated_file.

-w disable -w enable:repeated_file

You can also turn warnings on or off globally. For example, to turn off warnings for all deployed applications, specify the following in startup.m using isdeployed.

if isdeployed
    warning off
end

Limitations

  • mcc cannot create web apps. To create web apps, use the Web App Compiler app or the compiler.build.webAppArchive function.

  • You can use mcc to build components on MATLAB Online Server™, which acts as a Linux environment (since R2022b). To build targets that require an external compiler, including JavaJava, C++, and COM components, the MATLAB Online Server worker must be set up to run the required toolchain.

Tips

  • On Windows, you can generate a system-level file version number for your target file by appending version=version_number to the target generating mcc syntax. For an example, see Create Excel Add-In (Windows only).

    version_number — Specifies the version of the target file as major.minor.bug.build in the file system. You are not required to specify a version number. If you do not specify a version number, mcc sets the version number, by default, to 1.0.0.0.

    • major — Specifies the major version number. If you do not specify a version number, mcc sets major to 1.

    • minor — Specifies the minor version number. If you do not specify a version number, mcc sets minor to 0.

    • bug — Specifies the bug fix maintenance release number. If you do not specify a version number, mcc sets bug to 0.

    • build — Specifies build number. If you do not specify a version number, mcc sets build to 0.

    This functionality is supported for standalone applications and Excel add-ins in MATLAB Compiler.

    This functionality is supported for C shared libraries, C++ shared libraries, COM components, .NET assemblies, and Excel add-ins for MATLAB Production Server in MATLAB Compiler SDK.

Version History

Introduced before R2006a