Store 
Product Support
1620 - How to Troubleshoot Compilation Errors when using the MATLAB Compiler?
Table of Contents
- Introduction and purpose of the Tech Note
- What are some of the common issues faced?
- Where are you in the compilation process?
- Useful debugging tools and solutions
Introduction and purpose of the tech note
The MATLAB Compiler lets you convert your own MATLAB programs into self-contained applications and software components and share them with end users who do not have a MATLAB installation. The Compiler takes MATLAB applications (M-files, MEX-files, and other MATLAB executable code) as input and generates redistributable stand-alone applications or shared libraries. The resulting applications and components are platform specific.
This tech note addresses some of the common issues faced with creating and using applications or shared libraries with the MATLAB Compiler. This tech note is a collection of best practices used by MathWorks support engineers as well as information on some tools that are useful in troubleshooting deployment issues.
Note that the suggestions given in this tech note are in addition to the debugging strategies given in the Troubleshooting sections
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f3-956032.html (for MBUILD) and
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f3-961153.html (for MATLAB Compiler)
For general suggestions on debugging your M-files, refer to http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_env/edit_de4.html as well as http://www.mathworks.com/support/tech-notes/1200/1207.html
What are some of the common issues faced?
Some of the most common issues faced with MATLAB Compiler generated stand-alone executables or shared libraries are:
- Compilation fails with an error message
This could indicate a failure during any one of the internal steps involved in producing the final output
- Compilation succeeds but the application does not execute because required DLLs are not found
All shared libraries required for your stand-alone executable or shared library are contained in the MATLAB Component Runtime (MCR). Installing the MCR is required for any of the deployment targets.
- Compilation succeeds, and the resultant file starts to execute but then produces errors and/or generates a crash dump
- The compiled program executes on the machine where it was compiled but not on other machines
- The compiled program executes on some machines and not others
Where are you in the compilation process?
Building stand-alone executables
The typical work flow for building a stand-alone executable is to compile your M-code on a development machine, test the resulting executable on that machine, and deploy the executable and MCR to a test or customer machine without MATLAB.
The compilation process performs dependency analysis on your M-code, creates an encrypted archive of your code and required toolbox code, generates wrapper code, and compiles the wrapper code into an executable. If your application fails to build an executable, the following questions may help you isolate the problem:
What system compiler did you select with mbuild -setup?
The first step in using the MATLAB Compiler is to select a system compiler which is used to generate the final executable from the generated wrapper code.
Is it a supported compiler?
Refer to the list of supported compilers.
Are there error messages at compile time?
A list of common errors appears in the Troubleshooting section of the MATLAB Compiler documentation.
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f3-961153.html
Did you compile with the verbose flag?
Compilation can fail in MATLAB because of errors encountered by the system compiler when the generated wrapper code is compiled into an executable. Additional errors and warnings are printed when you use the verbose flag like:
mcc -mv myApplication.m
In this example, -m tells MATLAB Compiler to create a standalone application and -v tells MATLAB Compiler and other processors to display messages about the process.
Are you compiling inside MATLAB or outside?
MCC can be invoked from the operating system command line or from the MATLAB command prompt. When you run MCC inside the MATLAB environment, MATLAB will modify environment variables in its environment as necessary so that MCC will run. Issues with PATH, LD_LIBRARY_PATH, or other environment variables seen at the operating system command line are often not seen at the MATLAB prompt.
The environment that MATLAB uses for MCC can be listed at the MATLAB prompt. For example:
>>!set
Will list the environment on Windows platforms.
>>!printenv
Will list the environment on most unix platforms.
Using this path should allow you to use MCC from the operating system command line.
Does a simple helloworld compile successfully?
Sometimes applications won't compile because of MEX, toolbox or other dependencies. Compiling a helloworld application can determine if the Compiler is correctly set up to produce any executable. For example, try compiling:
function helloworld
disp('hello world')
with:
>>mcc -mv helloworld.m
Have you tried to compile any of the examples in the MATLAB Compiler help?
The source code for all examples is provided with MATLAB Compiler and is located in <matlabroot>\extern\examples\compiler, <matlabroot> being the root directory of your MATLAB installation.
Does your code compile with the LCC compiler?
The LCC compiler is a free compiler provided with MATLAB on Windows. If there are installation or path problems with other system compilers, it may be possible to compile the application with LCC.
Did the M-code used to compile?
The three most common reasons for M-code to stop compiling are
- An upgrade to MATLAB without running mbuild -setup
Running mbuild -setup is required after any upgrade to the MATLAB Compiler.
- A change in the selection of the system compiler
It is possible to inadvertently change the system compiler for versions of MATLAB that store preferences in a common directory. For example, MATLAB 7.0.1 (R14SP1) and MATLAB 7.0.4 (R14SP2) store their preferences in the same directory. Changing the system compiler in R14SP1 will also change the system compiler in R14SP2.
- An upgrade to MATLAB that didn't include an upgrade to the MATLAB Compiler.
MATLAB and the MATLAB Compiler are required to be from the same release. It is possible to see conflicts in installations where the MATLAB installation is local and the Compiler installation is on a network or vice versa.
Testing stand-alone executables
Once you have successfully compiled your application, the next steps are to test it on the development machine and deploy it on a target machine. Typically the target machine does not have a MATLAB installation and requires that the MATLAB Component Runtime (MCR) be installed.
A distribution includes all of the files that are required by your application to run, which include the executable, CTF-archive and the MCR.On Windows this looks like:
<application-name>.exe
<application-name>.ctf
MCRInstaller.exe
On unix/Mac:
<application-name>
<application-name>.ctf
MCRInstaller.zip
MCRInstaller.zip is created by executing BUILDMCR at the MATLAB command prompt.
Test the application on the development machine by running the application against the MCR shipped with the MATLAB Compiler. This will verify that library dependencies are correct, that the CTF-archive can be extracted and that all M-code, MEX and support files required by the application has been included in the archive. If you encounter errors testing your application, these questions may help you isolate the problem:
Are you able to execute the application from within MATLAB?
On the development machine, you can test your application's execution by issuing '!<application-name>' at the MATLAB command prompt. If your application executes within MATLAB but not from outside, this could indicate an issue with the system PATH variable. For more information, see:
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f12-999353.html#f12-999320
Does the application begin execution and result in MATLAB or other errors?
Ensure that you have included all necessary files when compiling your application. Functions that are called from within your main M-file are automatically included by the MATLAB Compiler; 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 will need to be added to the archive with the '-a' switch. For more information, see:
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f5-50432.html
There is a limitation on the functionality of MATLAB and its toolboxes that can be compiled. Check to see that the functions used in your application's M-files do not fall under the following lists:
http://www.mathworks.com/products/compiler/compiler_support.html
http://www.mathworks.com/products/ineligible_programs/
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f5-29815.html
Check the file 'mccExcludedFiles.log' on the development machine. This file lists all functions called from your application that cannot be compiled.
Does the application emit a warning like "MATLAB file may be corrupt"?
The Troubleshooting section of the MATLAB Compiler documentation addresses some techniques for diagnosing this warning: http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f3-961153.html
Do you have multiple versions of MATLAB installed?
Executables generated by the MATLAB Compiler 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. Ensure that the '<matlabroot>/bin/win32' of the version of MATLAB that you are compiling in appears ahead of '<matlabroot>/bin/win32' of other versions of MATLAB installed on the PATH environment variable on your machine. On UNIX machines, you can compare the outputs of '!printenv' at the MATLAB command prompt and 'printenv' at the shell prompt. Using this path should allow you to use MCC from the operating system command line.
Deploying stand-alone executables
Now that the application is working on the test machine, focus shifts to end-user deployment. The end-users of your application need to execute MCRInstaller once in order to install the MATLAB Component Runtime (MCR) on their machine. The MCR includes a set of shared libraries that provides support for all features of MATLAB.
Did you install the MCR?
All shared libraries required for your stand-alone executable or shared library are contained in the MCR. Installing the MCR is required for any of the deployment targets.
If on Unix or Mac, did you update the dynamic library path after installing the MCR?
For information on installing the MCR on a deployment machine, refer to http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f12-999353.html#f12-999320
Do you receive an error message about a missing DLL?
Error messages indicating missing DLLs of the form 'mclmcrrt7x.dll' or 'mclmcrrt7x.so' are generally caused by incorrect installation of the MCR. It is also possible that the MCR is installed correctly, but that the PATH, LD_LIBRARY_PATH or DYLD_LIBRARY_PATH variables are set incorrectly. For information on installing the MCR on a deployment machine, refer to http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f12-999353.html#f12-999320
It is important to note that these problems should not be solved by moving libraries or other files within the MCR directory structure. The runtime system is designed to accommodate different MCR versions operating on the same machine. The directory structure is an important part of this feature.
Do you have write access to the directory the application is installed in?
The first operation attempted by a compiled application is extraction of the CTF- archive. If the archive is not extracted, the application cannot access the compiled M-code and the application fails. If the application has write access to the installation directory, a subdirectory named <application-name>_mcr is created the first time the application is run. Once this subdirectory is created, the application no longer needs write access for subsequent executions.
Are you executing a newer version of your application?
When deploying a newer version of an executable, both the executable and CTF-files need to be redeployed. The CTF-file is keyed to a specific compilation session. Every time an application is re-compiled, a new, matched CTF-file is created. As above, write access is required to expand the new CTF-file. Deleting the existing <application-name>_mcr directory and running the new executable will verify that the application can expand the new CTF.
Building shared libraries
Another use of the MATLAB Compiler is to build C or C++ shared libraries (DLLs on Windows) from a set of M-files. You can then write C or C++ programs that can call the functions in these libraries.
The typical workflow for building a shared library is to compile your M-code on a development machine, write a C/C++ driver application, build an executable from the driver code, test the resulting executable on that machine, and deploy the executable and MCR to a test or customer machine without MATLAB.
Compiling a shared library and driver application
Compiling a shared library is very similar to compiling an executable. The command line differs:
mcc -B csharedlib:hellolib hello.m
OR
mcc -B cpplib:hellolib hello.m
The process of troubleshooting build errors for shared libraries is generally the same as troubleshooting build errors for stand-alone applications.
Building your driver application
Once you have compiled a shared library, the next step is to create a driver application that initializes and terminates the shared library as well as invokes method calls. This driver application can be compiled and linked with your shared library with the MBUILD command. For example,
mbuild helloapp.c hellolib.lib
OR
mbuild helloapp.cpp hellolib.lib
For examples of the correct method to access the shared library, refer to http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f2-1000836.html or http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f2-1009231.html
Note that the only header file that needs to be included in your driver application is the one generated by your MCC command (hellolib.h, in the above example)
Are you receiving errors when trying to compile the shared library?
Errors at compile-time could indicate issues with either MCC or MBUILD. For troubleshooting MCC issues, refer to the section above on compile-time issues.
It is recommended that your driver application be compiled and linked using MBUILD. MBUILD can be executed with the '-v' switch to provide additional information on the compilation process. If you receive errors at this stage, ensure that you are using the correct header files and/or libraries produced by MCC, in your C or C++ driver. For example,
mcc -B csharedlib:hellolib hello.m
produces hellolib.h, which is required to be included in your C/ C++ driver, and hellolib.lib or hellolib.so, which is required on the MBUILD command line.
Are you using the MBUILD command to compile your driver application?
The MathWorks recommends and supports using MBUILD to compile your driver application. MBUILD is designed and tested to correctly build driver applications. It will ensure that all MATLAB header files are found by the C/C++ compiler, and that all necessary libraries are specified and found by the linker.
Are you trying to compile your driver application using Microsoft Visual Studio or another IDE?
If using an IDE, in addition to linking to the generated export library, you need to include an additional dependency to 'mclmcrrt.lib'. This library is provided for all supported third-party compilers in <matlabroot>\extern\lib\<vendor-name>.
Are you importing the correct versions of the import libraries?
If you have multiple versions of MATLAB installed on your machine, it is possible that an older or incompatible version of the library is referenced. Ensure that the only MATLAB library that you are linking to is 'mclmcrrt.lib' and that it is referenced from the appropriate vendor directory. Do not reference libraries like 'libmx' or 'libut'. Also verify that your library include path references the version of MATLAB that your shared library was built with.
Are you able to compile the matrixdriver example?
This example can be found in the MATLAB documentation by opening Help, navigating to the Search tab and typing "C shared library example" or "C++ shared library example". Typically, if you are unable to compile the examples given in the documentation, it is indicative of an issue with the installation of MATLAB or your system compiler.
Testing a shared library and driver application
Did you install the MCR?
All shared libraries required for your stand-alone executable or shared library are contained in the MATLAB Component Runtime (MCR). Installing the MCR is required for any of the deployment targets.
Do you receive an error message about a missing DLL?
Error messages indicating missing DLLs of the form 'mclmcrrt7x.dll' or 'mclmcrrt7x.so' are generally caused by incorrect installation of the MCR. It is also possible that the MCR is installed correctly, but that the PATH, LD_LIBRARY_PATH or DYLD_LIBRARY_PATH variables are set incorrectly. For information on installing the MCR on a deployment machine, refer to http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f12-999353.html#f12-999320
Are you receiving errors when trying to run the shared library application?
Calling MATLAB Compiler generated shared libraries requires correct initialization and termination in addition to library calls themselves. For information on calling shared libraries, see
http://www.mathworks.com/access/helpdesk/help/toolbox/compiler/f2-1008484.html
Some key points to consider to avoid errors at run-time are
- Ensure that the calls to mclInitializeApplication and <libname>Initialize are successful. The first function enables construction of MCR instances, and the second creates the MCR 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 prior to initialization results in undefined behavior.
- Do not re-initialize (that is, call mclInitializeApplication) after terminating it with mclTerminateApplication. The mclInitializeApplication and <libname>Initialize functions must each be called once and only once.
- Ensure that you do not have any library calls after mclTerminateApplication.
- Also ensure that you are using the correct syntax to call the library and its functions.
Useful debugging tools and Solutions
http://www.mathworks.com/support/solutions/data/1-2RQL4L.html?solution=1-2RQL4L
