Working with the MCR

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

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

You can install the MCR by running MCRInstaller.exe.

On platforms other than Windows, you must also set paths and environment variables. See Directories Required for Run-Time Deployment for more information about these settings.

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

Note   If you are deploying .NET component applications to programmers or end users, make sure to tell them to install .NET Framework before installing the MCR. The MCRinstaller.exe must detect the presence of .NET Framework on a system for it to install MCR .NET support. Alternatively, you can package .NET Framework with the component installer that you provide to them as part of your deployment package.

Note   MCRInstaller.exe has obsoleted the need for the function buildmcr or the creation of MCRInstaller.zip. See Replacement of MCRInstaller.zip and BUILDMCR Functionality for more details including complete file paths to all install programs.

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.

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

To run MATLAB on Mac OS X or Intel^® Mac, matlabroot/runtime 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 M-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 M-functions callable from within deployed application M-code

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

Note   The M-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 M-language functions getmcruserdata and setmcruserdata from deployed M applications. They are loaded by default only in applications created with the MATLAB Compiler or builder products. See Functions — Alphabetical List, for more information.

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

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:

 Building on UNIX

mbuild -gv -output magicmatrix magicmatrix.c libmagicmatrix.so

 Building on Windows

mbuild -gv -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};

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

int main()
{
    mclmcrInitialize();
    return mclRunMain((mclMainFcnType)run_main,0,NULL);
}

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

For a complete working example describing how to use Parallel Computing Toolbox with MATLAB Builder JA, see Example: Supplying Run-Time Configuration Information for Parallel Computing Toolbox Applications.

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:

Back to Top

Deploying to End Users

Deploying a Standalone Application on a Network Drive

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit