Main Content

Write Deployable MATLAB Code

In order to package and deploy MATLAB® code, your code must follow certain guidelines to avoid errors. You can implement applications to access deployed MATLAB code using APIs generated from MATLAB functions.

Accepted File Types for Packaging

The valid and invalid file types for packaging using deployment apps are as follows:

Target ApplicationValid File TypesInvalid File Types

Standalone Application

MATLAB MEX files, MATLAB scripts, MATLAB functions, and MATLAB class files. These files must have a single entry point.

Protected function files (.p files), Java® functions, COM or .NET components, and data files.

Library Compiler

MATLAB MEX files, MATLAB functions, and MATLAB class files. These files must have a single entry point.

MATLAB scripts, protected function files (.p files), Java functions, COM or .NET components, and data files.

MATLAB Production Server

MATLAB MEX files and MATLAB functions. These files must have a single entry point.

MATLAB scripts, MATLAB class files, protected function files (.p files), Java functions, COM or .NET components, and data files. MATLAB class files can be dependent files.

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 LOADLIBRARY 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:

  1. Run the code once in MATLAB to obtain your generated function.

  2. Package the MATLAB code and include the generated function.

Tip

Another alternative to using EVAL or 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.

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. Your end users do not require any licenses to run packaged toolbox code.

Use isdeployed Functions To Execute Deployment-Specific Code Paths

The 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 your startup.m. Using ismcc and isdeployed, you specify when and what is packaged and executed.

if ~(ismcc || isdeployed)
    addpath(mypath);
end

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 addpath command) fails.

If you find you cannot avoid placing addpath calls in your MATLAB code, use ismcc and isdeployed. For details, see Use isdeployed Functions To Execute Deployment-Specific Code Paths.

Gradually Refactor Applications that Depend on Non-Deployable 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 eliminated.

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 non-deployable 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 static.

See Also

|

Related Topics