MATLAB®

Compiling and Linking MATLAB^® Engine Programs

Write Your Application

Write your application in C or Fortran using any of the engine routines to perform computations in MATLAB^®. For more information, see Using the MATLAB^® Engine to Call MATLAB^® Software from C and Fortran Programs and Examples of Calling Engine Functions.

Back to Top

Check Required Libraries and Files

MATLAB requires the following files for building any engine application:

• Third-Party Libraries

• Library Files Required by libeng

• Unicode^® Data Files

Third-Party Libraries

Verify that the required libraries are installed. Use the following table to identify the path and library filename. Replace libfile with each of these filenames:

libeng
libmx

Library Files Required by libeng

The libeng library requires additional third-party library files. MATLAB uses these libraries to support Unicode^® character encoding and data compression in MAT-files.

These library files must reside in the same directory as libmx. You can determine what most of these libraries are using the platform-specific commands shown here.

On a Windows system, download the Dependency Walker utility from the following Web site:

http://www.dependencywalker.com/

Drag and drop the libeng.dll file into the Depends window.

Unicode^® Data Files

Verify that the appropriate Unicode data file is installed. Systems that order bytes in a big-endian manner use icudt32b.dat, and those that have little-endian ordering use icudt32l.dat.

Note    If you need to manipulate Unicode text directly in your application, the latest version of International Components for Unicode (ICU) is available online from the IBM Corporation Web site at http://icu.sourceforge.net/download.

Back to Top

Build the Application

Use the mex script to compile and link engine programs. mex has a set of switches you can use to modify the compile and link stages. The table MEX Script Switches lists the available switches and their uses.

MEX Options File

MATLAB supplies an options file to facilitate building MEX applications. This file contains compiler-specific flags that correspond to the general compile, prelink, and link steps required on your system. If you want to customize the build process, you can modify this file.

Different options files are provided for UNIX^® and Windows operating systems.

On Windows systems, the options file depends on which compiler you use. The name of the options file is prefixed with a string representing the compiler and compiler version it is used with.

For example, to locate the options file on a Windows 32-bit system, type:

dir([matlabroot '\bin\win32\mexopts\*engmatopts.bat'])

If you need to modify the options file for your particular compiler, use the mex command with the -v switch to view the current compiler and linker settings, and then make the appropriate changes in the options file.

Build the Application

To build your engine application, use the mex script with the options filename and the name of your MEX-file.

UNIX^® Operating Systems.   Enter the following command, where mexfilename is the name of your C or Fortran program. Enclose mexfilename in single quotation marks.

mex('-f', [matlabroot '/bin/engopts.sh'], mexfilename);

Alternatively, copy the options file to your current working directory, and then enter the following command:

mex -f engopts.sh mexfilename

Windows^® Operating Systems.   Enter the following command, where mexfilename is the name of your C or Fortran program. Enclose mexfilename in single quotation marks. This example uses the Lcc compiler. Be sure to use the appropriate options file for your compiler.

mex('-f', [matlabroot ...
   '\bin\win32\mexopts\lccengmatopts.bat'], mexfilename);

Alternatively, copy the options file to your current working directory, and then enter the following command:

mex -f lccengmatopts.bat mexfilename

Back to Top

Set Run-Time Library Path

At run-time, you need to tell the system where the API shared libraries reside.

UNIX^® Operating Systems

Set the library path as follows for the C and Bourne shells. In the commands shown, replace the terms envvar and pathspec with the appropriate values from the table that follows.

To set the library path in the C shell, type:

setenv envvar pathspec

In the Bourne shell, type:

envvar = pathspec:envvar export envvar

Here is an example for a Solaris system for the C shell:

setenv LD_LIBRARY_PATH matlabroot/bin/sol64:matlabroot/sys/os/sol64

and for the Bourne shell:

LD_LIBRARY_PATH=matlabroot/bin/sol64:matlabroot/sys/os/sol64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH 

Place these commands in a startup script such as ~/.cshrc for the C shell or ~/.profile for the Bourne shell.

Windows^® Operating Systems

Set the Path environment variable to the path string returned by MATLAB in response to the following expression:

[matlabroot '\bin\win32']

or:

[matlabroot '\bin\win64']

To set an environment variable in a Windows system, select Start > Settings > Control Panel > System. The System Properties dialog box is displayed. Click the Advanced tab, and then the Environment Variables button.

In the System variables panel scroll down until you find the Path variable. Click this variable to highlight it, and then click the Edit button to open the Edit System Variable dialog box. At the end of the path string, enter a semicolon and then the path string returned by evaluating the expression shown above in MATLAB. Click OK in the Edit System Variable dialog box, and in all remaining dialog boxes.

Back to Top

Select MATLAB^® Version

If you have multiple versions of MATLAB installed on your Windows operating system, the version you use to build your engine applications must be the first listed in your system PATH environment variable. If the MATLAB version you use to build the application is not the first listed on the path, you may see the following error:

Can't start MATLAB engine

For information about accessing the PATH environment variable through the Windows Control Panel, see the Windows^® Operating Systems topic in Set Run-Time Library Path.

Back to Top

Register MATLAB^® Software as a COM Server

To run this program on a Windows operating system, you need to have MATLAB registered as a COM server on your system. This registration is part of the MATLAB installation and should have already been done for you as part of the installation. If, for some reason, the registration was not done or did not complete successfully, you may see the following error displayed when you try to run this example:

Can't start MATLAB engine

If you see this error, manually register MATLAB as a server by entering the following commands in a DOS command window:

cd matlabroot\bin\win32
matlab /regserver

or:

cd matlabroot\bin\win64
matlab /regserver

Close the MATLAB window that appears.

Back to Top

Test the Program

Test your application in MATLAB by typing:

!engwindemo

Back to Top

Example — Building an Engine Application on Windows^® System

MATLAB provides a demonstration program written in C that you can use to verify the build process on your computer. The demo file for Windows systems is engwindemo.c.

Copy the C language MEX-file engwindemo.c to your current working directory:

demofile = [matlabroot '\extern\examples\eng_mat\engwindemo.c'];
copyfile(demofile, '.');

Look in the \bin\win32\mexopts directory for the appropriate options file for the Lcc compiler. Use the following commands to build the executable file using this compiler:

optsfile = [matlabroot '\bin\win32\mexopts\lccengmatopts.bat'];
mex('-f', optsfile, 'engwindemo.c');

Verify that the build worked by looking in your current working directory for the file engwindemo.exe:

dir engwindemo.exe

To run the demo from MATLAB, make sure your current working directory is set to the one in which you built the executable file, and then type:

!engwindemo

Back to Top

Example — Building an Engine Application on UNIX^® Systems

MATLAB software provides demonstration programs written in C and C++ that you can use to verify the build process on your computer. The demo files for UNIX systems are engdemo.c and engdemo.cpp.

Copy one of the demonstration programs, for example, engdemo.c, to your current working directory:

demofile = [matlabroot '/extern/examples/eng_mat/engdemo.c'];
copyfile(demofile, '.');

Build the executable file using the ANSI compiler for engine stand alone programs and the options file engopts.sh:

optsfile = [matlabroot '/bin/engopts.sh'];
mex('-f', optsfile, 'engdemo.c');

Verify that the build worked by looking in your current working directory for the file engdemo:

dir engdemo

To run the demo in MATLAB, make sure your current working directory is set to the one in which you built the executable file, and then type:

!engdemo

^[a] Linux is a registered trademark of Linus Torvalds.

^[a] Linux is a registered trademark of Linus Torvalds.

Back to Top

Examples of Calling Engine Functions

Calling Sun™ Java™ Commands from MATLAB® Command Line