mcc

Compile MATLAB functions for deployment

Syntax

mcc options mfilename1 mfilename2...mfilenameN

mcc -l options mfilename1 mfilename2...mfilenameN

mcc -W cpplib:library_name[,{all|legacy|generic}] options mfilename1 mfilename2...mfilenameN

mcc -W com:component_name,className -T link:lib options class{className:mfilename1 mfilename2...mfilenameN}

mcc -W dotnet:assembly_name,className,framework_version,security,remote_type -T link:lib options mfilename1 mfilename2...mfilenameN

mcc -W dotnet:assembly_name,className,framework_version,security,remote_type -T link:lib options class{className:mfilename1 mfilename2...mfilenameN}

mcc -W java:packageName,className options mfilename1 mfilename2...mfilenameN

mcc -W java:packageName,className options class{className:mfilename1 mfilename2...mfilenameN}

mcc -W python:namespace.packageName -T link:lib options mfilename1 mfilename2...mfilenameN

mcc -W CTF:archive_name -U options mfilename1 mfilename2...mfilenameN

mcc -W mpsxl:addin_name,className,version input_marshaling_flags output_marshaling_flags -T link:lib options mfilename1 mfilename2...mfilenameN

Description

mcc options mfilename1 mfilename2...mfilenameN compiles the functions as specified by the options.

The options used depend on the intended results of the compilation. For information on compiling:

• standalone applications, Excel^® add-ins, or Hadoop^® jobs see mcc for MATLAB^® Compiler™

C Shared Library

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.

This syntax is equivalent to -W lib:libname -T link:lib.

C++ Shared Library

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.

• legacy— Generates shared libraries using the mwArrayAPI.

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

COM Component

mcc -W com:component_name,className -T link:lib options class{className:mfilename1 mfilename2...mfilenameN} compiles the listed functions into a generic Microsoft^® COM component.

• component_name — Specifies the name of the COM component.

• className — Specifies the name of the class.

.NET Assembly

mcc -W dotnet:assembly_name,className,framework_version,security,remote_type -T link:lib options mfilename1 mfilename2...mfilenameN creates a .NET assembly with a single class from the specified files.

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

• className — 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,className,framework_version,security,remote_type -T link:lib options class{className:mfilename1 mfilename2...mfilenameN} creates a .NET assembly with multiple classes from the specified files.

• assembly_name — Specifies the name of the assembly and its namespace, which is a period-separated list, such as companyname.groupname.component.

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

  Note

  You can include multiple class specifiers.

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

Java Package

mcc -W java:packageName,className options mfilename1 mfilename2...mfilenameN creates a Java^® package from the specified files.

• packageName — Specifies the name of the Java package and its namespace, which is a period-separated list, such as companyname.groupname.component.

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

mcc -W java:packageName,className options class{className:mfilename1 mfilename2...mfilenameN} creates a Java package with multiple classes from the specified files.

• packageName — Specifies the name of the Java package and its namespace, which is a period-separated list, such as companyname.groupname.component.

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

  Note

  You can include multiple class specifiers.

Python Package

mcc -W python:namespace.packageName -T link:lib options mfilename1 mfilename2...mfilenameN creates a Python^® package from the specified files.

• namespace — Specifies the optional namespace for the package, which is a period-separated list, such as companyname.groupname.component

• packageName — Specifies the name of the Python package.

Deployable Archive for MATLAB Production Server

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

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 and its namespace, which is a period-separated list, such as companyname.groupname.component.

• 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 C shared library

mcc -l mymagic.m

Create a C shared library with a system-level file version number (Windows only)

Create a C shared library in Windows^® with version number 4.3.1.7.

mcc -W 'lib:myCSharedLib,version=4.3.1.7' -T link:lib mymagic.m

Create a C++ shared library

Use the mwArray API

mcc -W 'cpplib:mymagic,legacy' mymagic.m

Use the MATLAB Data API

mcc -W 'cpplib:mymagic,generic' mymagic.m

Use both the mwArray API and the MATLAB Data API

mcc -W 'cpplib:mymagic,all' mymagic.m

OR

mcc -W 'cpplib:mymagic' mymagic.m

Create a C++ shared library with a system-level file version number (Windows only)

Create a C++ shared library in Windows with version number 3.7.1.5.

mcc -W 'cpplib:mymagic,all,version=3.7.1.5' -T link:lib mymagic.m

Create a COM component

Create a COM component in Windows with version number 7.10.1.3.

mcc -W 'com:myCOMComponent,myClass,version=7.10.1.3' -T link:lib class{myClass:mymagic.m}

Create a Java package containing multiple classes

mcc -W 'java:myMatrix,add' class{add:add.m} class{sub:minus.m}

Create a Python package

mcc -W python:myMagic -T link:lib magic.m

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:myDeployableArchvie,myExcelClass,version=1.0' -T link:lib mymagic.m

Input Arguments

mfilename1 mfilename2...mfilenameN — Files to be compiled

list of filenames

One or more files to be compiled, specified as a space-separated list of filenames.

options — Options for customizing the output

-a | -b | -B | -c | -C | -d | -f | -g | -G | -I | -K | -m | -M | -n | -N | -o | -p | -R | -S | -T | -u | -U | -v | -w | -W | -Y

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

• -a

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

  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.

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

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

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

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

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

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

• -m

  Direct mcc to generate a standalone application.

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

• -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

  Provide MATLAB Runtime options. This option is relevant only when building standalone applications using MATLAB Compiler. The syntax is as follows:

  -R option

  Option	Description	Target
  -logfile,filename	Specify a log file name.	MATLAB Compiler
  -nodisplay	Suppress the MATLAB nodisplay run-time warning.	MATLAB Compiler
  -nojvm	Do not use the Java Virtual Machine (JVM).	MATLAB Compiler
  -startmsg	Customizable user message displayed at initialization time.	MATLAB Compiler Standalone Applications
  -completemsg	Customizable user message displayed when initialization is complete.	MATLAB Compiler Standalone Applications

  Caution

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

  Note

  If you specify the -R option for libraries created from MATLAB Compiler SDK, mcc still compiles without errors and generates the results. But the -R option doesn't apply to these libraries and does not do anything.

• -S

  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 Runtime	Create a Singleton MATLAB Runtime by....
  Excel add-in	Default behavior for target is singleton MATLAB Runtime. You do not need to perform other steps.
  .NET assembly	Default 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.

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

  Target	Description
  compile:exe	Generate a C/C++ wrapper file, and compile C/C++ files to an object form suitable for linking into a standalone application.
  compile:lib	Generate a C/C++ wrapper file, and compile C/C++ files to an object form suitable for linking into a shared library or DLL.
  link:exe	Same as compile:exe and also link object files into a standalone application.
  link:lib	Same 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 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.

• -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 warnings associated with <string> as an error. Omit the optional <string> to apply the error action to all compile-time 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.

  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.

• -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

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 a C++ shared library with a system-level file version number (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 C shared libraries, C++ shared libraries, COM components, .NET assemblies, and Excel add-ins for MATLAB Production Server in MATLAB Compiler SDK. For supported targets in MATLAB Compiler, see the Tips section in mcc.