Working with the MATLAB Runtime

About the MATLAB Runtime

The MATLAB® runtime is a standalone set of shared libraries that enables the execution of MATLAB files on computers without an installed version of MATLAB. Applications that use artifiacts built with MATLAB Compiler™ require access to an appropriate version of the MATLAB runtime to run.

End-users of compiled artifacts without access to MATLAB must install the MATLAB runtime on their computers or know the location of a network-installed MATLAB runtime. The installers generated by the compiler app include the MATLAB runtime installer. If you compiled your artifact using mcc, you should direct your end-users to download the MATLAB runtime installer from the Web at http://www.mathworks.com/products/compiler/mcr.

See The MATLAB Runtime Installer for more information.

How is the MATLAB Runtime Different from MATLAB?

The MATLAB runtime differs from MATLAB in several important ways:

  • In the MATLAB runtime, MATLAB files are securely encrypted for portability and integrity.

  • MATLAB has a desktop graphical interface. The MATLAB runtime has all the MATLAB functionality without the graphical interface.

  • The MATLAB runtime is version-specific. You must run your applications with the version of the MATLAB runtime associated with the version of MATLAB Compiler with which it was created. For example, if you compiled an application using version 4.10 (R2009a) of MATLAB Compiler, users who do not have MATLAB installed must have version 7.10 of the MATLAB runtime installed. Use mcrversion to return the version number of the MATLAB runtime.

  • The MATLAB and Java® paths in an MATLAB runtime instance are fixed and cannot be changed. To change them, you must first customize them within MATLAB.

Performance Considerations and the MATLAB Runtime

MATLAB Compiler was designed to work with a large range of applications that use the MATLAB programming language. Because of this, run-time libraries are large.

Since the MATLAB runtime technology provides full support for the MATLAB language, including the Java programming language, starting a compiled application takes approximately the same amount of time as starting MATLAB. The amount of resources consumed by the MATLAB runtime is necessary in order to retain the power and functionality of a full version of MATLAB.

The MATLAB runtime makes use of thread locking so that only one thread is allowed to access the MATLAB runtime at a time. As a result, calls into the MATLAB runtime are threadsafe for MATLAB Compiler generated libraries, COM objects, and .NET objects. On the other hand, this can impact performance.

The MATLAB Runtime Installer

Download the MATLAB runtime from the Web at http://www.mathworks.com/products/compiler/mcr.

Installing the MATLAB Runtime

To install the MATLAB runtime, users of your application must run theMATLAB Runtime Installer.

    Note:   When packaging compiled MATLAB code for distribution, MATLAB Compiler can include the Web-based or the local MATLAB runtime installer in the distribution package.

To install the MATLAB runtime:

  1. Start the MATLAB Runtime Installer.

    ComputerSteps
    Windows®Double-click the compiled MATLAB code package self-extracting archive file, typically named my_program_pkg.exe, where my_program is the name of the MATLAB code. This extracts the MATLAB Runtime Installer from the archive, along with all the files that make up the MATLAB runtime. Once all the files have been extracted, the MATLAB Runtime Installer starts automatically.
    Linux®

    Extract the contents of the compiled package, which is a Zip file on Linux systems, typically named, my_program_pkg.zip, where my_program is the name of the compiled MATLAB code. Use the unzip command to extract the files from the package.

    unzip MCRInstaller.zip

    Run the MATLAB Runtime Installer script, from the directory where you unzipped the package file, by entering:

    ./install
    For example, if you unzipped the package and MATLAB Runtime Installer in \home\USER, you run the ./install from \home\USER.

      Note:   On Mac systems, you may need to enter an administrator username and password after you run ./install.

    Mac

  2. When the MATLAB Runtime Installer starts, it displays the following dialog box. Read the information and then click Next to proceed with the installation.

  3. Specify the folder in which you want to install the MATLAB runtime in the Folder Selection dialog box.

      Note:   On Windows systems, you can have multiple versions of the MATLAB runtime on your computer but only one installation for any particular version. If you already have an existing installation, the MATLAB runtime Installer does not display the Folder Selection dialog box because you can only overwrite the existing installation in the same folder.

  4. Confirm your choices and click Next.

    The MATLAB Runtime Installer starts copying files into the installation folder.

  5. On Linux and Macintosh systems, after copying files to your disk, the MATLAB Runtime Installer displays the Product Configuration Notes dialog box. This dialog box contains information necessary for setting your path environment variables. Copy the path information from this dialog box and then click Next.

  6. Click Finish to exit the installer.

MATLAB Runtime Installer Readme File.  A readme.txt file is included with the MATLAB Runtime Installer. This file, visible when the MATLAB Runtime Installer is expanded, provides more detailed information about the installer and the switches that can be used with it.

Installing the MATLAB Runtime and MATLAB on the Same Machine

You do not need to install the MATLAB runtime on your machine if your machine has both MATLAB and MATLAB Compiler installed. The version of MATLAB should be the same as the version of MATLAB that was used to create the compiled MATLAB code.

You can, however, install the MATLAB runtime for debugging purposes. See Modifying the Path.

    Caution   If the target machine has a MATLAB installation, the <mcr_root> folders must be first on the path to run the deployed application. To run MATLAB, the matlabroot folders must be first on the path.

Modifying the Path.  If you install the MATLAB runtime on a machine that already has MATLAB on it, you must adjust the library path according to your needs.

  • Windows

    To run deployed MATLAB code against the MATLAB runtime install, mcr_root\ver\runtime\win32|win64 must appear on your system path before matlabroot\runtime\win32|win64.

    If mcr_root\ver\runtime\arch appears first on the compiled application path, the application uses the files in the MATLAB runtime install area.

    If matlabroot\runtime\arch appears first on the compiled application path, the application uses the files in the MATLAB Compiler installation area.

  • UNIX®

    To run deployed MATLAB code against the MATLAB runtime install, on Linux, Linux x86-64, or the <mcr_root>/runtime/<arch> folder must appear on your LD_LIBRARY_PATH before matlabroot/runtime/<arch>. See MATLAB Runtime Path Settings for Run-time Deployment for the platform-specific commands.

    To run deployed MATLAB code on Mac OS X, the <mcr_root>/runtime folder must appear on your DYLD_LIBRARY_PATH before matlabroot/runtime/<arch>.

    To run MATLAB on Mac OS X or Intel® Mac, matlabroot/runtime/<arch> must appear on your DYLD_LIBRARY_PATH before the <mcr_root>/bin folder.

      Note:   For detailed information about setting MATLAB runtime paths on UNIX variants such as Mac and Linux, see Using MATLAB Compiler on Mac or Linux for complete deployment and troubleshooting information.

Installing Multiple MATLAB Runtimes on a Single Machine

MCRInstaller supports the installation of multiple versions of the MATLAB runtime on a target machine. This allows applications compiled with different versions of the MATLAB runtime to execute side by side on the same machine.

If you do not want multiple MATLAB runtime versions on the target machine, you can remove the unwanted ones. On Windows, run Add or Remove Programs from the Control Panel to remove any of the previous versions. On UNIX, you manually delete the unwanted MATLAB runtime. You can remove unwanted versions before or after installation of a more recent version of the MATLAB runtime, as versions can be installed or removed in any order.

    Note for Mac OS X Users   Installing multiple versions of the MATLAB runtime on the same machine is not supported on Mac OS X. When you receive a new version of MATLAB, you must recompile and redeploy all of your applications. Also, when you install a new MATLAB runtime onto a target machine, you must delete the old version of the MATLAB runtime and install the new one. You can only have one version of the MATLAB runtime on the target machine.

Deploying a Recompiled Application.  Always run your compiled applications with the version of the MATLAB runtime that corresponds to the MATLAB version with which your application was built. If you upgrade your MATLAB Compiler software on your development machine and distribute the recompiled application to your users, you should also distribute the corresponding version of the MATLAB runtime. Users should upgrade their MATLAB runtime to the new version. If users need to maintain multiple versions of the MATLAB runtime on their systems, refer to Installing Multiple MATLAB Runtimes on a Single Machine for more information.

Installing the MATLAB Runtime Non-Interactively

To install the MATLAB runtime without having to interact with the installer dialog boxes, use one of the MATLAB runtime installer's non-interactive modes:

  • silent—the installer runs as a background task and does not display any dialog boxes

  • automated—the installer displays the dialog boxes but does not wait for user interaction

When run in silent or automated mode, the MATLAB runtime installer uses default values for installation options. You can override these defaults by using MATLAB runtime installer command-line options or an installer control file.

    Note:   When running in silent or automated mode, the installer overwrites the default installation location.

Running the Installer in Silent Mode

To install the MATLAB runtime in silent mode:

  1. Extract the contents of the MATLAB runtime installer file to a temporary folder, called $temp in this documentation.

      Note:   On Windows systems, manually extract the contents of the installer file.

  2. Run the MATLAB runtime installer, specifying the -mode option and -agreeToLicense yes on the command line.

      Note:   On most platforms, the installer is located at the root of the folder into which the archive was extracted. On Windows 64, the installer is located in the archives bin folder.

    PlatformCommand
    Windowssetup -mode silent -agreeToLicense yes
    Linux./install -mode silent -agreeToLicense yes
    Mac OS X./install -mode silent -agreeToLicense yes

      Note:   If you do not include the -agreeToLicense yes the installer will not install the MATLAB runtime.

  3. View a log of the installation.

    On Windows systems, the MATLAB runtime installer creates a log file, named mathworks_username.log, where username is your Windows log-in name, in the location defined by your TEMP environment variable.

    On Linux and Mac systems, the MATLAB runtime installer displays the log information at the command prompt, unless you redirect it to a file.

Customizing a Non-Interactive Installation

When run in one of the non-interactive modes, the installer will use the default values unless told to do otherwise. Like the MATLAB installer, the MATLAB runtime installer accepts a number of command line options that modify the default installation properties.

OptionDescription
-destinationFolderSpecifies where the MATLAB runtime will be installed.
-outputFileSpecifies where the installation log file is written.
-automatedModeTimeoutSpecifies how long, in milliseconds, that the dialog boxes are displayed when run in automatic mode.
-inputFileSpecifies an installer control file with the values for all of the above options.

    Note:   The MATLAB runtime installer archive includes an example installer control file called installer_input.txt. This file contains all of the options available for a full MATLAB installation. Only the options listed in this section are valid for the MATLAB runtime installer.

Uninstalling the MATLAB Runtime

The method you use to uninstall the MATLAB runtime from your computer varies depending on the type of computer.

You can remove unwanted versions before or after installation of a more recent version of the MATLAB runtime, as versions can be installed or removed in any order.

Windows

  1. Start the uninstaller. From the Windows Start menu, search for the Add or Remove Programs control panel, and double-click MATLAB runtime in the list. You can also launch the MATLAB Runtime Uninstaller from the mcr_root\uninstall\bin\arch folder, where mcr_root is your MATLAB runtime installation folder and arch is an architecture-specific folder, such as win64.

  2. Select the MATLAB runtime from the list of products in the Uninstall Products dialog box and click Next.

  3. After the MATLAB runtime uninstaller removes the files from your disk, it displays the Uninstallation Complete dialog box. Click Finish to exit the uninstaller.

Linux

  1. Exit the application.

  2. Enter this command at the Linux prompt:

    rm -rf mcr_root

    where mcr_root represents the name of your top-level MATLAB installation folder.

Mac

  • Exit the application.

  • Navigate to your MATLAB runtime installation folder. For example, the installation folder might be named MATLAB_Compiler_Runtime.app in your Applications folder.

  • Drag your MATLAB runtime installation folder to the trash, and then select Empty Trash from the Finder menu.

MATLAB Runtime Startup Options

Setting MATLAB Runtime Options

Set MATLAB runtime options, such as -nojvm, -nodisplay, or -logfile by performing either of the following tasks.

  • Using the Additional Runtime Settings area of the compiler apps.

  • Using the mcc command, specify the -R switch.

Using a Compiler App.  In the Additional Runtime Settings area of the compiler apps, you can set the following options.

    Note:   Not all options are available for all compilation targets.

Setting MATLAB Runtime Startup Options Using the Compiler Apps

MATLAB Runtime Startup OptionThis option...Set the options by...
-nojvmDisables the Java Virtual Machine, which is enabled by default. This can help improve the runtime performance.Select the No JVM checkbox.
-nodisplayOn Linux, launches the runtime without display functionality.In the Settings box, enter -R -nodisplay.
-logfileWrites information about the runtime startup to a logfile.Select the Create log file checkbox. Enter the path to the logfile, including the logfile name, in the Log File box.

Setting MATLAB Runtime Startup Options Using the mcc Command Line.  When you use the command line, specify the -R switch to invoke the MATLAB runtime startup options you want to use.

Following are examples of using mcc -R to invoke -nojvm, -nodisplay, and -logfile when building a C standalone (designated by the -m switch).

 Setting -nojvm

 Setting -nodisplay (Linux Only)

 Setting -logfile

 Setting -nojvm, -nodisplay, and -logfile With One Command

Retrieving MATLAB Runtime Startup Options (Shared Libraries Only)

Use these functions to return data about MATLAB runtime state when working with shared libraries.

Function and SignatureWhen to UseReturn Value
bool mclIsMCRInitialized()Use mclIsMCRInitialized() to determine whether or not the runtime has been properly initialized.Boolean (true or false).
Returns true if runtime is already initialized, else returns false.
bool mclIsJVMEnabled()Use mclIsJVMEnabled() to determine if the runtime was launched with an instance of a Java Virtual Machine (JVM).Boolean (true or false).
Returns true if runtime is launched with a JVM instance, else returns false.
const char* mclGetLogFileName()Use mclGetLogFileName() to retrieve the name of the log file used by the runtimeCharacter string representing log file name used by the runtime
bool mclIsNoDisplaySet()Use mclIsNoDisplaySet() to determine if -nodisplay option is enabled.Boolean (true or false).
Returns true if -nodisplay is enabled, else returns false.

    Note:   false is always returned on Windows systems since the -nodisplay option is not supported on Windows systems.

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

    Note:   All of these attributes have properties of write-once, read-only.

Retrieving Information About MATLAB Runtime Startup Options.  

 const char* options[4];     
    options[0] = "-logfile";    
    options[1] = "logfile.txt";
    options[2] = "-nojvm";
    options[3] = "-nodisplay"; 
    if( !mclInitializeApplication(options,4) )
    {
        fprintf(stderr, 
                "Could not initialize the application.\n");
        return -1;
    }
    printf("MCR initialized : %d\n", mclIsMCRInitialized());
    printf("JVM initialized : %d\n", mclIsJVMEnabled());
    printf("Logfile name : %s\n", mclGetLogFileName());
    printf("nodisplay set : %d\n", mclIsNoDisplaySet());
    fflush(stdout);

Using the MATLAB Runtime User Data Interface

The MATLAB runtime User Data Interface lets you easily access MATLAB runtime data. It allows keys and values to be passed between an MATLAB runtime instance, the MATLAB code running on the runtime, and the host application that created the runtime instance. Through calls to the MATLAB Runtime User Data Interface API, you access MATLAB runtime data by creating a per-runtime-instance associative array of mxArrays, consisting of a mapping from string keys to mxArray values. Reasons for doing this include, but are not limited to the following:

  • You need to supply run-time profile information to a client running an application created with the Parallel Computing Toolbox. You supply and change profile information on a per-execution basis. For example, two instances of the same application may run simultaneously with different profiles. See Deploy Applications Created Using Parallel Computing Toolbox for more information.

  • You want to set up a global workspace, a global variable or variables that MATLAB and your client can access.

  • You want to store the state of any variable or group of variables.

The API consists of:

  • Two MATLAB functions callable from within deployed application MATLAB code

  • Four external C functions callable from within deployed application wrapper code

    Note:   The MATLAB functions are available to other modules since they are native to MATLAB. These built-in functions are implemented in the MCLMCR module, which lives in the standalone folder.

For implementations using .NET assemblies, Java packages, or COM components with Excel, see the MATLAB Builder™ NE, MATLAB Builder JA, and MATLAB Builder EX documentation, respectively.

MATLAB Functions

Use the MATLAB functions getmcruserdata and setmcruserdata from deployed MATLAB applications. They are loaded by default only in applications created with the MATLAB Compiler or builder products. See Using the MATLAB Runtime User Data Interface for more information.

    Tip   getmcruserdata and setmcruserdata will produce an Unknown function error when called in MATLAB if the MCLMCR module cannot be located. This can be avoided by calling isdeployed before calling getmcruserdata and setmcruserdata. For more information about the isdeployed function, see the isdeployed reference page.

Setting MATLAB Runtime Data for Standalone Executables

MATLAB runtime data can be set for a standalone executable with the -mcruserdata command line argument.

The following example demonstrates how to set MATLAB runtime user data for use with a Parallel Computing Toolbox profile:

 parallelapp.exe -mcruserdata 
                  ParallelProfile:config.settings

The argument following -mcruserdata is interpreted as a key/value MATLAB runtime user data pair, where the colon separates the key from the value. The standalone executable accesses this data by using getmcruserdata.

    Note:   A compiled application should set mcruserdata ParallelProfile before calling any Parallel Computing Toolbox™ code. Once this code has been called, setting ParallelProfile to point to a different file has no effect.

Setting and Retrieving MATLAB Runtime Data for Shared Libraries

As mentioned in Using the MATLAB Runtime User Data Interface, there are many possible scenarios for working with MATLAB runtime data. The most general scenario involves setting the MATLAB runtime with specific data for later retrieval, as follows:

  1. In your code, include the MATLAB runtime header file and the library header generated by MATLAB Compiler.

  2. Properly initialize your application using mclInitializeApplication.

  3. After creating your input data, write or "set" it to the MATLAB runtime with setmcruserdata .

  4. After calling functions or performing other processing, retrieve the new MATLAB runtime data with getmcruserdata.

  5. Free up storage memory in work areas by disposing of unneeded arrays with mxDestroyArray.

  6. Shut down your application properly with mclTerminateApplication.

Displaying MATLAB Runtime Initialization Start-Up and Completion Messages For Users

You can display a console message for end users that informs them when MATLAB runtime initialization starts and completes.

To create these messages, use the -R option of the mcc command.

You have the following options:

  • Use the default start-up message only (Initializing MATLAB Compiler Runtime version x.xx)

  • Customize the start-up or completion message with text of your choice. The default start-up message will also display prior to displaying your customized start-up message.

Some examples of different ways to invoke this option follow:

This command:Displays:
mcc -R -startmsgDefault start-up message Initializing MATLAB Compiler Runtime version x.xx
mcc -R -startmsg,'user customized message'Default start-up message Initializing MATLAB Compiler Runtime version x.xx and user customized message for start-up
mcc -R -completemsg,'user customized message'Default start-up message Initializing MATLAB Compiler Runtime version x.xx and user customized message for completion
mcc -R -startmsg,'user customized message' -R -completemsg,'user customized message" Default start-up message Initializing MATLAB Compiler Runtime version x.xx and user customized message for both start-up and completion by specifying -R before each option
mcc -R -startmsg,'user customized message',-completemsg,'user customized message'Default start-up message Initializing MATLAB Compiler Runtime version x.xx and user customized message for both start-up and completion by specifying -R only once

Best Practices

Keep the following in mind when using mcc -R:

  • When calling mcc in the MATLAB Command Window, place the comma inside the single quote. For example:

    mcc -m hello.m -R '-startmsg,"Message_Without_Space"'

  • If your initialization message has a space in it, call mcc from the system console or use !mcc from MATLAB.

Was this topic helpful?