Write Deployable MATLAB Code
Packaged Applications Require Functions
Applications implemented with MATLAB® Compiler SDK™ and MATLAB Production Server™ access MATLAB code through APIs generated from MATLAB functions. All MATLAB code packaged for use in these applications must be written as a MATLAB function.
Packaged Applications Do Not Process MATLAB Files at Run Time
The compiler secures your code against unauthorized changes. Deployable MATLAB files are suspended or frozen at the time of compilation. This does not mean that you cannot deploy a flexible application—it means that you must design your application with flexibility in mind. If you want the end user to be able to choose between two different methods, for example, both methods must be available in the deployable archive.
MATLAB Runtime only works on MATLAB code that was encrypted when the deployable archive was built. Any function or process that dynamically generates new MATLAB code will not work against MATLAB Runtime.
Some MATLAB toolboxes, such as the Deep Learning Toolbox™ product, generate MATLAB code dynamically. Because MATLAB Runtime only executes encrypted MATLAB files, and the Deep Learning Toolbox generates unencrypted MATLAB files, some functions in the Deep Learning Toolbox cannot be deployed.
Similarly, functions that need to examine the contents of a MATLAB function file cannot be deployed.
HELP, for example, is
dynamic and not available in deployed mode. You can use
in deployed mode if you provide it with a MATLAB function prototype.
Instead of compiling the function that generates the MATLAB code and attempting to deploy it, perform the following tasks:
Run the code once in MATLAB to obtain your generated function.
Package the MATLAB code, including the generated function.
Another alternative to using
FEVAL is using anonymous function handles.
If you require the ability to create MATLAB code for dynamic run-time processing, your end users must have an installed copy of MATLAB.
Do Not Rely on Changing Directory or Path to Control the Execution of MATLAB Files
In general, good programming practices advise against redirecting a program search path dynamically within the code. Many developers are prone to this behavior since it mimics the actions they usually perform on the command line. However, this can lead to problems when deploying code.
For example, in a deployed application, the MATLAB and Java® paths are fixed and cannot change. Therefore, any attempt to change these
paths (using the
cd command or the
If you find you cannot avoid placing
addpath calls in your
MATLAB code, use
isdeployed. See Use isdeployed Functions To Execute Deployment-Specific Code Paths for details.
Use isdeployed Functions To Execute Deployment-Specific Code Paths
isdeployed function allows you to specify which portion of
your MATLAB code is deployable, and which is not. Such specification minimizes your
compilation errors and helps create more efficient, maintainable code.
For example, you find it unavoidable to use
addpath when writing
isdeployed, you specify when and what is packaged and
if ~(ismcc || isdeployed) addpath(mypath); end
Gradually Refactor Applications That Depend on Noncompilable Functions
Over time, refactor, streamline, and modularize MATLAB code containing non-compilable or non-deployable functions that use
isdeployed. Your eventual goal is “graceful
degradation” of non-deployable code. In other words, the code must present the
end user with as few obstacles to deployment as possible until it is practically
Partition your code into design-time and run-time code sections:
Design-time code is code that is currently evolving. Almost all code goes through a phase of perpetual rewriting, debugging, and optimization. In some toolboxes, such as the Deep Learning Toolbox product, the code goes through a period of self-training as it reacts to various data permutations and patterns. Such code is almost never designed to be deployed.
Run-time code, on the other hand, has solidified or become stable—it is in a finished state and is ready to be deployed by the end user.
Consider creating a separate directory for code that is not meant to be deployed or for code that calls undeployable code.
Do Not Create or Use Nonconstant Static State Variables
Avoid using the following:
Global variables in MATLAB code
Static variables in MEX-files
Static variables in Java code
The state of these variables is persistent and shared with everything in the process.
When deploying applications, using persistent variables can cause problems because the MATLAB Runtime process runs in a single thread. You cannot load more than one of these non-constant, static variables into the same process. In addition, these static variables do not work well in multithreaded applications.
When programming against packaged MATLAB code, you should be aware that an instance of MATLAB Runtime is created for each instance of a new class. If the same class is instantiated again using a different variable name, it is attached to the MATLAB Runtime instance created by the previous instance of the same class. In short, if an assembly contains n unique classes, there will be maximum of n instances of MATLAB Runtime created, each corresponding to one or more instances of one of the classes.
If you must use static variables, bind them to instances. For example, defining
instance variables in a Java class is preferable to defining the variable as
Get Proper Licenses for Toolbox Functionality You Want to Deploy
You must have a valid MathWorks® license for toolboxes you use to create deployable MATLAB code.