Managing Non-Deployable Functions in a Compiled Application

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