Working with the MCR

About the MATLAB Compiler Runtime (MCR)

MATLAB Compiler uses the MATLAB Compiler Runtime (MCR), a standalone set of shared libraries that enables the execution of MATLAB files on computers without an installed version of MATLAB.

If you do not have MATLAB installed on the target machine and you want to run components created by MATLAB Compiler , you still need to install the MCR on the target machine, whether you are a developer or end user. You have to install the MCR only once. There is no way to distribute your application with any subset of the files that are installed by MCRInstaller.exe.

See Deploying to End Users for more information about the general steps for installing the MCR as part of the deployment process.

See also Using MCR Installer Command Line Options for more information.

How is the MCR Different from MATLAB?

This MCR differs from MATLAB in several important ways:

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

• MATLAB has a desktop graphical interface. The MCR is has all of MATLAB's functionality without the graphical interface.

• The MCR is version-specific. You must run your applications with the version of the MCR 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 MCR installed. Use mcrversion to return the version number of the MCR.

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

Performance Considerations and the MCR

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 MCR 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 MCR is necessary in order to retain the power and functionality of a full version of MATLAB.

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

Back to Top

Installing the MCR and MATLAB on the Same Machine

You do not need to install the MCR 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 deployed component.

Caution   There is a limitation regarding folders on your path. 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. This restriction only applies to configurations involving an installed MCR and an installed MATLAB on the same machine.

Modifying the Path

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

Windows.  To run deployed components against the MCR 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 MCR 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 components against the MCR install, on Linux, Linux x86-64, or the <mcr_root>/runtime/<arch> folder must appear on your LD_LIBRARY_PATH before matlabroot/runtime/<arch>, and XAPPLRESDIR should point to <mcr_root>/X11/app-defaults. See Directories Required for Run-Time Deployment for the platform-specific commands.

To run deployed components on Mac OS X, the <mcr_root>/runtime folder must appear on your DYLD_LIBRARY_PATH before matlabroot/runtime/<arch>, and XAPPLRESDIR should point to <mcr_root>/X11/app-defaults.

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, and XAPPLRESDIR should point to matlabroot/X11/app-defaults.

Back to Top

Installing Multiple MCRs on One Machine

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

If you do not want multiple MCR 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 MCR. You can remove unwanted versions before or after installation of a more recent version of the MCR, as versions can be installed or removed in any order.

Note for Mac OS X Users   Installing multiple versions of the MCR 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 and components. Also, when you install a new MCR onto a target machine, you must delete the old version of the MCR and install the new one. You can only have one version of the MCR on the target machine.

Deploying a Recompiled Application

Always run your compiled applications with the version of the MCR 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 MCR. Users should upgrade their MCR to the new version. If users need to maintain multiple versions of the MCR on their systems, refer to Installing Multiple MCRs on One Machine for more information.

Back to Top

Retrieving MCR Attributes

Use these new functions to return data about MCR state when working with shared libraries (this does not apply to standalone applications).

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

Example: Retrieving Information from MCR State

 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);

Back to Top

Improving Data Access Using the MCR User Data Interface

The MCR User Data Interface lets you easily access MCR data. It allows keys and values to be passed between an MCR instance, the MATLAB code running on the MCR, and the wrapper code that created the MCR. Through calls to the MCR User Data Interface API, you access MCR data by creating a per-MCR-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 configuration information to a client running an application created with the Parallel Computing Toolbox. You supply and change configuration information on a per-execution basis. For example, two instances of the same application may run simultaneously with different configuration files. See Deploying 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 components, Java components, or COM components with Excel, see the MATLAB Builder NE User's Guide, MATLAB Builder JA User's Guide, and MATLAB Builder EX User's Guide, 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 Functions — Alphabetical List, for more information.

Tip   When calling the MATLAB functions getmcruserdata and setmcruserdata, remember the following: These functions 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. The MATLAB functions getmcruserdata and setmcruserdata can be dragged and dropped (as you would any other MATLAB file), directly to the deploytool GUI.

External C Functions

Use the following C functions in deployed C/C++ applications. See Functions — Alphabetical List for more information.

• libnameGetMcrID

• mclSetMCRUserData

• mclGetMCRUserData

• mclSetCmdLineUserData

Setting MCR Data for Standalone Executables

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

The following example demonstrates how to set MCR user data for use with a Parallel Computing Toolbox configuration .mat file:

 parallelapp.exe -mcruserdata 
                  ParallelConfigurationFile:config.mat

The argument following -mcruserdata is interpreted as a key/value MCR 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 ParallelConfigurationFile before calling any Parallel Computing Toolbox™ code. Once this code has been called, setting ParallelConfigurationFile to point to a different file has no effect.

Setting and Retrieving MCR Data for Shared Libraries

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

1. Outside the scope of your main code, use libnameGetMcrID to retrieve the key value of the MCR data you want to update.

2. In your code, Include the MCR header file and the library header generated by MATLAB Compiler.

3. Properly initialize your application using mclInitializeApplication.

4. After creating your input data, write or "set" it to the MCR with setmcruserdata or mclSetMCRUserData, as appropriate. Use mclSetCmdLineUserData to set data from the command line.

5. After calling functions or performing other processing, retrieve the new MCR data with getmcruserdata or mclGetMCRUserData, as appropriate.

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

7. Shut down your application properly with mclTerminateApplication.

Example: MagicMatrix.  This following is an end-to-end example showing how to set and retrieve MCR data with the magicmatrix application and the MCR User Data interface API:

 MagicMatrix Function

function magicmatrix
    key = 'MagicMatrix';
    m = getmcruserdata(key);
    disp(m);
    m = m + 1;
    setmcruserdata(key, m);

 Building the Shared Library with mcc

mcc -B csharedlib:libmagicmatrix magicmatrix.m setmcruserdata 
                                             getmcruserdata -Nv 

 Building on UNIX

mbuild -g -v -output magicmatrix magicmatrix.c libmagicmatrix.so

 Building on Windows

mbuild -g -v -output magicmatrix magicmatrix.c 
                             libmagicmatrix.lib

 Running on UNIX

% ./magicmatrix

 Running on Windows

C:\> magicmatrix.exe

 Running on 64-bit Macintosh

./magicmatrix.app/Contents/MacOS/magicmatrix

 magicmatrix.c

#include <stdio.h>

/* Include the MCR header file and the library specific header
 * file as generated by MATLAB Compiler */
#include "libmagicmatrix.h"

/* This function is used to display a double matrix stored in
 * an mxArray */
void display(const mxArray* in);

int run_main(int argc, char **argv)
{
    /* Input and output parameters. For testing, keep inputValue
     *   and outputValue in separate arrays, so a dangling 
     *   pointer can't
     * cause a false positive.
     */
    mxArray *key, *inputValue; 
    mxArray *outputValue = NULL;
    
    /* Column-major 3x3 magic square. */
    double data[] = {8, 3, 4, 1, 5, 9, 6, 7, 2};

    /* Call the library intialization routine and make sure 
     * that the
     * library was initialized properly. */
    if (!libmagicmatrixInitialize()){
        fprintf(stderr,"Could not initialize the library.\n");
        return -2;
    }
    else
    {
        /* Declare an array to hold the inputs */
        mxArray *key = 0, *inputValue = 0;

        /* Create the input data */
        inputValue = mxCreateDoubleMatrix(3,3,mxREAL); /* key */
        key = mxCreateString("MagicMatrix");       /* value */
        memcpy(mxGetPr(inputValue), data, 9*sizeof(double));
    
        /* Set the user data: 2 inputs, no outputs */
        mlfSetmcruserdata(key, inputValue);

        /* Call the library function */
        mlfMagicmatrix(0, NULL, NULL);

        /* Get the MCR user data - it should be different now */
        mlfGetmcruserdata(1, &outputValue, key);

        display(outputValue);

        /* Clean up */
        mxDestroyArray(outputValue); outputValue=0;

        /* Call the library termination routine */
        libmagicmatrixTerminate();
        
        /* Free the memory created for the inputs */
        mxDestroyArray(key); key = 0;
        mxDestroyArray(inputValue); inputValue = 0;
    }

    /* Shut everything down */
    mclTerminateApplication();
    return 0;
}


/*DISPLAY This function will display the double matrix stored 
 * in an mxArray.
 * This function assumes that the mxArray passed as
 * input contains double array.
 */
void display(const mxArray* in)
{
    int i=0, j=0; /* loop index variables */
    int r=0, c=0; /* variables to store the row and column 
    * length of the matrix */
    double *data; /* variable to point to the double data 
    * stored within the mxArray */

    /* Get the size of the matrix */
    r = mxGetM(in);
    c = mxGetN(in);
    /* Get a pointer to the double data in mxArray */
    data = mxGetPr(in);
    
    /* Loop through the data and display the same in 
    * matrix format */
    for( i = 0; i < c; i++ ){
        for( j = 0; j < r; j++){
            printf("%4.2f\t",data[j*c+i]);
        }
        printf("\n");
    }
    printf("\n");
}

/* Initialize the application */
    if( !mclInitializeApplication(NULL,0) )
    {
        fprintf(stderr, 
         "Could not initialize the application.\n");
    	return -1;
    }
    

Deploying Applications Created Using Parallel Computing Toolbox

For information about creating and exporting configurations from Parallel Computing Toolbox applications, see Programming with User Configurations.

For information about using the MCR User Data Interface see "Improving Data Access Using the MCR User Data Interface" in the MATLAB Builder JA, MATLAB Builder NE, and MATLAB Builder EX User's Guides.

For a complete working example describing how to use Parallel Computing Toolbox with MATLAB Builder JA, see .

Example: Compiling and Deploying a Standalone Application (with MAT File Passed at Run-time) with the Parallel Computing Toolbox.  This example shows how to compile a standalone application, using functions from the Parallel Computing Toolbox, with deploytool. In this case, the configuration information is passed at run-time.

Note   It is not possible to compile and deploy applications using the LOCAL scheduler. You must have access to MDCS workers.

 Step 1: Write Your PCT Code

 Step 2: Export Your Configuration as a MAT file

 Step 3: Compile and Deploy Your Application

Example: Compiling and Deploying a Standalone Application (with MAT File in the CTF Archive) with the Parallel Computing Toolbox.  This example shows how to compile a standalone application, using functions from the Parallel Computing Toolbox, with deploytool. In this case, the configuration information is embedded in the CTF archive as a MAT file, and you set up the MCR to work with PCT using the setmcruserdata function in MATLAB.

Note   It is not possible to compile and deploy applications using the LOCAL scheduler. You must have access to MDCS workers.

 Step 1: Write Your PCT Code

function run_sample_pct(n)
% Set the Parallel Configuration file:
if(isdeployed)
    matfile = 'myconfig.mat'; % can also use uigetfile to let 
                                        the USER select file
    setmcruserdata('ParallelConfigurationFile',matfile);
end
speedup = sample_pct(n)

function speedup = sample_pct (n)
warning off all;
if(ischar(n))
    n=str2double(n);
end
tic
for ii = 1:n
   (cov(sin(magic(n)+rand(n,n))));
end
time1 =toc;
matlabpool('open',4);
tic
parfor ii = 1:n
   (cov(sin(magic(n)+rand(n,n))));
end
time2 =toc;
disp(['Normal loop times: ' num2str(time1) ...
    ', parallel loop time: ' num2str(time2) ]);
disp(['parallel speedup:  ' num2str(1/(time2/time1)) ...
    ' times faster than normal']);
matlabpool('close','force');
disp('done');
speedup = (time1/time2);

 Step 2: Compile and Deploy Your Application

Back to Top

Displaying MCR Initialization Start-Up and Completion Messages For Users

You can display a console message for end users that informs them when MCR 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:

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.

Back to Top

Deploying to End Users

Deploying a Standalone Application on a Network Drive

Free MATLAB Compiler Interactive Kit

Learn how to build standalone executables and C/C++ shared libraries from MATLAB code.

Get free kit

Trials Available

Try the latest version of MATLAB Compiler.

Get trial software