Loren on the Art of MATLAB

Guest blogger Peter Webb presents another post about building applications with the MATLAB Compiler. This week's topic: understanding the types of functions that cannot be deployed and managing those that behave differently when deployed.

For an introduction to writing deployable code, please see the June 19th post.

Contents

When you're writing an application you intend to deploy with the MATLAB Compiler, you need to be aware that a subset of MATLAB's functions either cannot be deployed or behave differently when deployed.

There are two classes of non-deployable functions: functions that are not licensed for deployment; and functions that the deployment runtime (the MATLAB Common Runtime or MCR) cannot support.

Excluded Functions: Design Time Functions and GUIs

The intent of the MATLAB Compiler and the Builders is to create a robust application with predictable behavior. In part, this means that the users of the deployed application should not be able to modify it. Preventing users from modifying deployed applications has several benefits:

To prevent the modification of deployed applications, the Compiler includes only those M-files the application actually uses, encrypts the M-files (this also protects the intellectual property they contain), creates MEX authorization files, and truncates the MATLAB path. But editing M-files and modifying the MATLAB path is not the only way to change a MATLAB application. Certain MATLAB and toolbox functions can themselves change an application's behavior. For example, the MATLAB debugger can interactively modify the contents of variables and change the order in which the interpreter calls functions. Similarly, the figure property editor can modify figure callback strings. The Compiler prevents these types of modifications by refusing to compile the functions that perform them; these functions are excluded from the generated CTF archive.

In general the Compiler excludes those functions used when developing an application. Most of these design time functions fall into one of two categories: those that permit the application to change the way it works, like dbstop and propedit; and those that are complete mini-applications in and of themselves, like imtool and guide. This includes, but is not limited to:

Many of these restrictions have no workaround: debugging functions and functions which generate M-code simply cannot be deployed. There's no workaround for the debugging functions because they are builtins, and there's no effective way to debug MATLAB code using M-files. Functions which generate M-code will not work in a deployed application because they have no way of encrypting the generated M-code, which the MCR requires. You can, of course, write your own code to compensate for other types of excluded functions, but keep in mind that cloning MATLAB or toolbox functions violates your license agreement, which we don't encourage.

The Compiler creates a list of excluded functions in the output directory. This list, mccExcludedFiles.log, which is often quite long, contains the full paths to the M-files that the Compiler removed from the list produced by depfun and a short explanation for why each function cannot be deployed.

We publish a list of deployable functions; this list may change with each release of MATLAB and the deployable toolboxes.

Unsupported Functions: Differences in the Execution Environment

Certain MATLAB functions cannot be deployed because they act on objects that are not present in a deployed application. For example, since deployed applications have no command window, functions that modify the command window can't be deployed.

Use of these functions in deployed application will result in mlint warnings in the MATLAB editor and runtime warnings in the deployed application. For example, calls to help generate this text when deployed:

Warning: The HELP function cannot be used in compiled applications.

You can prevent your deployed applications from displaying warnings like this via the isdeployed function. For more details, see the previous blog posting about path management in deployed applications.

There are currently four non-deployable MATLAB functions:

The versions of these functions that issue warnings override the versions in MATLAB because of their location in toolbox/compiler/deploy which always appears first on the path used by mcc and depfun.

Functions that Work Differently

Where the differences between MATLAB and the deployed environment are not insurmountable, the MATLAB Compiler and the Builder tools offer versions of MATLAB functions that have been modified to work in deployed applications.

Eight important MATLAB functions work differently in deployed applications:

        if isdeployed
            deployprint
        else
            print
        end

You'll find the code for the deployment-specific versions of these functions in toolbox/compiler/deploy. You can control if these functions get called in deployed applications using the isdeployed function. In the unlikely event that you need to change how these functions work, you can overload them by creating a function of the same name in your top-level application directory. The Compiler will set the path of the generated application so that your M-file gets called instead of the one in toolbox/compiler/deploy.

Finally, please note that functions deployed as the main routine of a standalone executable may need to process their input arguments differently when deployed. When making a standalone executable from a MATLAB function that takes parameters, the MATLAB Compiler generates code to pass any user-supplied command line arguments to the compiled MATLAB function. However, the command line arguments are passed to the MATLAB function as strings, even if they are numeric. Therefore, any M-function serving as the entry point for a compiled MATLAB program should expect (or at least test for) string input. For example:

 function y = addten(x)
   if isstr(x)
       x = str2num(x);
   end

   y = x + 10;

Deploying Your Applications

Deploying your applications will be easier if you follow these guidelines:

Most of the information in this series of postings will eventually end up in the documentation for the MATLAB Compiler. Please comment on anything you feel was unclear, and ask any questions you think were unanswered. And feel free to contact me if you have other questions about the MATLAB Compiler or the Builders or post your thoughts here.

Get the MATLAB code

Published with MATLAB® 7.6

<pre class="code">
a = magic(3);
sum(a)
</pre>