Deploying Standalone Applications

http://blogs.mathworks.com/loren/2010/11/18/deploying-standalone-applications/

Guest blogger Peter Webb returns with another in an occasional series of postings about application deployment.

Contents

• Application Deployment
• Creating a Standalone Executable
• How Can I Help?

In the first four articles in this series, I addressed some of the differences between MATLAB and deployed runtime environment. With the next set, I'll be talking more about the features of our deployment tools, and how you use them to create deployable applications. Of necessity, I'm limiting myself to discussing the technical computing tools because that's where my expertise lies. Even though the term ''application deployment'' applies to control design tools like Real Time Workshop and Embedded MATLAB, I won't post about those tools here. You can read about code generation for control design applications in Seth Popinchalk's Seth on Simulink blog. By concentrating on the deployment process, I hope to complement the other articles in Loren's blog -- she'll show you how to write interesting MATLAB programs, and I'll help you turn them into deployable applications.

I'd like to to host a conversation here: a real two-way exchange of ideas. I'll post articles that will make it easier, and perhaps even more fun, to use the MATLAB Compiler and the Builders. I hope you'll respond with questions where you have them, praise where it's merited, and especially complaints and suggestions -- your feedback here will help us improve the tools you use.

In this post, I'm going to briefly introduce the most important application deployment concepts, and then demonstrate how to use the MATLAB Compiler to turn an MATLAB function into a standalone executable.

Application Deployment

Our deployment tools all focus on the same basic process: transforming a collection of functions written in MATLAB into an application or library that can be used outside of MATLAB.

The MATLAB Compiler and Builders allow you to deploy MATLAB applications as:

• Stand-alone executables
• C or C++ libraries
• Microsoft .NET or COM components (local or remote)
• Java classes
• Microsoft Excel add-ins

A deployed application consists of a collection of MATLAB-based functions and data packaged for a particular target environment. For example, the MATLAB Compiler can package MATLAB-based functions into C++ shared libraries so they can be called in any programming environment that supports C++ functions.

All of our tools follow the same four step process to create a deployed application:

• Examine the application to determine which MATLAB-based files to ship.
• Generate interface (wrapper) functions for the target environment.
• Invoke a target environment specific build tool (like a C++ or Java compiler) to create an executable or software component.
• Assemble the MATLAB-based files and the binary generated in step 3 into one or more files for distribution.

The deployment tools create an application you can install on a machine without MATLAB. But in order to run, the application requires a runtime library (like Java programs require a Java installation). Our runtime library is called the MATLAB Compiler Runtime, or more commonly, the MCR. An installer for the MCR ships with the MATLAB Compiler and Builders. You can redistribute this installer to your end users.

Creating a Standalone Executable

A standalone executable is a complete program that you can run from the Unix command line or Microsoft Windows DOS command prompt. Standalone executables are a convenient way to provide turn-key MATLAB-based solutions to your colleagues or end users.

Save this MATLAB function as helloworld.m. Before compiling it, test it in MATLAB. It should produce a globe with the continents visible and the view centered on the mid-Atlantic trench.

function helloworld
% HELLOWORLD Display the globe and a welcome message.

    % Load the topographical data for the globe
    load('topo.mat', 'topo', 'topomap1');

    % Create a unit sphere with 50 facets. This sphere is the Earth.
    [x,y,z] = sphere(50);

    % Establish initial viewing and lighting parameters. Use Phong shading
    % and texture mapping to wrap the topo map data around the sphere.

    props.FaceColor= 'texture';
    props.EdgeColor = 'none';
    props.FaceLighting = 'phong';
    props.CData = topo;

    % Set the viewpoint to look at the Atlantic Ocean.
    view(-130, 10);

    % Draw the sphere, with the topo data texture mapped to the surface.
    s=surface(x,y,z,props);
    set(gcf, 'Color', 'white');  % White background
    axis square
    axis off
    axis equal

    title('Hello, World.', 'FontSize', 14, 'FontWeight', 'Bold');
end

Build this function into a standalone application with the MATLAB Compiler:

  mcc -mv helloworld.m -a topo.mat

Here, I've specified three groups of arguments to the mcc command:

• -mv: -m means create a ''main'' program, a standalone executable. -v requests verbose output.
• helloworld.m: The name of the MATLAB function to compile. The generated executable takes its name from the name of the first MATLAB function specified on the command line.
• -a topo.mat: -a stands for ''additional file''; it is typically used to add data files to the application.

This mcc command will create a standalone executable called helloworld on UNIX systems, helloworld.exe on PCs running Microsoft Windows.

In order to run the executable, the operating system needs to be able to find the MCR. You need to put the MCR'sruntime/<architecture> directory on the system's library search path. On Windows, you add it to the PATH environment variable. On Unix, you add it to LD_LIBRARY_PATH (except on the MacIntosh, which uses DYLD_LIBRARY_PATH). To run the executable locally (on the machine where you created it), use MATLAB's runtime/<architecture> directory. If the environment variable MATLAB_ROOT indicates the root of your MATLAB installation, add the runtime directory to the library search path with one of the following commands

Linux 32-bit:
  % setenv LD_LIBRARY_PATH $MATLAB_ROOT/runtime/glnx86

Windows:
  c:\Work> set %PATH%;%MATLAB_ROOT%\runtime\win32

Then, run the application:

UNIX:
  % helloworld

Windows:
  c:\Work> helloworld.exe

You should see a single window displaying a map of the world.

How Can I Help?

Writing applications for deployment requires a new set of skills. There are differences between the MATLAB interactive environment and the DOS and Unix command lines that I can't (and don't want to) erase. But I do want to make the deployment process as painless as possible. Let me know how we're doing. Tell me what we've done right, and how we could improve. I've got a long list of topics lined up for future postings, but I'm very interested in hearing what you'd like to know. Reply to this posting and let's get started.