Testing Failures

After you have successfully compiled your application, the next step is to test it on a development machine and deploy it on a target machine. The target machine requires MATLAB^® Runtime to be installed. An installer packaged using compiler.package.installer or a deploytool app includes all of the files that are required by your application to run, which include the executable, deployable archive, and MATLAB Runtime.

For information on distribution contents for specific application types and platforms, see Distribute MATLAB Compiler SDK Files to Application Developers.

Test the application on the development machine by running the application against MATLAB Runtime shipped with MATLAB Compiler SDK™. This verifies that library dependencies are correct, that the deployable archive can be extracted, and that all MATLAB code, MEX—files, and support files required by the application have been included in the archive. If you encounter errors testing your application, the following questions may help you isolate the problem.

 Are you able to execute the application from MATLAB?

On the development machine, test your application's execution by issuing !application-name at the MATLAB prompt. If your application executes within MATLAB but not from outside, this can indicate an issue with the one of the system variables:

• PATH

• LD_LIBRARY_PATH

• DYLD_LIBRARY_PATH

For more information on setting the system library path, see Set MATLAB Runtime Path for Deployment.

 Does the application begin execution and result in MATLAB or other errors?

Ensure that you included all necessary files when compiling your application (see the readme.txt file generated with your compilation for more details).

Functions that are called from your main MATLAB file are automatically included by MATLAB Compiler SDK as are functions included using the %#function pragma. However, functions that are not explicitly called, for example through EVAL, need to be included at compilation using the -a switch of the mcc command. Also, any support files like .mat, .txt, or .html files need to be added to the archive with the -a switch. For more information, see Include and Access Files in Packaged Applications.

There is a limitation on the functionality of MATLAB and associated toolboxes that can be compiled. Check the documentation to see that the functions used in your application's MATLAB files are valid. Check the file mccExcludedFiles.log on the development machine. This file lists all functions called from your application that cannot be compiled.

 Do you have multiple MATLAB versions installed?

Executables generated using MATLAB Compiler SDK components are designed to run in an environment where multiple versions of MATLAB are installed. Some older versions of MATLAB may not be fully compatible with this architecture.

On Windows, ensure that the matlabroot\runtime\win64 of the version of MATLAB in which you are compiling appears ahead of matlabroot\runtime\win64 of other versions of MATLAB installed on the PATH environment variable on your machine.

Similarly, on UNIX^®, ensure that the dynamic library paths (LD_LIBRARY_PATH on Linux^®) match. Do this by comparing the outputs of !printenv at the MATLAB prompt and printenv at the shell prompt. Using this path allows you to use mcc from the operating system command line.

 If you are testing a shared library and application, did you install MATLAB Runtime?

All runtime libraries required for any deployment target are contained in MATLAB Runtime. For information on installing MATLAB Runtime, see Download and Install MATLAB Runtime.

 Do you receive an error message about a missing DLL?

Error messages indicating missing DLLs such as mclmcrrtX_XX.dll or mclmcrrtX_XX.so are generally caused by an incorrect installation of MATLAB Runtime. For information on installing MATLAB Runtime, see Download and Install MATLAB Runtime.

It is also possible that MATLAB Runtime is installed correctly, but the PATH,LD_LIBRARY_PATH, or DYLD_LIBRARY_PATH variable is set incorrectly. For information on setting environment variables, see Set MATLAB Runtime Path for Deployment.

Caution

Do not solve these problems by moving libraries or other files within the MATLAB Runtime folder structure. The MATLAB Runtime system is designed to accommodate different MATLAB Runtime versions operating on the same machine. The folder structure is an important part of this feature.

 Are you receiving errors when trying to run the shared library application?

Calling MATLAB Compiler SDK generated shared libraries requires correct initialization and termination in addition to library calls themselves. For information on calling shared libraries, see Call MATLAB Compiler SDK API Functions from C/C++.

Some key points to consider to avoid errors at run time:

• Ensure that the calls to mclinitializeApplication and libnameInitialize are successful. The first function enables construction of MATLAB Runtime instances. The second creates the MATLAB Runtime instance required by the library named libname. If these calls are not successful, your application will not execute.

• Do not use any mw- or mx-functions before calling mclinitializeApplication. This includes static and global variables that are initialized at program start. Referencing mw- or mx-functions before initialization results in undefined behavior.

• Do not re-initialize (call mclinitializeApplication) after terminating it with mclTerminateApplication. The mclinitializeApplication andlibnameInitialize functions should be called only once.

• Ensure that you do not have any library calls after mclTerminateApplication.

• Ensure that you are using the correct syntax to call the library and its functions.

 Does your system’s graphics card support the graphics application?

In situations where the existing hardware graphics card does not support the graphics application, use software OpenGL^®. OpenGL libraries are visible for an application by appending matlabroot/sys/opengl/lib/arch to the library path. For example, on Linux, enter the following in a Bash shell:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:matlabroot/sys/opengl/lib/glnxa64

For more information on setting environment variables, see Set MATLAB Runtime Path for Deployment.

 Is OpenGL properly installed on your system?

When searching for OpenGL libraries, MATLAB Runtime first looks on the system library path. If OpenGL is not found there, it uses the LD_LIBRARY_PATH environment variable to locate the libraries. If you are getting failures due to the OpenGL libraries not being found, you can append the location of the OpenGL libraries to the LD_LIBRARY_PATH environment variable. For example, on Linux, enter the following in a Bash shell:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:matlabroot/sys/opengl/lib/glnxa64

For more information on setting environment variables, see Set MATLAB Runtime Path for Deployment.