MATLAB® Compiler™

Deploying to End Users

Steps by the Programmer to Deploy to End Users

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.

For an end user to run an application or use a library that contains compiled M-code, there are two sets of tasks. Some tasks are for the programmer who developed the application or library, and some tasks are for the end user.

1. Create a package that contains the software needed at run time. See What Software Does a Programmer Need? for more details.

   Note   The package needed for end users must include the .ctf file, which includes all the files in your preferences directory. Thus, you should make sure that you do not have files in your preferences directory that you do not want to expose to end users. MATLAB preferences set at compile time are inherited by a compiled application. Preferences set by a compiled application do not affect the MATLAB preferences, and preferences set in MATLAB do not affect a compiled application until that application is recompiled. The preferences directory is as follows: $HOME/.matlab/current_release on UNIX system root\profiles\user\application data\mathworks\ matlab\current_release on Windows The directory will be stored in the CTF archive in a directory with a generated name, such as: mwapplication_mcr/myapplication_7CBEDC3E1DB3D462C18914C13CBFA649.

   Caution   MATLAB does not save your preferences directory until you exit MATLAB. Therefore, if you make changes to your MATLAB preferences, stop and restart MATLAB before attempting to recompile using your new preferences.

2. Write instructions for the end user. See Steps by the End User on the Windows^® Operating System.

3. Distribute the package to your end user, along with the instructions.

Steps by the End User on the Windows^® Operating System

1. Open the package containing the software needed at run time.

2. Run MCRInstaller once on the target machine, that is, the machine where you want to run the application or library. The MCRInstaller opens a command window and begins preparation for the installation. See Using the MCR Installer GUI.

3. If you are deploying a Java™ application to end users, they must set the class path on the target machine.

Note for Windows® Applications   You must have administrative privileges to install the MCR on a target machine since it modifies both the system registry and the system path. Running the MCRInstaller after the MCR has been set up on the target machine requires only user-level privileges.

Steps by the End User on the UNIX^® System

1. Install the MCR.

   Locate the MCRInstaller.zip file and copy it to a new directory on your machine. This new directory will become the installation directory for your library or application. To install the MCR, unzip MCRInstaller.zip.

2. Set the path environment variables properly. See Directories Required for Run-Time Deployment.

3. When you deploy a Java application to end users, they must set the class path on the target machine.

Using the MCR Installer GUI

1. When the MCR Installer wizard appears, click Next to begin the installation. Click Next to continue.

2. In the Select Installation Folder dialog box, specify where you want to install the MCR and whether you want to install the MCR for just yourself or others. Click Next to continue.

   Note   The Install MATLAB® Compiler™ Runtime for yourself, or for anyone who uses this computer option is not implemented for this release. The current default is Everyone.

3. Confirm your selections by clicking Next.

   The installation begins. The process takes some time due to the quantity of files that are installed.

   The MCRInstaller automatically:

   • Copies the necessary files to the target directory you specified.

   • Registers the components as needed.

   • Updates the system path to point to the MCR binary directory, which is <target_directory>/<version>/runtime/bin/win32.

4. When the installation completes, click Close on the Installation Completed dialog box to exit.

Back to Top

What Software Does the End User Need?

The software required by end users depends on which of the following kinds of software is to be run by the user:

• Standalone Compiled Application That Accesses Shared Library

• .NET Application

• COM Application

• Java™ Application

• Microsoft^® Excel^®Add-In

Standalone Compiled Application That Accesses Shared Library

To distribute a shared library created with the MATLAB Compiler product to end users, create a package that includes the following files.

.NET Application

To distribute a .NET application that uses components created with the MATLAB^® Builder™ NE product, create a package that includes the following files.

COM Application

To distribute a COM application that uses components created with the MATLAB Builder NE or MATLAB Builder EX product, create a package that includes the following files.

Java™ Application

To distribute a Java application created with the MATLAB Builder JA product, create a componentname.jar file. To deploy the application on computers without MATLAB^®, you must include the MCR when creating your Java component. As of R2007b, JAR files contain the CTF file, as well. See How Does the MATLAB^® Builder™ JA Product Use JAR Files?.

Microsoft^® Excel^®Add-In

To distribute an Excel^® add-in created with the MATLAB Builder EX product, create a package that includes the following files.

Back to Top

Using Relative Paths with Project Files

Project files now support the use of relative paths as of R2007b of the MATLAB Compiler product, enabling you to share a single project file for convenient deployment over the network. Simply share your project directory and use relative paths to define your project location to your distributed computers.

Back to Top

Porting Generated Code to a Different Platform

You can distribute an application generated by the MATLAB Compiler product to any target machine that has the same operating system as the machine on which the application was compiled. For example, if you want to deploy an application to a Windows machine, you must use the Windows version of the MATLAB Compiler product to build the application on a Windows machine.

Note   Since binary formats are different on each platform, the components generated by the MATLAB Compiler product cannot be moved from platform to platform as is.

To deploy an application to a machine with an operating system different from the machine used to develop the application, you must rebuild the application on the desired targeted platform. For example, if you want to deploy a previous application developed on a Windows machine to a Linux machine, you must use the MATLAB Compiler product on a Linux machine and completely rebuild the application. You must have a valid MATLAB Compiler license on both platforms to do this.

Back to Top

Extracting a CTF Archive Without Executing the Component

CTF archives contain content (M-files and MEX-files) that need to be extracted from the archive before they can be executed. In order to extract the archive you must override the default CTF embedding option (see Overriding Default CTF Archive Embedding Using MCR Component Cache). To do this, ensure that you compile your component with the -C Do Not Embed CTF Archive By Default option.

The CTF archive automatically expands the first time you run the MATLAB Compiler-based component (a MATLAB Compiler based standalone application or an application that calls a MATLAB Compiler-based shared library, COM, or .NET component).

To expand an archive without running the application, you can use the extractCTF (.exe on Windows) standalone utility provided in the matlabroot/toolbox/compiler/deploy/arch directory, where arch is your system architecture, Windows = win32, Linux = glnx86, Solaris = sol64, x86-64 = glnxa64, and Mac OS X = mac. This utility takes the CTF archive as input and expands it into the directory in which it resides. For example, this command expands hello.ctf into the directory where it resides:

extractCTF hello.ctf

The archive expands into a directory called hello_mcr. In general, the name of the directory containing the expanded archive is <componentname>_mcr, where componentname is the name of the CTF archive without the extension.

Note   To run extractCTF from any directory, you must add matlabroot/toolbox/compiler/deploy/arch to your PATH environment variable. Run extractCTF.exe from a system prompt. If you run it from MATLAB, be sure to utilize the bang (!) operator.

Back to Top

Dependency Analysis Function (depfun) and User Interaction with the Compilation Path

The MATLAB Compiler product uses a dependency analysis function (depfun) to determine the list of necessary files to include in the CTF package. In some cases, this process includes an excessive number of files, for example, when MATLAB OOPS classes are included in the compilation and it cannot resolve overloaded methods at compile time. The dependency analysis is an iterative process that also processes include/exclude information on each pass. Consequently, this process can lead to very large CTF archives resulting in long compilation times for relatively small applications.

depfun searches for "executable" content such as:

• M-files

• P-files

• Java classes and .jar files

• .fig files

• MEX-files and dependent binaries

depfun does not search for data files of any kind. You must manually include data files.

M-files are encrypted by depfun, and depfun creates authorization files for each MEX-file. This file guards against MEX-files of the same name (but of different functionality) being placed into exploded CTF directories.

The most effective way to reduce the number of files is to constrain the MATLAB path that depfun uses at compile time. The MATLAB Compiler product includes features that enable you to manipulate the path. Currently, there are three ways to interact with the compilation path:

• addpath and rmpath in MATLAB

• Passing -I <directory> on the mcc command line

• Passing -N and -p directories on the mcc command line

addpath and rmpath in MATLAB^®

If you run the MATLAB Compiler product from the MATLAB prompt, you can use the addpath and rmpath commands to modify the MATLAB path before doing a compilation. There are two disadvantages:

• The path is modified for the current MATLAB session only.

• If the MATLAB Compiler product is run outside of MATLAB, this doesn't work unless a savepath is done in MATLAB.

  Note   The path is also modified for any interactive work you are doing in the MATLAB environment as well.

Passing -I <directory> on the Command Line

You can use the -I option to add a directory to the beginning of the list of paths to use for the current compilation. This feature is useful when you are compiling files that are in directories currently not on the MATLAB path.

Passing -N and -p <directory> on the Command Line

There are two MATLAB Compiler options that provide more detailed manipulation of the path. This feature acts like a "filter" applied to the MATLAB path for a given compilation. The first option is -N. Passing -N on the mcc command line effectively clears the path of all directories except the following core directories (this list is subject to change over time):

• matlabroot/toolbox/matlab

• matlabroot/toolbox/local

• matlabroot/toolbox/compiler/deploy

• matlabroot/toolbox/compiler

It also retains all subdirectories of the above list that appear on the MATLAB path at compile time. Including -N on the command line allows you to replace directories from the original path, while retaining the relative ordering of the included directories. All subdirectories of the included directories that appear on the original path are also included. In addition, the -N option retains all directories that the user has included on the path that are not under matlabroot/toolbox.

Use the -p option to add a directory to the compilation path in an order-sensitive context, i.e., the same order in which they are found on your MATLAB path. The syntax is

p <directory>

where <directory> is the directory to be included. If <directory> is not an absolute path, it is assumed to be under the current working directory. The rules for how these directories are included are

• If a directory is included with -p that is on the original MATLAB path, the directory and all its subdirectories that appear on the original path are added to the compilation path in an order-sensitive context.

• If a directory is included with -p that is not on the original MATLAB path, that directory is not included in the compilation. (You can use -I to add it.)

• If a path is added with the -I option while this feature is active (-N has been passed) and it is already on the MATLAB path, it is added in the order-sensitive context as if it were included with -p. Otherwise, the directory is added to the head of the path, as it normally would be with -I.

  Note   The -p option requires the -N option on the mcc command line.

Back to Top

Deploying to Programmers

Working with the MCR