Deploying with the Magic Square Example

About This Example

The examples for MATLAB Compiler are in matlabroot\extern\examples\compiler. For matlabroot, substitute the MATLAB root folder on your system. Type matlabroot to see this folder name.

The Magic Square example in this section shows you how to:

• Use MATLAB Compiler to create and package a simple standalone application that compiles an M-file, magicsquare.m

• Access the examples provided with MATLAB Compiler.

Note   If you are using a non-Windows operating system, "console applications" are referred to as "standalone applications".

Tip   To set examplesDir to the path matlabroot\extern\examples\compiler, click here.

Command-Line Alternative

The examples use the deploytool GUI, a graphical front-end interface to MATLAB Compiler software. You can perform these tasks using the command-line interface to MATLAB Compiler software. See Using the Command Line (mcc) to Create Standalone Applications and Shared Libraries and the mcc reference page for complete reference information.

Back to Top

Magic Square Example: MATLAB Programmer Tasks

The MATLAB programmer performs the tasks described in the following table.

Key Tasks for the MATLAB Programmer

The Magic Square example shows how to create a standalone application, or shared library (magicsquare), containing the magic class and other files for application deployment. The class encapsulates a MATLAB function which computes a magic square.

The client standalone application or shared library converts the array returned by the function to a native array and displays it on the screen. When you run the magicsquare application from the command line, you pass the dimension for the magic square as a command-line argument

Note   The examples for the MATLAB Compiler product reside in matlabroot\extern\examples\compiler. This example assumes that the work folder is on drive D:.

Starting the Deployment Tool

You can access the MATLAB Compiler product through the Deployment Tool GUI (deploytool). Alternately, you can use the mcc function of MATLAB Compiler. deploytool is the GUI front end for mcc, the command that executes MATLAB Compiler.

This tutorial uses deploytool. If you want to use mcc, see Using the Command Line (mcc) to Create Standalone Applications and Shared Libraries . Also see the mcc reference page for complete reference information.

To start the Deployment Tool by perform the following steps:

1. Start MATLAB.

2. Type deploytool at the MATLAB command prompt. The deploytool GUI opens.

Copying the Example Files

Prepare to run the example by copying needed files into your work area as follows:

1. Navigate to matlabroot\extern\examples\compiler. matlabroot is the MATLAB root folder (where you installed MATLAB). To find the value of this variable on your system, type matlabroot at a MATLAB command prompt.

2. Create a work folder named Work (D:\Work). Create a subfolder in your Work folder and name it MagicExample (D:\Work\MagicExample). Avoid using spaces in your folder names, if possible.

3. Copy magicsquare.m from matlabroot\extern\examples\compiler to D:\Work\MagicExample.

4. To run your resulting client standalone application or shared library, verify that MATLAB can find it. Use the File > Set Path option in MATLAB to add the D:\Work\MagicExample folder to the MATLAB search path.

5. At the MATLAB command prompt, change your working folder to D:\Work\MagicExample.

Testing the M-File You Want To Deploy

In this example, you test an M-file (magicsquare.m) containing the predefined MATLAB function magic. Testing the file provides a baseline to compare to the results of the function as a deployable standalone application or shared library.

1. Using MATLAB, locate and open magicsquare.m. This file has the following:

   function m = magicsquare(n)
   %MAGICSQUARE generates a magic square matrix of the size
   % specified by the input parameter n.
   
   % Copyright 2003-2007 The MathWorks, Inc.
   
   if ischar(n)
       n=str2num(n);
   end
   m = magic(n)
   

2. At the MATLAB command prompt, enter magicsquare(5), and view the results. The output appears as follows:

   17 24  1  8 15
   23  5  7 14 16
    4  6 13 20 22
   10 12 19 21  3
   11 18 25  2  9

Creating a Deployable Standalone Application or Shared Library

You create a deployable standalone application or shared library by using the Deployment Tool GUI to build a wrapper. This wrapper encloses the sample M-code discussed in Testing the M-File You Want To Deploy. To run the Magic Square example, use the following information:

1. Create a deployment project. A project is a collection of files you bundle together under a project file name (.prj file) for your convenience in the Deployment Tool. Using a project makes it easy for you to build and run an application many times—effectively testing it—until it is ready for deployment.

   1. Type the name of your project in the Name field.

   2. Enter the location of the project in the Location field. Alternately, navigate to the location.

   3. Select the target for the deployment project from the Target drop-down menu.

   4. Click OK.

2. On the Build tab, add what you want to compile, and any supporting files, to the project.

   1. Do the following, depending on the type of application you are building:

      • If you are building a C or C++ application, click Add files

   2. Add any supporting files. For example, you can add the following files, as appropriate for your project:

      • Functions called using eval (or variants of eval)

      • Functions not on the MATLAB path

      • Code you want to remain private

      • Code from other programs that you want to compile and link into the main file

      If you want to include additional files, in the Shared Resources and Helper Files area, click Add files/directories. Click Open to select the file or files.

3. When you complete your changes, click the Build button ( ).

Packaging Your Deployment Application (Optional)

Packaging is bundling the standalone application or shared libraries with additional files for end users. Perform this step using the Package tab of deploytool. Alternately, copy the contents of the distrib folder and the MCR Installer to a local folder of your choice.

1. On the Package tab, add the MATLAB Compiler Runtime (the MCR) by clicking Add MCR.

2. Next, add others files useful for end users. The readme.txt file contains important information about others files useful for end users. To package additional files or folders, click Add file/directories, select the file or folder you want to package, and click Open.

3. In the Deployment Tool, click the Packaging button ( ).

4. After packaging, the package resides in the distrib subfolder. On Windows^®, the package is a self-extracting executable. On platforms other than Windows, it is a .zip file. Verify that the contents of the distrib folder contains the files you specified.

Copy the Package You Created (Optional)

Copy the package that you created from the distrib folder to the local folder of your choice or send them to the C/C++ programmer, if applicable.

Using the Command Line (mcc) to Create Standalone Applications and Shared Libraries

Instead of the GUI, you can use the mcc command to run MATLAB Compiler. The following table shows sample commands to create a standalone application or a shared library using mcc at the operating system prompt.

mcc -m mymfunction.m

mcc -B csharedlib:libfiles file1.m file2.m file3.m 

mcc -B cpplib:libfiles file1.m file2.m file3.m 

Back to Top

Magic Square Example: C/C++ Programmer Tasks

The C or C++ programmer performs these tasks.

Key Tasks for the C or C++ Programmer

Gathering Files Necessary for Deployment

Before beginning, verify that you have access to the following files, packaged by the MATLAB Programmer in Copy the Package You Created (Optional). End users who do not have a copy of MATLAB installed need the following:

• MCR Installer. For locations of all MCR Installers, run the mcrinstaller command.

• readme.txt file

See Packaging Your Deployment Application (Optional) for more information about these files.

Distribute to End Users

If the MATLAB programmer packages the standalone or library (see Packaging Your Deployment Application (Optional)), paste the package in a folder on the target machine, and run it. If you are using a .zip file bundled with WinZip, unzip and extract the contents to the target machine.

Note   If you are using a non-Windows operating system, "console applications" are referred to as "standalone applications".

Install the MCR on Target Computers Without MATLAB and Update System Paths

On target computers without MATLAB, install the MCR, if it is not already present on the development machine:

 What Is the MATLAB Compiler Runtime (MCR) and How Do I Get It?

Replacement of MCRInstaller.zip and BUILDMCR Functionality.   In past releases, you included MCRInstaller.zip in your packaged application (created by running the buildmcr command). Now, you run the following files, which trigger self-extracting archives, that replace the functionality previously provided by MCRInstaller.zip. These files ship with MATLAB Compiler. To get information on the where you can find the MCR Installer, run the command mcrinstaller.

Note   Since you no longer create MCRInstaller.zip, buildmcr is no longer supported.

Build and Test

Build and test the standalone application or shared library as you would any application in your environment. After you create and distribute the initial application, you continue to enhance it.

Back to Top

Before You Use MATLAB Compiler

For More Information

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