-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
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
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
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
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
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.
Platform | Syntax |
---|
MATLAB |
|
Windows command prompt |
|
Linux® and macOS command line |
|
-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
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
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
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:
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 |
-softwareopengl | Use 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 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. 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.
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 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
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
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.
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
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
to specify the method of adding support packages to the deployable
archive.
Syntax | Description |
---|
-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
packagename | Only the specified support package is
included. To specify multiple support packages,
use multiple -Z inputs. |