Interpreting the Code Analyzer’s Deployment Messages
Guest blogger Peter Webb returns with another in an occasional series of postings about application deployment.
Contents
Previously, Jacob introduced the MATLAB code analyzer, mlint, which helps you write better code by notifying you of questionable constructs and opportunities for performance enhancement. The code analyzer's messages are organized into categories, one of which is deployment. The deployment category contains 16 messages. Deployment messages are off by default; you activate them via code analyzer preferences. To help you make the best possible use of the feedback provided by the code analyzer, I'll use this week's posting to provide an interpretation of each of its deployment messages. In the sections below, I quote code analyzer warning messages in italics.
Unsupported MATLAB Features
Some features of MATLAB do not work in deployed applications because of differences between the deployed environment and the MATLAB interactive environment. The MATLAB code analyzer warns about five such features:
- MCC allows writing .m files, but they cannot be executed by the deployed application.
A MATLAB function may create another MATLAB function and then call it. For example, the Deep Learning Toolbox uses this technique to train neural networks. A deployed application may create MATLAB functions on disk, but it cannot execute them. Deployed applications only execute encrypted MATLAB functions and only MATLAB Compiler can create encrypted functions for deployment (MATLAB Compiler itself cannot be deployed).
Functions that create and then call MATLAB functions on disk cannot be deployed. If your code needs to create simple functions at runtime, you may be able to use anonymous functions instead of creating new MATLAB function files.
- MCC does not allow C++ files to be read directly using LOADLIBRARY.
When processing a C++ header file, loadlibrary creates new MATLAB function files. As discussed above, creating and then calling new MATLAB functions is a non-deployable feature. As a result loadlibrary cannot be used with C++ headers in deployed applications. However, you can deploy applications that use MATLAB function prototypes with loadlibrary. (See the documentation for MATLAB Compiler; search for "loadlibrary".)
- MCC requires the program to assign a value to output argument
name 
.
When MATLAB Compiler processes a MATLAB function with outputs, it creates a wrapper function with output parameters. The generated code requires that the output variables have valid MATLAB values when the function returns. MATLAB functions that do not assign values to their outputs are likely to cause the program to crash.
- MCC use of absolute file names is likely to fail.
- MCC use of toolbox folder file names is likely to fail.
Deployed applications have a different view of the file system than applications running in interactive MATLAB. A deployed application has a limited MATLAB path, and a different notion of the MATLAB root directory. A full discussion of this issue is beyond the scope of this post but, generally speaking, it is best to use relative paths instead of absolute paths, and to avoid references to files in a MATLAB installation. If you need access to a file in MATLAB in a deployed application, include the file in the application with the -a switch when creating it.
Unsupported Functions
MCC does not permit the function name function.
Certain MATLAB functions cannot be deployed because they rely on features of MATLAB that the deployed environment does not support. Avoid using these functions in code you intend to deploy, or use the isdeployed function to ensure your compiled program does not call these functions. The code analyzer issues warnings about five unsupported functions:
- addpath: The path a deployed application uses to look for executable functions is fixed when the deployed application is created, and cannot be changed.
- help: The help database is too big to put in a deployed application. Besides, users of your application should not need help with MATLAB functions, since your application encapsulates them.
- keyboard: The implementation of this function relies on the MATLAB desktop environment, and deployed applications do not have access to the MATLAB desktop.
- printdlg: On Microsoft Windows platforms, you must use deployprint instead of print. As a result, certain forms of printdlg cannot be deployed.
- savepath: Deployed applications do not support saving and loading the MATLAB path. The MATLAB path is embedded into a deployed application when it is created, and the path can't be changed (so there's no point in saving it).
DEPLOYPRINT
MCC prefers Windows applications to call DEPLOYPRINT instead of PRINT, but use PRINT when printing to a file.
On Microsoft Windows platforms, a deployed application generates printed output by creating a JPEG file and then sending that file to printer. This mechanism is very different from the way MATLAB prints on Windows platforms. Deployed applications must use the deployprint function on Microsoft Windows platforms.
WEBFIGURE
- MCC requires that the first argument of WEBFIGURE not come from FIGURE(n).
- MCC requires that the first argument of WEBFIGURE not come from FIGURE(n) (line number).
Deployed applications use the webfigure function to display graphics inside of a web browser. webfigure takes a single argument: the handle of a figure. Certain details of the implementation require that the figure's numerical ID be automatically assigned by Handle Graphics rather than specified by the user. The code analyzer issues this webfigure warning when it detects code manually specifying figure IDs. For example:
f_bad = figure(1); wf = webfigure(f_bad); % Warning generated
f_ok = figure; wf = webfigure(f_ok); % No warning generated
Functions with Unexpected Behavior
MCC use of the function name function is problematic.
The code analyzer generates warnings for the first two of these functions because they manipulate or rely on the program's view of the file system, which is is very different in a deployed application. The third warning, about deployprint, only appears on UNIX systems. Deployed applications on UNIX systems print using print instead of deployprint.
- cd: Changing the current directory in a deployed application does not affect the order in which the application will search directories for executable functions. In fact, the current directory is never searched for executable functions.
- matlabroot: In a deployed application, matlabroot refers to the root of the installed MCR against which the application is running. An MCR installation is not a full MATLAB installation; applications cannot rely on being able to find all of MATLAB's functions or data files in an MCR installation.
- deployprint: As noted above, applications deployed to UNIX systems use print instead of deployprint.
How do you use the code analyzer? Do these error messages make sense? Would you like to see the code analyzer integrated with deploytool or mcc? Let us know here.
- Category:
- Deployment
