(Ebook) MatLab - C C++ Compiler Suite 2.1 PDF

C/C++ Compiler Suite 2.
1
for converting MATLAB applications that contain math, GUIs, and graphics into
®
freely distributable stand-alone C and C++ code
The C/C++ Compiler Suite consists of

three components: the MATLAB Compiler,
the MATLAB C/C++ Math Library, and
the MATLAB C/C++ Graphics Library. KEY FEATURES
Working together, these components
■ Distribute C and C++ applications easily and freely
allow you to convert many MATLAB
to colleagues
applications that contain math, GUIs,
and graphics to stand-alone C/C++ code. ■ Include MATLAB math and graphics in end-user applications
■ Generate, rotate, zoom, and scroll MATLAB 2-D and 3-D

plot types
■ Incorporate MATLAB GUI controls into your application
■ Display lighting and shading on 3-D surfaces

■ Compile toolbox M-files for inclusion in your stand-alone
applications
■ Protect proprietary algorithms to prevent users from
modifying source code
■ Compile, edit, and run your application from within
Visual Studio
This example shows how MATLAB and

the Compiler Suite can be run within
the Microsoft Visual C++ environment.
This stand-alone
application was created
in MATLAB and converted
to C++ using the
C/C++ Compiler Suite.
The MathWorks
MATLAB Compiler
The MATLAB Compiler component serves COMPILER KEY FEATURES
two primary user groups: Developers
looking to deploy MATLAB applications to ■ Protects your proprietary algorithms and prevents users from
stand-alone C/C++ applications and users modifying source code
who want to improve code performance by
■ Provides portable C and C++ code that can run on any MATLAB-
compiling their MATLAB algorithms and
supported platform
converting them to C.
■ Improves the performance of some MATLAB code that contains for
The MATLAB Compiler automatically
or while loops, performs scalar operations, or performs integer or
converts M-files into C and C++ source
exclusively real operations
code, eliminating time-consuming and
error-prone manual translation and ■ Supports the most widely used system compilers, including Microsoft
reducing development time for applications Visual C++, Borland, UNIX native compilers, and GNU (on Linux only)
that run outside the MATLAB environment.
■ Lets you insert calls to arbitrary C and C++ functions and then
Running inside or outside the MATLAB
compile them in both stand-alone and MEX-file modes
environment, the MATLAB Compiler can
automatically translate M-file functions into: ■ Compiles many MATLAB toolbox M-files for inclusion in
your applications
• C/C++ source code or stand-alone
external applications that run
independently of MATLAB (requires
the C/C++ Math and Graphics
Library components) Language Features
• Multi dimensional arrays
• C code S-functions for use in Simulink®
• Structures
models
• Cell arrays
• C versions of MATLAB M-code • Sparse arrays
programs that are linked in at runtime • varargin/varargout
(MEX-files) L • switch/case
• try/catch
• evalin (mex mode only)
• persistent
Sample Command-Line Options

Specify the target language for either C or C++
Generate MEX-files
Generate C code for use with Simulink models
Turn compiling graphics on or off
Turn on trace back error message to display M Line—number line

directives allow M-source level debugging
Turn optimization routines on or off for easier debugging This image processing application, developed with GUIDE,
loads an image file and then uses a MATLAB edge detection
Specify formatting options, including indentation and line wrapping algorithm to identify the edges of the image.

MATLAB Compiler
The Language of Technical Computing
Computation
Visualization
Programming
User’s Guide
Version 2
1 Introducing the MATLAB Compiler
Introduction
This book describes version 2.1 of the MATLAB® Compiler. The MATLAB
Compiler takes M-files as input and generates C or C++ source code or P-code
as output. The MATLAB Compiler can generate these kinds of source code:
• C source code for building MEX-files.

• C or C++ source code for combining with other modules to form stand-alone
applications. Stand-alone applications do not require MATLAB at run time;
they can run even if MATLAB is not installed on the system. The MATLAB
Compiler does require the MATLAB C/C++ Math Library to create
stand-alone applications that rely on the core math and data analysis
capabilities of MATLAB. The MATLAB Compiler also requires the MATLAB
C/C++ Graphics Library in order to create stand-alone applications that
make use of Handle Graphics® functions.
• C code S-functions for use with Simulink®.
• C shared libraries (dynamically linked libraries, or DLLs, on Microsoft
Windows 95/98/2000/NT) and C++ static libraries. These can be used without
MATLAB on the system, but they do require the MATLAB C/C++ Math
Library.
This chapter takes a closer look at these categories of C and C++ source code
and explains the value of compiled code.
Before You Begin

Before reading this book, you should already be comfortable writing M-files. If
you are not, see “Programming and Data Types” in the MATLAB
documentation.
Note The phrase MATLAB interpreter refers to the application that accepts
MATLAB commands, executes M-files and MEX-files, and behaves as
described in Using MATLAB. When you use MATLAB, you are using the
MATLAB interpreter. The phrase MATLAB Compiler refers to this product
that translates M-files to C or C++ source code.This book distinguishes
references to the MATLAB Compiler by using the word ‘Compiler’ with a
capital C. References to “compiler” with a lowercase c refer to your C or C++
compiler.
1-2
Additional Language Support
pause and continue. These commands are now supported.
eval and input. eval and input are supported for strings that do not contain
workspace variables.
Note As of Compiler 2.1, Compiler 1.2 is no longer available due to the

evolution of internal data structures. The -V1.2 option is no longer supported,
along with any options recognized by Compiler 1.2.
Compiler Licensing Changes

Starting with Compiler 1.2.1, a new licensing scheme has been employed that
enables the product to be simpler and more user friendly.
In versions prior to 1.2.1, you could not run the MATLAB Compiler unless you
were running MATLAB. On networked systems, this meant that one user
would be holding the license for one copy of MATLAB and the Compiler,
simultaneously. In effect, one user required both products and tied up both
licenses until the user exited MATLAB. Although you can still run the
Compiler from within MATLAB, it is not required. One user could be running
the Compiler while another user could be using MATLAB.
The licensing model is based on how you run the Compiler:
• From the MATLAB command prompt

• From a DOS/UNIX shell
Running Compiler from MATLAB

When you run the Compiler from “inside” of MATLAB, that is, you run mcc
from the MATLAB command prompt, you hold the Compiler license as long as
MATLAB remains open . To give up the Compiler license, exit MATLAB.
1-5
Running Compiler from DOS/UNIX Shell

If you run the Compiler from a DOS or UNIX shell, you are running from
“outside” of MATLAB. In this case, the Compiler:
• Does not require MATLAB to be running on the system where the Compiler
is running
• Gives the user a dedicated 30 minute time allotmentduring which the user
has complete ownership over a license to the Compiler
Each time a user requests the Compiler, the user begins a 30 minute time
period as the sole owner of the Compiler license. Anytime during the 30 minute
segment, if the same user requests the Compiler, the user gets a new 30 minute
allotment. When the 30-minute time interval has elapsed, if a different user
requests the Compiler, the new user gets the next 30 minute interval.
When a user requests the Compiler and a license is not available, the user
receives the message
Error: Could not check out a Compiler License.
This message is given when no licenses are available. As long as licenses are
available, the user gets the license and no message is displayed. The best way
to guarantee that all MATLAB Compiler users have constant access to the
Compiler is to have an adequate supply of licenses for your users.
1-6
Uses of the Compiler

The MATLAB Compiler (mcc) can translate M-files into C files . The resultant
C files can be used in any of the supported executable types including MEX,
executable, or library by generating an appropriate wrapper file
. A wrapper file
contains the required interface between the Compiler-generated code and a
supported executable type . For example, a MEX wrapper contains the MEX
gateway routine that sets up the left- and right-hand arguments for invoking
the Compiler-generated code.
The code produced by the MATLAB Compiler is independent of the final target
type — MEX, executable, or library. The wrapper file provides the necessary
interface to the target type.
Creating MEX-Files
The MATLAB Compiler, when invoked with the -x macro option, produces a
MEX-file from M-files. The Compiler:
1 Translates your M code to C code.
2 Generates a MEX wrapper.
3 Invokes the mex utility which builds the C MEX-file source into a MEX-file
by linking the MEX-file with the MEX version of the math libraries
(libmatlbmx).
This figure illustrates the process of producing a MEX-file. The MATLAB

interpreter dynamically loads MEX-files as they are needed. Some MEX-files
run significantly faster than their M-file equivalents, which is explained in
“Faster Execution” on page 1-14.
1-7
M-File
mcc -x
• Shaded block is user-written code.

C version of C MEX-File • Shadowed blocks are MathWorks
M code Wrapper tools.
• Unshaded blocks are MATLAB
Compiler-generated code.
mex • Dotted block is C/C++
compiler-generated executable.
MEX Math Library

(libmatlbmx)
MEX-File
Figure 1-1: Developing MEX-Files
MATLAB users who do not have the MATLAB Compiler must write the source
code for MEX-files in either Fortran or C. “External Interfaces/API” explains
the fundamentals of this process. To write MEX-files, you have to know how
MATLAB represents its supported data types and the MATLAB external
interface (i.e., the application program interface, or API.)
If you are comfortable writing M-files and have the MATLAB Compiler, then
you do not have to learn all the details involved in writing MEX-file source
code.
1-8
Creating Stand-Alone Applications

C Stand-Alone Applications
The MATLAB Compiler, when invoked with the -m macro option, translates
input M-files into C source code that is usable in any of the supported
executable types. The Compiler also produces the required wrapper file
suitable for a stand-alone application.Then, your ANSI C compiler compiles
these C source code files and the resulting object files are linked against the
MATLAB C/C++ Math Library , which you must have in order to create C or
C++ stand-alone applications. For more information about which libraries
must be included when you distribute a C application, see “Distributing
Stand-Alone UNIX Applications” on page 4-14 or “Distributing Stand-Alone
Windows Applications” on page 4-26.
Note If you do not have the MATLAB C/C++ Graphics Library (libsgl), and
your application calls a Handle Graphics function, a run-time error occurs.
C++ Stand-Alone Applications

The MATLAB Compiler, when invoked with the -p macro option, translates
input M-files into C++ source code that is usable in any of the executable types
except MEX. The Compiler also produces the required wrapper file suitable for
a stand-alone application. Then, your C++ compiler compiles this C++ source
code and the resulting object files are linked against the MATLAB C/C++ Math
Library. For more information about which libraries must be included when
you distribute a C++ application, see “Distributing Stand-Alone UNIX
Applications” on page 4-14 or “Distributing Stand-Alone Windows
Applications” on page 4-26.
Developing a Stand-Alone Application

Suppose you want to create an application that calculates the rank of a large
magic square. One way to create this application is to code the whole
application in C or C++; however, this would require writing your own magic
square, rank, and singular value routines.
An easier way to create this application is to write it as one or more M-files.
This figure outlines this development process.
1-9
M-File function to find the

rank of a magic square
mcc -m
• Shaded block is user-written code.
C version of C File • Shadowed blocks are tools.

mbuild does
this part. M code Wrapper • Unshaded blocks are MATLAB
• Dotted blocks are C/C++
C Compiler compiler-generated executables.
Object Files
MATLAB M-File Math Library MATLAB API Library
MATLAB Math Built-In Library MATLAB Utility Library

ANSI C Library MATLAB C/C++ Graphics Library
Linker
Stand-Alone
C Application
Figure 1-2: Developing a Typical Stand-Alone C Application
1-10
Why Compile M-Files?

There are three main reasons to compile M-files:
• To create stand-alone applications or C shared libraries(DLLs on Windows)

or C++ static libraries
• To hide proprietary algorithms
• To speed them up
Stand-Alone Applications and Libraries

You can create MATLAB applications that take advantage of the mathematical
functions of MATLAB, yet do not require that the user owns MATLAB .
Stand-alone applications are a convenient way to package the power of
MATLAB and to distribute a customized applicationto your users.
You can develop an algorithm in MATLAB to perform specialized calculations
and use the Compiler to create a C shared library (DLL on Windows) or a C++
static library. You can then integrate the algorithm into a C/C++ application.
After you compile the C/C++ application, you can use the MATLAB algorithm
to perform specialized calculations from your program.
Hiding Proprietary Algorithms

MATLAB M-files are ASCII text files that anyone can view and modify.
MEX-files are binary files. Shipping MEX-files or stand-alone applications
instead of M-files hides proprietary algorithms and prevents modification of
your M-files.
Faster Execution
Compiled C or C++ code typically runs faster than its M-file equivalents
because:
• Compiled code usually runs faster than interpreted code.

• C or C++ can avoid unnecessary memory allocation overhead that the
MATLAB interpreter performs.
1-14
Why Compile M-Files?
Cases When Performance Does Not Improve. Compilation is not likely to speed up
M-file functions that:
• Are heavily vectorized

• Spend most of their time in MATLAB’s built-in indexing, math, or graphics
functions
Cases When Performance Does Improve. Compilation is most likely to speed up

M-file functions that contain loops.
1-15
Limitations and Restrictions

MATLAB Code
This version of the MATLAB Compiler supports almost all of the functionality
of MATLAB. However, there are some limitations and restrictions that you
should be aware of. Although this version of the MATLAB Compiler cannot
compile the following, a future version will be able to compile them:
• Script M-files (See “Converting Script M-Files to Function M-Files” in

Chapter 3 for further details.)
• M-files that use objects
• M-files that use input or eval to manipulate workspace variables.
• M-files that dynamically name variables to be loaded or saved. For example,
x= 'f';
load('foo.mat',x);
is disallowed by the Compiler.
Note input and eval calls that do not use workspace variables will compile
and execute properly.
The Compiler cannot compile built-in MATLAB functions (functions such as

eig have no M-file, so they can’t be compiled). Note, however, that most of these
functions are available to you because they are in the MATLAB Math Built-in
Library (libmatlb).
In addition, the Compiler does not honor conditional global and persistent
declarations. It treats global and persistent as declarations. For example,
if (y==3)
persistent x
else
x = 3;
end
1-17
Stand-Alone Applications
The restrictions and limitations noted in the previous section also apply to
stand-alone applications. The functions in this table are supported in
MEX-mode, but are not supported in stand-alone mode.
Note You cannot call any Handle Graphics functions unless you have the
optional Graphics Library installed. In addition, stand-alone applications
cannot access Simulink functions. Although the MATLAB Compiler can
compile M-files that call these functions, the MATLAB C/C++ Math library
does not support them. Therefore, unless you write your own versions of the
unsupported routines in a MEX-file or as C-code, when you run the
executable, you will get a run-time error.
Table 1-2: Unsupported Functions in Stand-Alone Mode
add_block add_line applescript assignin
callstats close_system cputime dbclear
dbcont dbdown dbquit dbstack
dbstatus dbstep dbstop dbtype
dbup delete_block delete_line diary
echo edt errorstat errortrap
evalin fields fschange functionscalled
get_param hcreate help home
hregister inferiorto inmem isglobal
isjava isruntime java javaArray
javaMethod javaObject keyboard linmod
lookfor macprint mactools methods
mislocked mlock more munlock
new_system open_system pack pfile
1-18
Table 1-2: Unsupported Functions in Stand-Alone Mode (Continued)

rehash runtime set_param sim
simget simset sldebug str2func
superiorto system_dependent trmginput type
vms what which who
whos
Fixing Callback Problems: Missing Functions

When the Compiler creates a stand-alone application, it compiles the M-file
you specify on the command line and, in addition, it compiles any other M-files
that your M-file calls. If your application includes a call to a function in a
callback string or in a string passed as an argument to the feval function or
an ODE solver, and this is the only place in your M-file this function is called,
the Compiler will not compile the function. The Compiler does not look in these
text strings for the names of functions to compile.
Symptom
Your application runs, but an interactive user interface element, such as a
push button, is unresponsive. When you close the application, the graphics
library issues this error message:
An error occurred in the callback : change_colormap
The error message caught was : Reference to unknown function
change_colormap from FEVAL in stand-alone mode.
Workaround
To eliminate this error, create a list of all the functions that are specified only
in callback strings and pass this list to the %#function pragma. (See “Finding
Missing Functions in an M-File” on page 1-20 for hints about finding functions
in callback strings.) The Compiler processes any function listed in a
%#function pragma.
For example, the call to the change_colormap function in the sample

application, my_test, illustrates this problem. To make sure the Compiler
processes the change_colormap M-file, list the function name in the
%#function pragma.
1-19
2
Installation and
Configuration
System Configuration for MEX-Files . . . . . . . . . 2-3
UNIX Workstation . . . . . . . . . . . . . . . . . 2-5

System Requirements . . . . . . . . . . . . . . . . . 2-5
Installation . . . . . . . . . . . . . . . . . . . . . 2-7
mex Verification . . . . . . . . . . . . . . . . . . . 2-8
MATLAB Compiler Verification . . . . . . . . . . . . . 2-12
Microsoft Windows on PCs . . . . . . . . . . . . . 2-14

System Requirements . . . . . . . . . . . . . . . . . 2-14
Installation . . . . . . . . . . . . . . . . . . . . . 2-18
mex Verification . . . . . . . . . . . . . . . . . . . 2-20
MATLAB Compiler Verification . . . . . . . . . . . . . 2-24
Troubleshooting . . . . . . . . . . . . . . . . . . 2-26
mex Troubleshooting . . . . . . . . . . . . . . . . . 2-26
Troubleshooting the Compiler . . . . . . . . . . . . . 2-28
System Configuration for MEX-Files
System Configuration for MEX-Files

This section outlines the steps necessary to configure your system to create
MEX-files.
The sequence of steps to install and configure the MATLAB Compiler so that it
can generate MEX-files is:
1 Install the MATLAB Compiler .
2 Install an ANSI C or C++ compiler , if you don’t already have one installed.
3 Verify that mex can generate MEX-files.
4 Verify that the MATLAB Compiler can generate MEX-files from the
MATLAB command line and from the UNIX or DOS command line.
This figure shows the Compiler installation sequence for creating MEX-files on
both platforms. The sections following the flowchart provide more specific
details for the individual platforms. Additional steps may be necessary if you
plan to create stand-alone applications or libraries,however, you still must
perform the steps given in this chapter first. Chapter 4, “Stand-Alone
Applications” provides the details about the additional installation and
configuration steps necessary for creating stand-alone applications and
libraries.
Note This flowchart assumes that MATLAB is properly installed on your

system.
2-3
2 Installation and Configuration
Start
Use MATLAB installer to

Install MATLAB
Compiler install component (MATLAB
Compiler).
Follow vendor’s instructions

Install ANSI C/ Is ANSI C or C++ No
to install and test
C++ Compiler compiler installed
ANSI C or C++ compiler.
?
Yes 1
Test your Does the MATLAB command No

Verify
mex mex yprime.c
mex configuration. generate proper MEX-file
?
See “mex
Yes Troubleshooting.”
2
1
Verify MATLAB
Compiler can Test your Does the MATLAB command No
generate
MEX-files from MATLAB Compiler mcc invhilb.m
MATLAB/DOS/ installation/configuration. generate invhilb.mex
UNIX command ?
line
See “Compiler
Yes Troubleshooting.”
Stop
2
Figure 2-1: MATLAB Compiler Installation Sequence for Creating MEX-Files
2-4
UNIX Workstation
UNIX Workstation
This section examines the system requirements, installation procedures, and
configuration procedures for the MATLAB Compiler on UNIX systems.
System Requirements
You cannot install the MATLAB Compiler unless MATLAB 6/Release 12 is
already installed on the system.The MATLAB Compiler imposes no operating
system or memory requirements beyond those that are necessary to run
MATLAB. The MATLAB Compiler consumes a small amount of disk space.
This table shows the requirements for creating UNIX applications with the
MATLAB Compiler.
Table 2-1: Requirements for Creating UNIX Applications
To create... You need...
MEX-files ANSI C compiler

MATLAB Compiler
Stand-alone C applications ANSI C compiler

MATLAB Compiler
MATLAB C/C++ Math Library
Stand-alone C++ applications C++ compiler

MATLAB Compiler
The MATLAB C/C++ Math Library is a separately sold product.
Note If your application uses Handle Graphics, you will need the MATLAB
C/C++ Graphics Library to develop stand-alone applications. The MATLAB C/
C++ Graphics Library is a separately sold product.
2-5
Note Although the MATLAB Compiler supports the creation of stand-alone

C++ applications, it does not support the creation of C++ MEX-files.
Supported ANSI C and C++ UNIX Compilers

The MATLAB Compiler supports:
• The GNU C compiler, gcc, (except on HP and SGI64)

• The system’s native ANSI C compiler on all UNIX platforms
• The system’s native C++ compiler on all UNIX platforms (except Linux)
• The GNU C++ compiler, g++, on Linux.
Note For a list of all the compilers supported by MATLAB, see the
MathWorks Technical Support Department’s Technical Notes at
http://www.mathworks.com/support/tech-notes/v5/1600/1601.shtml
Known Compiler Limitations. There are several known restrictions regarding the
use of supported compilers:
• The SGI C compiler does not handle denormalized floating-point values

correctly. Denormalized floating-point numbers are numbers that are
greater than 0 and less than the value of DBL_MIN in the compiler’s float.h
file.
• Due to a limitation of the GNU C++ compiler (g++) on Linux, try…catch…end
blocks do not work.
• The -A debugline:on option does not work on the GNU C++ compiler (g++)
on Linux because it uses try…catch…end.
Compiler Options Files

The MathWorks provides options files for every supported C or C++ compiler.
These files contain the necessary flags and settings for the compiler.
This table
2-6
UNIX Workstation
shows the preconfigured options files that are included with MATLAB for
UNIX.
Compiler Options File
System native ANSI compiler mexopts.sh
gcc (GNU C compiler) gccopts.sh
Information on the options files is provided for those users who may need to
modify them to suit their own needs. Many users never have to be concerned
with the inner workings of the options files.
Locating Options Files

To locate your options file, the mex script searches the following:
• The current directory

• $HOME/.matlab/R12
• <matlab>/bin
mex uses the first occurrence of the options file it finds. If no options file is
found, mex displays an error message.
Installation
MATLAB Compiler
To install the MATLAB Compiler on UNIX systems, follow the instructions in
the MATLAB Installation Guide for UNIX. If you have a license to install the
MATLAB Compiler, it appears as one of the installation choices that you can
select as you proceed through the installation process. If the MATLAB
Compiler does not appear as one of the installation choices, contact The
MathWorks to get an updated license file (license.dat):
• Via the Web at www.mathworks.com. On the MathWorks home page, click on

the MATLAB Access option, log in to the Access home page, and follow the
instructions.
• Via e-mail at service@mathworks.com
2-7
UNIX Workstation
If you do not need to change C or C++ compilers, or you do not need to modify
your compiler options files, you can skip ahead in this section to “Creating
MEX-Files” on page 2-10. If you need to know how to change the options file,
continue with this section.
Changing Compilers
Changing the Default Compiler. To change your default C or C++ compiler, you
select a different options file. You can do this at anytime by using the command
mex -setup
Using the 'mex -setup' command selects an options file that is

placed in ~/.matlab/R12 and used by default for 'mex'. An options
file in the current working directory or specified on the
command line overrides the default options file in ~/.matlab/R12.
Options files control which compiler to use, the compiler and

link command options, and the runtime libraries to link against.
To override the default options file, use the 'mex -f' command
(see 'mex -help' for more information).
The options files available for mex are:
1: <matlab>/bin/gccopts.sh :
Template Options file for building gcc MEX-files
2: <matlab>/bin/mexopts.sh :
Template Options file for building MEX-files via the
system ANSI compiler
Enter the number of the options file to use as your default options
file:
Select the proper options file for your system by entering its number and
pressing Return. If an options file doesn’t exist in your MATLAB directory, the
system displays a message stating that the options file is being copied to your
user-specific matlab directory. If an options file already exists in your
MATLAB directory, the system prompts you to overwrite it.
2-9
Note The setup option creates a user-specific, matlab directory in your

individual home directory and copies the appropriate options file to the
directory.(If the directory already exists, a new one is not created.) This
matlab directory is used for your individual options files only; each user can
have his or her own default options files (other MATLAB products may place
options files in this directory). Do not confuse these user-specific matlab
directories with the system matlab directory, where MATLAB is installed.
Using the setup option resets your default compiler so that the new compiler
is used every time you use the mex script
.
Modifying the Options File. Another use of the setup option is if you want to
change your options file settings. For example, if you want to make a change to
the current linker settings, or you want to disable a particular set of warnings,
you should use the setup option.
As the previous note says, setup copies the appropriate options file to your
individual directory. To make your user-specific changes to the options file, you
then edit your copy of the options file to correspond to your specific needs and
save the modified file. This sets your default compiler’s options file to your
specific version.
Temporarily Changing the Compiler. To temporarily change your C or C++ compiler,

use the -f option, as in
mex -f <file> …
The -f option tells the mex script to use the options file, <file>. If <file> is not
in the current directory, then <file> must be the full pathname to the desired
options file. Using the -f option tells the mex script to use the specified options
file for the current execution of mex only; it does not reset the default compiler.
Creating MEX-Files
To create MEX-files on UNIX, first copy the source file(s) to a local directory,
and then change directory (cd) to that local directory.
2-10
UNIX Workstation
On UNIX, MEX-files are created with platform-specific extensions, as shown in

this table.
Table 2-2: MEX-File Extensions for UNIX
Platform MEX-File Extension
DEC Alpha mexaxp
HP 9000 PA-RISC mexhp7
HP-UX mexhpux
IBM RS/6000 mexrs6
Linux mexglx
SGI mexsg
Solaris mexsol
The <matlab>/extern/examples/mex directory contains C source code for the

example yprime.c . After you copy the source file (yprime.c) to a local directory
and cd to that directory, enter at the MATLAB prompt
mex yprime.c
This should create the MEX-file called yprime with the appropriate extension
corresponding to your UNIX platform. For example, if you create the MEX-file
on Solaris, its name is yprime.mexsol.
You can now call yprime from the MATLAB prompt as if it were an M-function.
For example,
yprime(1,1:4)
ans =
2.0000 8.9685 4.0000 -1.0947
If you encounter problems generating the MEX-file or getting the correct

results, refer to “External Interfaces/API” in the MATLAB documentation for
additional information about MEX-files.
2-11
MATLAB Compiler Verification

Verifying from MATLAB
Once you have verified that you can generate MEX-files on your system, you
are ready to verify that the MATLAB Compiler is correctly installed . Type the
following at the MATLAB prompt.
mcc -x invhilb
After a short delay, this command should complete and display the MATLAB
prompt. Next, at the MATLAB prompt, type
which invhilb
The which command should indicate that invhilb is now a MEX-file by listing
the filename followed by the appropriate UNIX MEX-file extension. For
example, if you run the Compiler on Solaris, the Compiler creates the file
invhilb.mexsol. Finally, at the MATLAB prompt, type
invhilb(10)
Note that this tests only the Compiler’s ability to make MEX-files. If you want
to create stand-alone applications, refer to Chapter 4, “Stand-Alone
Applications” for additional details.
Verifying from UNIX Command Prompt

To verify that the Compiler can generate MEX-files from the UNIX command
prompt, you follow a similar procedure as that used in the previous section.
Note Before you test to see if the Compiler can generate MEX-files from the
UNIX command prompt, you may want to delete the MEX-file you created in
the previous section, invhilb.mexsol, or whatever the extension is on your
system. That way, you can be sure your newly generated MEX-file is the
result of using the Compiler from the UNIX prompt.
Copy invhilb.m from the <matlab>/toolbox/matlab/elmat directory to a local

directory and then type the following at the UNIX prompt.
mcc -x invhilb
2-12
UNIX Workstation
Next, verify that invhilb is now a MEX-file by listing the invhilb files.
ls invhilb.*
You will see a list similar to this.

invhilb.c invhilb.m invhilb_mex.c
invhilb.h invhilb.mexsol
These are the various files that the Compiler generates from the M-file.The
Compiler-generated MEX-file appears in the list as the filename followed by
the appropriate UNIX MEX-file extension. In this example, the Compiler was
executed on Solaris, so the Compiler creates the file invhilb.mexsol. For more
information on which files the Compiler creates for a compilation, see Chapter
5, “Controlling Code Generation.”
To test the newly created MEX-file, start MATLAB and, at the MATLAB
prompt, type
invhilb(10)
2-13
Microsoft Windows on PCs

This section examines the system requirements, installation procedures, and
configuration procedures for the MATLAB Compiler on PCs running Windows
95/98/2000 or Windows NT.
System Requirements
You cannot install the MATLAB Compiler unless MATLAB 6/Release 12 is
already installed on the system. The MATLAB Compiler imposes no operating
system or memory requirements beyond what is necessary to run MATLAB.
The MATLAB Compiler consumes a small amount of disk space.
This table shows the requirements for creating PC applications with the
MATLAB Compiler.
Table 2-3: Requirements for Creating PC Applications
To create... You need...
MEX-files ANSI C compiler (see following note)

MATLAB Compiler
Stand-alone C applications ANSI C compiler (see following note)

MATLAB Compiler
Stand-alone C++ applications C++ compiler

MATLAB Compiler
Note MATLAB includes an ANSI C compiler (Lcc) that is suitable for use
with the MATLAB Compiler.
The MATLAB C/C++ Math Library is a separately sold product; the MATLAB
C/C++ Graphics Library is a separately sold product. If your application uses
Handle Graphics, you will need the MATLAB C/C++ Graphics Library to
develop stand-alone applications.
2-14
Note Although the MATLAB Compiler supports the creation of stand-alone

C++ applications, it does not support the creation of C++ MEX-files.
Supported ANSI C and C++ PC Compilers

To create C MEX-files, stand-alone C/C++ applications, or dynamically linked
libraries (DLLs) with the MATLAB Compiler, you must install and configure a
supported C/C++ compiler. Use one of the following 32-bit C/C++ compilers
that create 32-bit Windows dynamically linked libraries (DLLs) or Windows
NT applications:
• Lcc C version 2.4 (included with MATLAB)

• Watcom C/C++ versions 10.6 & 11.0
• Borland C++ versions 5.0, 5.2, 5.3, 5.4, & 5.5
• Microsoft Visual C++ (MSVC) versions 5.0 & 6.0
Note For a list of all the compilers supported by MATLAB, see the
MathWorks Technical Support Department’s Technical Notes at:
http://www.mathworks.com/support/tech-notes/v5/1600/1601.shtml
To create stand-alone applications or DLLs, you also need the MATLAB C/C++
Math Library, which is sold separately. Also, if your applications use Handle
Graphics, you will need the MATLAB C/C++ Graphics Library , which is sold
separately.
Applications generated by the MATLAB Compiler are 32-bit applications and
only run on Windows 95/98/2000 and Windows NT systems.
Known Compiler Limitations. There are several known restrictions regarding the
use of supported compilers:
• Some compilers, e.g., Watcom, do not handle denormalized floating-point

values correctly. Denormalized floating-point numbers are numbers that are
greater than 0 and less than the value of DBL_MIN in your compiler’s float.h
file.
2-15

The MathWorks provides options files for every supported C or C++ compiler.
These files contain the necessary flags and settings for the compiler
. This table
shows the preconfigured PC options files that are included with MATLAB.
Compiler Options File
Lcc C, Version 2.4 (included with lccopts.bat

MATLAB)
Microsoft C/C++, Version 5.0 msvc50opts.bat

Microsoft C/C++, Version 6.0 msvc60opts.bat
Watcom C/C++, Version 10.6 watcopts.bat (supported for mex

Watcom C/C++, Version 11.0 only, not for mbuild)
wat11copts.bat (supported for mex
only, not for mbuild)
Borland C++, Version 5.0 bccopts.bat
Borland C++, Version 5.2 bccopts.bat
Borland C++ Builder 3 bcc53opts.bat

To locate your options file, the mex script searches the following:

• The user profile directory (see the following section, “The User Profile
Directory Under Windows,” for more information about this directory)
mex uses the first occurrence of the options file it finds. If no options file is
found, mex searches your machine for a supported C compiler and uses the
factory default options file for that compiler. If multiple compilers are found,
you are prompted to select one.
The User Profile Directory Under Windows. The Windows user profile directory is
a directory that contains user-specific information such as desktop appearance,
recently used files, and Start menu items. The mex and mbuild utilities store
their respective options files, mexopts.bat and compopts.bat, which are
2-17
3
Getting Started
with MEX-Files
A Simple Example - The Sierpinski Gasket . . . . . . 3-3
Invoking the M-File . . . . . . . . . . . . . . . . . 3-4
Compiling the M-File into a MEX-File . . . . . . . . . . 3-5
Invoking the MEX-File . . . . . . . . . . . . . . . . 3-5
Compiler Options and Macros . . . . . . . . . . . . 3-7
Generating Simulink S-Functions . . . . . . . . . . 3-8

Simulink-Specific Options . . . . . . . . . . . . . . . 3-8
Specifying S-Function Characteristics . . . . . . . . . . 3-9
Converting Script M-Files to Function M-Files . . . . 3-11

A Simple Example - The Sierpinski Gasket

Consider an M-file function called gasket.m.
function theImage = gasket(numPoints)
%GASKET An image of a Sierpinski Gasket.
% IM = GASKET(NUMPOINTS)
%
% Example:
% x = gasket(50000);
% imagesc(x);colormap([1 1 1;0 0 0]);
% axis equal tight
% Copyright (c) 1984-98 by The MathWorks, Inc

% $Revision: 1.1 $ $Date: 1998/09/11 20:05:06 $
theImage = zeros(1000,1000);
corners = [866 1;1 500;866 1000];

startPoint = [866 1];
theRand = rand(numPoints,1);
theRand = ceil(theRand*3);
for i=1:numPoints
startPoint = floor((corners(theRand(i),:)+startPoint)/2);
theImage(startPoint(1),startPoint(2)) = 1;
end
How the Function Works

This function determines the coordinates of a Sierpinski Gasket using an
Iterated Function System algorithm. The function starts with three points that
define a triangle, and starting at one of these points, chooses one of the
remaining points at random. A dot is placed at the midpoint of these two points.
From the new point, a dot is placed at the midpoint between the new point and
a point randomly selected from the original points. This process continues and
eventually leads to an approximation of a curve.
3-3
3 Getting Started with MEX-Files
The curve can be graphed in many ways. Sierpinski’s method is:
• Start with a triangle and from it remove a triangle that is one-half the height
of the original and inverted. This leaves three triangles.
• From each of the remaining three triangles, remove a triangle that is
one-fourth the height of these new triangles and inverted. This leaves nine
triangles.
• The process continues and at infinity the surface area becomes zero and the
length of the curve is infinite.
gasket.m is a good candidate for compilation because it contains a loop. The

overhead of the for loop command is relatively high compared to the cost of the
loop body. M-file programmers usually try to avoid loops containing scalar
operations because loops run relatively slowly under the MATLAB interpreter.
To achieve a reasonable approximation of the Sierpinski Gasket, set the
number of points to 50,000. To compute the coordinates and time the
computation, you can use
tic; x = gasket(50000); toc
To display the figure, you can use

imagesc(x); colormap([1 1 1;0 0 0]);
axis equal tight
Invoking the M-File

To get a baseline reading, you can determine how long it takes the MATLAB
interpreter to run gasket.m. The built-in MATLAB functions tic and toc are
useful tools for measuring time.
elapsed_time =
7.9620
On the Pentium Pro 200, the M-file took about 10 seconds of CPU time to
calculate the first 50,000 points on the Sierpinski Gasket.
3-4
Note The timings listed in this book were recorded on a Pentium Pro 200
MHz PC running Microsoft Windows NT. In each case, the code was executed
two times and the results of the second execution were captured for this book.
All of the timings listed throughout this book are for reference purposes only.
They are not absolute; if you execute the same example under the same
conditions, your times will probably differ from these values. Use these values
as a frame of reference only.
Compiling the M-File into a MEX-File

To create a MEX-file from this M-file, enter the mcc command at the MATLAB
interpreter prompt.
mcc -x gasket
This mcc command generates:
• A file named gasket.c containing MEX-file C source code.

• A file named gasket.h containing the public information.
• A file named gasket_mex.c containing the MEX-function interface (MEX
wrapper).
• A MEX-file named gasket.mex. (The actual filename extension of the
executable MEX-file varies depending on your platform, e.g., on the PC the
file is named gasket.dll.)
mcc automatically invokes mex to create gasket.mex from gasket.c and

gasket_mex.c. The mex utility encapsulates the appropriate C compiler and
linker options for your system.
This example uses the -x macro option to create the MEX-file. For more
information on this Compiler option as well as the other options, see the mcc
reference page. For more information on the files that the Compiler generates,
see Chapter 5, “Controlling Code Generation.”
Invoking the MEX-File

Invoke the MEX-file version of gasket from the MATLAB interpreter the same
way you invoke the M-file version.
3-5
3 Getting Started with MEX-Files
MATLAB runs the MEX-file version (gasket.mex) rather than the M-file
version (gasket.m). Given an M-file and a MEX-file with the same root name
(gasket) in the same directory, the MEX-file takes precedence.
This produces
elapsed_time =
5.2880
The MEX-file runs about 33% faster than the M-file version.
Note These are optimized times.
To display the Sierpinski Gasket, use

imagesc(x); colormap([1 1 1;0 0 0]);
axis equal tight
This figure shows the results.
Figure 3-1: The Sierpinski Gasket for 50,000 Points
3-6
Converting Script M-Files to Function M-Files
Converting Script M-Files to Function M-Files

MATLAB provides two ways to package sequences of MATLAB commands:
• Function M-files
• Script M-files
These two categories of M-files differ in two important respects:
• You can pass arguments to function M-files but not to script M-files.
• Variables used inside function M-files are local to that function; you cannot
access these variables from the MATLAB interpreter’s workspace unless
they are passed back by the function. By contrast, variables used inside
script M-files are shared with the caller’s workspace; you can access these
variables from the MATLAB interpreter command line.
The MATLAB Compiler cannot compile script M-files nor can it compile a
function M-file that calls a script.
Converting a script into a function is usually fairly simple. To convert a script
to a function, simply add a function line at the top of the M-file.
For example, consider the script M-file houdini.m.
m = magic(4); % Assign 4x4 matrix to m.
t = m .^ 3; % Cube each element of m.
disp(t); % Display the value of t.
Running this script M-file from a MATLAB session creates variables m and t in
your MATLAB workspace.
The MATLAB Compiler cannot compile houdini.m because houdini.m is a
script. Convert this script M-file into a function M-file by simply adding a
function header line.
function [m,t] = houdini(sz)
m = magic(sz); % Assign matrix to m.
t = m .^ 3; % Cube each element of m.
disp(t) % Display the value of t.
The MATLAB Compiler can now compile houdini.m. However, because this
makes houdini a function, running houdini.mex no longer creates variable m
3-11
4
Stand-Alone
Applications
Differences Between MEX-Files
and Stand-Alone Applications . . . . . . . . . . 4-3
Building Stand-Alone C/C++ Applications . . . . . . . 4-5
Building Stand-Alone Applications on UNIX . . . . . 4-8
Building Stand-Alone Applications on PCs . . . . . . 4-16
Building Shared Libraries . . . . . . . . . . . . . 4-27
Troubleshooting . . . . . . . . . . . . . . . . . . 4-28
Coding with M-Files Only . . . . . . . . . . . . . . 4-31
Alternative Ways of Compiling M-Files . . . . . . . . 4-35
Mixing M-Files and C or C++ . . . . . . . . . . . . . 4-37

Differences Between MEX-Files and Stand-Alone Applications
Differences Between MEX-Files and Stand-Alone

Applications
MEX-files and stand-alone applications differ in these respects:
• MEX-files run in the same process space as the MATLAB interpreter . When
you invoke a MEX-file, the MATLAB interpreter dynamically links in the
MEX-file.
• Stand-alone C or C++ applications run independently of MATLAB.
MEX-Files
It is now possible to call MEX-files from Compiler-generated stand-alone
applications. The Compiler will compile MEX-files whenever they are specified
on the command line or are located using the -h option to find helper functions
.
The MEX-files will then be loaded and called by the stand-alone code.
If an M-file and a MEX-file appear in the same directory and the M-file
contains at least one function, the Compiler will compile the M-file instead of
the MEX-file. If the MEX-file is desired instead, you must use the %#mex
pragma. For more information on this pragma, see “%#mex” in Chapter 7.
Note The Compiler-generated code cannot invoke Compiler-generated

MEX-files. Specify the M-file(s) source instead and the Compiler will compile
those into the stand-alone application.
Stand-Alone C Applications
To build stand-alone C applications as described in this chapter, MATLAB, the
MATLAB Compiler, a C compiler, and the MATLAB C/C++ Math Library must
be installed on your system.
The source code for a stand-alone C application consists either entirely of
M-files or some combination of M-files, MEX-files, and C or C++ source code
files.
4-3
4 Stand-Alone Applications
The MATLAB Compiler translates input M-files into C source code suitable for
your own stand-alone applications. After compiling this C source code, the
resulting object file is linked with the object libraries.
For more information about which libraries must be included when you
distribute a C application, see “Distributing Stand-Alone UNIX Applications”
on page 4-14 or “Distributing Stand-Alone Windows Applications” on page
4-26.
Note If you attempt to compile M-files to produce stand-alone applications

and you do not have the MATLAB C/C++ Math Library installed, the system
will not be able to find the appropriate libraries and the linking will fail. Also,
if you do not have the MATLAB C/C++ Graphics Library installed, the
MATLAB Compiler will generate run-time errors if the graphics functions are
called.
Stand-Alone C++ Applications

To build stand-alone C++ applications, MATLAB, the MATLAB Compiler, a
C++ compiler, and the MATLAB C/C++ Math Library must be installed on your
system.
The source code for a stand-alone C++ application consists either entirely of
M-files or some combination of M-files, MEX-files, and C or C++ source code
files.
The MATLAB Compiler, when invoked with the appropriate option flag (-p or
-L Cpp), translates input M-files into C++ source code suitable for your own
stand-alone applications. After compiling this C++ source code, the resulting
object files are linked against the MATLAB C/C++ Math Library. For more
information about which libraries must be included when you distribute a C++
application, see “Distributing Stand-Alone UNIX Applications” on page 4-14 or
“Distributing Stand-Alone Windows Applications” on page 4-26.
Note On the PC, the MATLAB C++ Math Library is static because the
different PC compiler vendors use different C++ name-mangling algorithms.
4-4
Building Stand-Alone C/C++ Applications

This section explains how to build stand-alone C and C++ applications on
UNIX systems and PCs running Microsoft Windows.
This section begins with a summary of the steps involved in building
stand-alone C/C++ applications, including the mbuild script, which helps
automate the build process, and then describes platform-specific issues for both
supported platforms.
Note This chapter assumes that you have installed and configured the
MATLAB Compiler.
Overview
On both operating systems, the steps you use to build stand-alone C and C++
applications are:
1 Verify that mbuild can create stand-alone applications.
2 Verify that the MATLAB Compiler can link object files with the proper
libraries to form a stand-alone application.
4-5
This figure shows the sequence on both platforms. The sections following the
flowchart provide more specific details for the individual platforms.
Start
Verify Test your Does the command No

mbuild mbuild ex1.c
mbuild configuration. generate proper application
?
See “Troubleshooting
Yes mbuild.”
2
1
Test your Does the command

Verify MATLAB No
Compiler can MATLAB Compiler mcc -m hello
generate generate the hello application
application
configuration.
?
See “Troubleshooting
Yes Compiler.”
Stop
2
Figure 4-1: Sequence for Creating Stand-Alone C/C++ Applications
Packaging Stand-Alone Applications

To distribute a stand-alone application, you must include the application’s
executable as well as the shared libraries with which the application was
linked. The necessary shared libraries vary by platform. The individual UNIX
and Windows sections that follow provide more information about packaging
applications.
4-6
Getting Started
Introducing mbuild
The MathWorks utility, mbuild, lets you customize the configuration and build
process. The mbuild script provides an easy way for you to specify an options
file that lets you:
• Set your compiler and linker settings

• Change compilers or compiler settings
• Switch between C and C++ development
• Build your application
The MATLAB Compiler (mcc) automatically invokes mbuild under certain

conditions. In particular, mcc -m or mcc -p invokes mbuild to perform
compilation and linking. See the mcc reference page for complete details on
which Compiler options you should use in order to use the mbuild script.
If you do not want mcc to invoke mbuild automatically, you can use the -c
option. For example, mcc -mc filename.

Options files contain the required compiler and linker settings for your
particular C or C++ compiler. The MathWorks provides options files for every
supported C or C++ compiler. The options file for UNIX is mbuildopts.sh ; the
table, Compiler Options Files on the PC, contains the PC options files.
Much of the information on options files in this chapter is provided for those
users who may need to modify an options file to suit their specific needs. Many
users never have to be concerned with how the options files work.
Note If you are developing C++ applications, make sure your C++ compiler
supports the templates features of the C++ language. If it does not, you may
be unable to use the MATLAB C/C++ Math Library.
4-7
Building Stand-Alone Applications on UNIX

This section explains how to compile and link C or C++ source code into a
stand-alone UNIX application. This section includes:
• Configuring for C or C++

• Preparing to Compile
• Verifying mbuild
• Verifying the MATLAB Compiler
• Distributing Stand-Alone UNIX Applications
• About the mbuild Script
Configuring for C or C++

The mbuild script deduces the type of files you are compiling by the file
extension. If you include both C and C++ files, mbuild uses the C++ compiler
and the MATLAB C++ Math Library. If mbuild cannot deduce from the file
extensions whether to compile C or C++, mbuild invokes the C compiler. The
MATLAB Compiler generates only .c and .cpp files. This table shows the
supported file extensions.
Table 4-1: UNIX File Extensions for mbuild
Language Extension(s)
C .c
C++ .cpp
.C
.cxx
.cc
Note You can override the language choice that is determined from the
extension by using the -lang option of mbuild. For more information about
this option, as well as all of the other mbuild options, see the mbuild reference
page.
4-8

mbuild locates your options file by searching the following:

• $HOME/.matlab/R12
• <matlab>/bin
mbuild uses the first occurrence of the options file it finds. If no options file is
found, mbuild displays an error message.
Preparing to Compile
Note Refer to “Supported ANSI C and C++ UNIX Compilers” in Chapter 2

for information about supported compilers and important limitations.
Using the System Compiler

If the MATLAB Compiler and your supported C or C++ compiler are installed
on your system, you are ready to create C or C++ stand-alone applications. To
create a stand-alone C application, you can simply enter
mbuild filename.c
This simple method works for the majority of users. Assuming filename.c
contains a main function, this example uses the system’s compiler as your
default compiler for creating your stand-alone application. If you are a user
who does not need to change C or C++ compilers, or you do not need to modify
your compiler options files, you can skip ahead in this section to “Verifying
mbuild” on page 4-12. If you need to know how to change the options file or
select a different compiler, continue with this section.
Changing Compilers
Changing the Default Compiler. You need to use the setup option if you want to
change any options or link against different libraries. At the UNIX prompt type
mbuild -setup
4-9
The setup option creates a user-specific options file for your ANSI C or C++
compiler. Executing mbuild -setup presents a list of options files currently
included in the bin subdirectory of MATLAB.
mbuild -setup
Using the 'mbuild -setup' command selects an options file that is

placed in ~/.matlab/R12 and used by default for 'mbuild'. An
options file in the current working directory or specified on the
command line overrides the default options file in ~/.matlab/R12.
Options files control which compiler to use, the compiler and link
command options, and the runtime libraries to link against.
To override the default options file, use the 'mbuild -f' command
(see 'mbuild -help' for more information).
The options files available for mbuild are:
1: /matlab/bin/mbuildopts.sh :
Build and link with MATLAB C/C++ Math Library
Enter the number of the options file to use as your default options
file:
If there is more than one options file, you can select the one you want by
entering its number and pressing Return. If there is only one options file
available, it is automatically copied to your MATLAB directory if you do not
already have an mbuild options file. If you already have an mbuild options file,
you are prompted to overwrite the existing one.
Note The options file is stored in the .matlab/R12 subdirectory of your home
directory. This allows each user to have a separate mbuild configuration.
Using the setup option sets your default compiler so that the new compiler is
used everytime you use the mbuild script.
Modifying the Options File. Another use of the setup option is if you want to
change your options file settings. For example, if you want to make a change to
4-10
the current linker settings, or you want to disable a particular set of warnings,
you should use the setup option.
If you need to change the options that mbuild passes to your compiler or linker,
you must first run
mbuild -setup
which copies a master options file to your local MATLAB directory, typically
$HOME/.matlab/R12/mbuildopts.sh.
If you need to see which options mbuild passes to your compiler and linker, use
the verbose option, -v, as in
mbuild -v filename1 [filename2 …]
to generate a list of all the current compiler settings. To change the options, use
an editor to make changes to your options file,which is in your local matlab
directory. Your local matlab directory is a user-specific, MATLAB directory in
your individual home directory that is used specifically for your individual
options files. You can also embed the settings obtained from the verbose option
of mbuild into an integrated development environment (IDE) or makefile that
you need to maintain outside of MATLAB. Often, however, it is easier to call
mbuild from your makefile. See your system documentation for information on
writing makefiles.
Note Any changes made to the local options file will be overwritten if you
execute mbuild -setup . To make the changes persist through repeated uses of
mbuild -setup, you must edit the master file itself,
<matlab>/bin/mbuildopts.sh.
Temporarily Changing the Compiler. To temporarily change your C or C++ compiler,

use the -f option, as in
mbuild -f <file> …
The -f option tells the mbuild script to use the options file, <file>. If <file>
is not in the current directory, then <file> must be the full pathname to the
desired options file. Using the -f option tells the mbuild script to use the
specified options file for the current execution of mbuild only; it does not reset
the default compiler.
4-11
Verifying mbuild
There is C source code for an example ex1.c included in the <matlab>/extern/
examples/cmath directory, where <matlab> represents the top-level directory
where MATLAB is installed on your system. To verify that mbuild is properly
configured on your system to create stand-alone applications, copy ex1.c to
your local directory and type cd to change to that directory. Then, at the
MATLAB prompt, enter
mbuild ex1.c
This creates the file called ex1. Stand-alone applications created on UNIX
systems do not have any extensions.
Locating Shared Libraries

Before you can run your stand-alone application, you must tell the system
where the API and C shared libraries reside. This table provides the necessary
UNIX commands depending on your system’s architecture.
Architecture Command
HP700/HP-UX setenv SHLIB_PATH <matlab>/extern/lib/<arch>:$SHLIB_PATH
IBM RS/6000 setenv LIBPATH <matlab>/extern/lib/ibm_rs:$LIBPATH
All others setenv LD_LIBRARY_PATH <matlab>/extern/lib/<arch>:$LD_LIBRARY_PATH
where:
<matlab> is the MATLAB root directory
<arch> is your architecture (i.e., alpha, hp700, hpux, lnx86, sgi, sgi64, or sol2)
It is convenient to place this command in a startup script such as ~/.cshrc.

Then the system will be able to locate these shared libraries automatically
, and
you will not have to re-issue the command at the start of each login session.
Note On all UNIX platforms, the Compiler library is shipped as a shared

object (.so) file or shared library (.sl). Any Compiler-generated, stand-alone
application must be able to locate the C/C++ libraries along the library path
environment variable (SHLIB_PATH, LIBPATH, or LD_LIBRARY_PATH) in order to
be found and loaded. Consequently, to share a Compiler-generated,
4-12
stand-alone application with another user, you must provide all of the
required shared libraries. For more information about the required shared
libraries for UNIX, see “Distributing Stand-Alone UNIX Applications” on page
4-14.
Running Your Application

To launch your application, enter its name on the command line. For example,
ex1
ans =
1 3 5
2 4 6
ans =
1.0000 + 7.0000i 4.0000 +10.0000i

2.0000 + 8.0000i 5.0000 +11.0000i
3.0000 + 9.0000i 6.0000 +12.0000i
Verifying the MATLAB Compiler

There is MATLAB code for an example, hello.m, included in the <matlab>/
extern/examples/compiler directory . To verify that the MATLAB Compiler
can generate stand-alone applications on your system, type the following at the
MATLAB prompt.
mcc -m hello.m
This command should complete without errors. To run the stand-alone

application, hello, invoke it as you would any other UNIX application,
typically by typing its name at the UNIX prompt. The application should run
and display the message
Hello, World
When you execute the mcc command to link files and libraries, mcc actually
calls the mbuild script to perform the functions.
4-13
Distributing Stand-Alone UNIX Applications

To distribute a stand-alone application, you must create a package containing
these files:
• Your application executable.

• The contents, if any, of a directory named bin, created by mbuild in the same
directory as your application executable . Note: mbuild does not create a bin
directory for every stand-alone application.
• Any custom MEX-files your application uses.
• All the MATLAB Math run-time libraries.
For specific information about packaging these files, see “Distributing

Stand-Alone Applications” in the MATLAB C Math Library User’s Guide.
Note There is no support for the MATLAB C/C++ Graphics Library on the
IBM_RS platform.
Remember to locate the shared libraries along the LD_LIBRARY_PATH

(SHLIB_PATH on HP) environment variable so that they can be found and
loaded.
Installing C++ and Fortran Support

MATLAB users require access to both the C++ and Fortran run-time shared
libraries. These are usually provided as part of the operating system
installation. For Digital UNIX, however, the C++ shared libraries are part of
the base installation package, but the Fortran shared libraries are on a
separate disk called the “Associated Products CD.” MATLAB users running
under Digital UNIX should install both the C++ and Fortran run-time shared
libraries.
Note If you distribute an application created with the math libraries on

Digital UNIX, your users must have both the C++ and Fortran run-time
shared libraries installed on their systems.
4-14
Building Shared Libraries
Building Shared Libraries

You can use mbuild to build C shared libraries on both UNIX and the PC . All
of the mbuild options that pertain to creating stand-alone applications also
pertain to creating C shared libraries. To create a C shared library, specify one
or more files with the .exports extension. The .exports files are text files that
contain the names of the functions to export from the shared library, one per
line. You can include comments in your code by beginning a line (first column)
with # or a *. mbuild treats these lines as comments and ignores them. mbuild
merges multiple .exports files into one master exports list.
For example, given file1.exports as
times2
times3
and file1.c as
int times2(int x)
{
return 2 * x;
}
int times3(int x)
{
return 3 * x;
}
The command
mbuild file1.c file1.exports
creates a shared library named file1.ext, where ext is the

platform-dependent shared library extension.For example, on the PC, it would
be called file1.dll. The shared library exports the symbols times2 and
times3.
4-27
Coding with M-Files Only

One way to create a stand-alone application is to write all the source code in
one or more M-files or MEX-files. Coding an application in M-files allows you
to take advantage of MATLAB’s interpretive development environment.Then,
after getting the M-file version of your program working properly, compile the
code and build it into a stand-alone application.
Note It is good practice to avoid manually modifying the C or C++ code that
the MATLAB Compiler generates. If the generated C or C++ code is not to
your liking, modify the M-file (and/or the compiler options) and then
recompile. If you do edit the generated C or C++ code, remember that your
changes will be erased the next time you recompile the M-file. For more
information, see “Compiling MATLAB Provided M-Files Separately” on page
4-35 and “Interfacing M-Code to C/C++ Code” in Chapter 5.
Consider a very simple application whose source code consists of two M-files,
mrank.m and main.m. This example involves C code; you use a similar process
(described below) for C++ code. In this example, the line r = zeros(n,1)
preallocates memory to help the performance of the Compiler.
mrank.m returns a vector of integers, r. Each element of r represents the rank
of a magic square. For example, after the function completes, r(3) contains the
rank of a 3-by-3 magic square.
function r = mrank(n)
r = zeros(n,1);
for k = 1:n
r(k) = rank(magic(k));
end
main.m contains a “main routine” that calls mrank and then prints the results
function main
r = mrank(5)
To compile these into code that can be built into a stand-alone application
,
invoke the MATLAB Compiler.
mcc -mc main mrank
4-31
The -m option flag causes the MATLAB Compiler to generate C source code
suitable for stand-alone applications. For example, the MATLAB Compiler
generates C source code files main.c, main_main.c, and mrank.c. main_main.c
contains a C function named main; main.c and mrank.c contain a C functions
named mlfMain and mlfMrank. (The -c option flag inhibits invocation of
mbuild. )
To build an executable application, you can use mbuild to compile and link
these files.Or, you can automate the entire build process (invoke the MATLAB
Compiler twice, use mbuild to compile the files with your ANSI C compiler, and
link the code) by using the command
mcc -m main mrank
This figure illustrates the process of building a stand-alone C application from

two M-files. The commands to compile and link depend on the operating system
being used. See “Building Stand-Alone C/C++ Applications” on page 4-5 for
details.
4-32
main.m mrank.m
mcc -W main -t main mcc -t mrank.m
mbuild does main_main.c main.c mrank.c

this part.
C Compiler C Compiler
Object File Object File
MATLAB M-File Math Library MATLAB API Library
MATLAB Math Built-In Library MATLAB Utility Library

ANSI C Library MATLAB C/C++ Graphics Library
• Shaded blocks are user-written code.

Linker • Shadowed blocks are tools.
• Unshaded blocks are MATLAB
Stand-Alone • Dotted block s are C/C++
C Application compiler-generated executable.
Figure 4-2: Building Two M-Files into a Stand-Alone C Application
4-33
Mixing M-Files and C or C++
Mixing M-Files and C or C++

The examples in this section illustrate how to mix M-files and C or C++ source
code files:
• The first example is a simple application that mixes M-files and C code.
• The second example illustrates how to write C code that calls a compiled
M-file.
One way to create a stand-alone application is to code some of it as one or more

function M-files and to code other parts directly in C or C++. To write a
stand-alone application this way, you must know how to:
• Call the external C or C++ functions generated by the MATLAB Compiler.

• Handle the results these C or C++ functions return.
Note If you include compiled M code into a larger application, you must
produce a library wrapper file even if you do not actually create a separate
library. For more information on creating libraries, see the library sections in
“Supported Executable Types” in Chapter 5.
Simple Example
This example involves mixing M-files and C code. Consider a simple
application whose source code consists of mrank.m and mrankp.c.
mrank.m
mrank.m contains a function that returns a vector of the ranks of the magic
squares from 1 to n.
function r = mrank(n)
r = zeros(n,1);
for k = 1:n
r(k) = rank(magic(k));
end
4-37
mcc
would be equivalent to
mcc -m -I /home/user/dir1 -I /home/user/dir2 myfile.m
The Compiler finds the myfile.m in dir1 and compiles it instead of the one in
dir2 because of the behavior of the -I option. If you are concerned that this
might be happening, you can specify the -v option and then see which M-file
the Compiler parses. The -v option prints the full pathname to the M-file.
Note The Compiler produces a warning (specified_file_mismatch) if a file

with a full pathname is included on the command line and it finds it
somewhere else.
Compiling Embedded M-Files

If the M-file you are compiling calls other M-files, you can list the called M-files
on the command line. Doing so causes the MATLAB Compiler to build all the
M-files into a single MEX-file, which usually executes faster than separate
MEX-files . Note, however, that the single MEX-file has only one entry point
regardless of the number of input M-files. The entry point is the first M-file on
the command line. For example, suppose that bell.m calls watson.m.
Compiling with
mcc -x bell watson
creates bell.mex. The entry point of bell.mex is the compiled code from
bell.m. The compiled version of bell.m can call the compiled version of
watson.m. However, compiling as
mcc -x watson bell
creates watson.mex. The entry point of watson.mex is the compiled code from
watson.m. The code from bell.m never gets executed.
As another example, suppose that x.m calls y.m and that y.m calls z.m. In this
case, make sure that x.m is the first M-file on the command line.After x.m, it
does not matter which order you specify y.m and z.m.
7-35
A MATLAB Compiler Quick Reference
Common Uses of the Compiler

This section summarizes how to use the MATLAB Compiler to generate some
of its more standard results. The first four examples take advantage of the
macro options.
Create a MEX-File. To translate an M-file named mymfile.m into C and to create

the corresponding C MEX-file that can be called directly from MATLAB, use
mcc -x mymfile
Create a Simulink S-Function. To translate an M-file named mymfile.m into C and

to create the corresponding Simulink S-function using dynamically sized
inputs and outputs, use
mcc -S mymfile
Create a Stand-Alone C Application. To translate an M-file named mymfile.m into C

and to create a stand-alone executable that can be run without MATLAB, use
mcc -m mymfile
Create a Stand-Alone C++ Application. To translate an M-file named mymfile.m

into C++ and to create a stand-alone executable that can be run without
MATLAB, use
mcc -p mymfile
Create a Stand-Alone C Graphics Library Application. To translate an M-file named

mymfile.m that contains Handle Graphics functions into C and to create a
stand-alone executable that can be run without MATLAB, use
mcc -B sgl mymfile
Create a Stand-Alone C++ Graphics Library Application. To translate an M-file named

mymfile.m that contains Handle Graphics functions into C++ and to create a
stand-alone executable that can be run without MATLAB, use
mcc -B sglcpp mymfile
Create a C Library. To create a C library, use

mcc -m -W lib:libfoo -T link:lib foo.m
A-2
Create a C++ Library. To create a C++ library, use
mcc -p -W lib:libfoo -T compile:lib foo.m
Create a C Shared Library. To create a C shared library that performs specialized

calculations that you can call from your own programs, use
mcc -W lib:mylib -L C -t -T link:lib -h Function1 Function2 …
Create MATLAB P-Code. To translate an M-file named mymfile.m into MATLAB

P-code, use
mcc -B pcode mymfile
Note You can add the -g option to any of these for debugging purposes.
A-3
The C/C++ Math Library serves two user
groups: MATLAB programmers who have
developed an application or algorithm and
MATH LIBRARY KEY FEATURES
want to convert their M-file to C/C++ and ■ Familiar Syntax and Matrix Manipulation Support
programmers working in C and C++ who The library supports a C++ syntax that is very similar to MATLAB code, making
need a fast, easy-to-use matrix math library. it intuitive for both MATLAB and C++ programmers. You operate on matrices in
The MATLAB C/C++ Math Library component C++ as you would in MATLAB.
is a compiled version of the math functions ■ Optimized Performance
that reside within MATLAB. The library By eliminating interpretive overhead and managing memory efficiently, C++
contains advanced math functionality ranging code built with the MATLAB Compiler may run significantly (up to 20 times)
from fast Fourier transforms and singular faster than equivalent M-file functions.
value decompositions to random number
generators that are callable from C or C++. ■ Automatic Memory Management
The library code allocates and frees memory automatically, improving
The library is divided into three parts: The performance and preventing memory leaks.
C++ interface functions provided via the
mwArray class, a set of binary and unary ■ MATLAB Speed and Accuracy
mathematical operators, and the MATLAB The C/C++ Math Library routines have been carefully tuned for accuracy
math functions. With its ease of use and large and speed. All computations use double-precision (64-bit), floating-point
number of functions, the C/C++ Math arithmetic. All functions allow you to operate on scalars, vectors, and
Library makes it easy to create solutions that matrices with equal ease.
require less than a page of code—much less
than the equivalent C/C++ solution would
require. Short programs mean easier
maintenance and time savings.
The library provides a natural interface

and many powerful math functions for Using the C/C++ Math Library to Developing from Scratch in C/C++
programming in C++. Develop Applications You can build stand-alone applications
Building stand-alone applications with the from beginning to end that embed calls
The intuitive syntax of MATLAB lets you
C/C++ Math Library is a straightforward to the MATLAB math functions while
program the way you think. This same flexibility
process. You can bind the library files statically excluding compiled M-files. You develop
is available to C++ programmers. Using the
into your program on UNIX or include them your code from scratch in C or C++ and
library’s matrix class objects and math
as shared DLL libraries in Windows. link it against the C/C++ Math Library.
functions, MATLAB M-file programmers can
write C++ code that looks like M-file code but
runs significantly faster. They can apply their
Building Stand-Alone Applications
knowledge of M-file programming and become
from MATLAB
When you issue the mcc -p or mcc -m
productive using this library very quickly.
command, you initiate the following steps
to generate a stand-alone application:
C/C++ Math Library Functions
The C/C++ Math Library contains more 1. The MATLAB Compiler converts the
than 600 MATLAB math functions. All
functions allow you to operate on scalars,
M-file into C or C++.
Functions Overview
2. The source code is compiled into object
vectors, and matrices with equal ease and For a list of functions see the Sample
code using a C++ system compiler.
simplicity of syntax. C/C++ Math Library Functions section
3. The resulting code is linked against the provided in this datasheet.
C/C++ Math Library and any
application-specific files.
Sample C/C++ Math Library Functions
Elementary and Specialized Functions Algebraic and Logical Operators

• Beta, elliptic, error, and gamma functions • Array and matrix add, subtract, multiply, divide, power
• Coordinate system transforms • Noncomplex transpose
• Identity and other elementary matrices • Logical AND, OR, NOT, XOR
• Hadamard, Hilbert, Toeplitz, Vandermonde, and other
specialized matrices Utility and Matrix Access Functions
• Real part, imaginary part, complex conjugate • Error handling
• Trigonometric, power, and other elementary functions • Formatted and unformatted file I/O
• Fortran data type conversion
Numeric Linear Algebra • Matrix creation, access, indexing, and destruction
• Eigenvalues and matrix decomposition • Number/string conversion
• Evaluate general matrix function • Sort, resize, and reshape matrices
• Matrix determinant, norm, rank, condition number • Time and date functions
• Matrix inverse and factorization
• Matrix exponential, logarithm, square root MAT-file Access
• Reduced row echelon form • Save variables to MAT-file
• Load variables from MAT-file
Polynomials and Interpolation
• 1-D and 2-D interpolation (table lookup) Functions For Programming In C++
• Construct polynomials The C++ Math Library provides overloaded C++ operators that
• Cubic spline interpolation enable you to use MATLAB’s natural mathematical syntax from C++.
• Data gridding Functions include:
• Differentiate polynomials
• Evaluate polynomials C++ Arithmetic Operators
• Multiply and divide polynomials • Matrix multiplication
• Polynomial residues and roots • Array addition and subtraction
• Matrix division
Numerical Methods Nonlinear • Matrix power
• Find zero of function of one variable
• Minimize function of one or more variables C++ Binary Relational Operators
• Numeric evaluation of integrals • Less than and greater than
• Numeric solution of ordinary differential equations • Less than or equal, greater than or equal
• Equal and not equal
Statistics, Data Analysis, and Fourier Analysis
• 1-D and 2-D convolution C++ Boolean Operators
• 1-D and 2-D digital filter • or
• 1-D and 2-D FFT and inverse • and
• Correlation coefficients and covariance matrix • not
• Deconvolution
• Difference function and approximate derivative C++ Indexing Operators
• Magnitude, phase angle • Multidimensional indexing and assignment
• Max, min, sum, mean, and other basic statistics • General array assignment
Ordinary Differential Equations Array Construction Functions

• Stiff and nonstiff solvers • Horizontal concatenation
• Low, medium, and variable order methods • Vertical concatenation
MATLAB C Math Library
®
Computation
Visualization
Programming
User’s Guide
Version 2.1
1 Getting Started
Introduction
The MATLAB ® C Math Library makes the mathematical core of MATLAB
available to application programmers. The library is a collection of more than
400 mathematical routines written in C. Programs written in any language
capable of calling C functions can call these routines to perform mathematical
computations.
The MATLAB C Math Library is based on the MATLAB language. The
mathematical routines in the MATLAB C Math Library are C callable versions
of features of the MATLAB language . However, you do not need to know
MATLAB or own a copy of MATLAB to use the MATLAB C Math Library. If
you have purchased the MATLAB C Math Library, then the only additional
software you need is an ANSI C compiler. In addition, you may freely distribute
applications you develop with the MATLAB C Math Library.
Who Should Read This Book

This book assumes that you are familiar with general programming concepts
such as function calls, variable declarations, and flow of control statements.
You also need to be familiar with the general concepts of C and linear algebra.
The audience for this book is C programmers who need a matrix math library
or MATLAB programmers who want the performance of C. This book will not
teach you how to program in either MATLAB or C.
MATLAB C Math Library Features

Version 2.1 of the library provides the following new features:
• Support for the eval function for expressions that do not contain variables
• Support for the input function with the same restrictions as eval
• Performance enhancements in the core numerical routines
1-2
Introduction
Note Existing Version 2.0 hand-written source code is compatible with the
Version 2.1 libraries, but you must recompile your code. Additionally, any
M-files which were compiled with Version 2.0 of the MATLAB Compiler must
be recompiled with Version 2.1 of the MATLAB Compiler before using them
with the Version 2.1 libraries. If you do not recompile your program, it will
produce a runtime error.
Unsupported MATLAB Features

The library does not include any Handle Graphics ® or Simulink® functions.
For information about compiling an application that uses graphics functions,
see the MATLAB C/C++ Graphics Library User’s Guide.
In addition, the library does not support MATLAB objects
Library Routine Naming Convention

All routines in the MATLAB C Math Library begin with the prefix mlf .
The name of every routine in the MATLAB C Math Library is derived from the
corresponding MATLAB function . For example, the MATLAB function sin is
represented by the MATLAB C Math Library function mlfSin. The first letter
following the mlf prefix is always capitalized.
MATLAB C Math Library Documentation

The documentation for the library includes:
• MATLAB C Math Library User’s Guide—This manual provides tutorial

information about the library. This manual is also available in PDF format,
accessible through MATLAB Help.
• MATLAB C Math Library Reference—The reference pages for all the
MATLAB C Math library routines are available in HTML and PDF versions,
accessible through MATLAB Help.
How This Book Is Organized

This chapter provides an introduction to the MATLAB C Math Library and
tells how to install it. The remainder of the book is organized as follows:
1-3
2
Writing and Building
Programs
Introduction . . . . . . . . . . . . . . . . . . . . 2-2
Example – Writing a Simple Program . . . . . . . . . . 2-2
Building Stand-Alone C Applications . . . . . . . . 2-7

Overview . . . . . . . . . . . . . . . . . . . . . . 2-7
Building UNIX Applications . . . . . . . . . . . . 2-9

Configuring the Build Environment . . . . . . . . . . . 2-9
Building an Application . . . . . . . . . . . . . . . . 2-12
mbuild Options . . . . . . . . . . . . . . . . . . . 2-14
Building Microsoft Windows Applications . . . . . . 2-17

Configuring the Build Environment . . . . . . . . . . . 2-17
Building an Application . . . . . . . . . . . . . . . . 2-23
mbuild Options . . . . . . . . . . . . . . . . . . . 2-24
Distributing Stand-Alone Applications . . . . . . . . 2-27

Packaging the MATLAB Math Run-Time Libraries . . . . . 2-27
Installing Your Application . . . . . . . . . . . . . . 2-28
Problem Starting Stand-Alone Application . . . . . . . . 2-29
Building Shared Libraries . . . . . . . . . . . . . 2-30
Troubleshooting mbuild . . . . . . . . . . . . . . 2-31
Linking Applications Without mbuild . . . . . . . . 2-33

2 Writing and Building Programs
Introduction
This section presents a simple example program that introduces C Math
Library programming concepts and describes how to compile and link a C
application with the libraries.
Example – Writing a Simple Program

This example application determines if two numbers are relatively prime; that
is, the numbers share no common factors. While its function is trivial, the
application serves well as an introduction to programming in C with the
MATLAB C Math Library. The notes following the example highlight points of
particular interest in the example and provide pointers to other sections in the
documentation where specific topics are covered in more detail.
The source code for this example, named intro.c, is in the
<matlab>/extern/examples/cmath directory on UNIX systems, and in the
<matlab>\extern\examples\cmath directory on PCs , where <matlab>
represents the top-level directory of your installation. See “Building
Stand-Alone C Applications” on page 2-7 for information on building the
examples.
2-2
Introduction
/* intro.c*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
1 #include "matlab.h"
int main()
{
double num1, num2;
2 mxArray *volatile factors1 = NULL;
mxArray *volatile factors2 = NULL;
mxArray *volatile common_factors = NULL;
3 mlfEnterNewContext(0,0);
4 printf("Enter a number: ");

scanf("%lf", &num1);
printf("Enter a second number: ");
scanf("%lf", &num2);
mlfTry
{
mlfAssign(&factors1, mlfFactor(mlfScalar(num1)));
6
mlfAssign(&factors2, mlfFactor(mlfScalar(num2)));
7 mlfAssign(&common_factors,
mlfIntersect(NULL, NULL, factors1, factors2, NULL));
if (mlfTobool(mlfIsempty(common_factors)))
8 printf("%0.0lf and %0.0lf are relatively prime\n",
num1, num2);
else
{
printf("%0.0lf and %0.0lf share common factor(s):",
num1, num2);
mlfPrintMatrix(common_factors);
}
9 } /* end mlfTry */
mlfCatch
2-3
{
mlfPrintf("In catch block: \n");
mlfPrintMatrix(mlfLasterr(NULL));
}
mlfEndCatch
10 mxDestroyArray(factors1);
mxDestroyArray(factors2);
mxDestroyArray(common_factors);
11 mlfRestorePreviousContext(0,0);
return(EXIT_SUCCESS);
}
The numbered items in the list below correspond to the numbered sections of
code example:
1 Applications must include the file"matlab.h" which contains the

declaration of the mxArray data structure and the prototypes for all the
functions in the library. stdlib.h contains the definition of EXIT_SUCCESS.
2 Applications must declare pointers to any MATLAB arrays (mxArray *)

explicitly used as variables. All arguments to MATLAB routines must be
MATLAB arrays. In addition, the routines return newly allocated MATLAB
arrays as output. These pointers are declared as volatile pointers because
they are assigned values within a try block and so may change without
warning due to an error. For more information about working with
MATLAB arrays in C programs, see Chapter 3.
3 Applications must enable MATLAB C Math Library automated memory

management by calling mlfEnterNewContext() . With the library memory
management facility enabled, the library can delete the arrays it creates
automatically. This allows you to compose functions; that is, nest one
function call within another. For more information about automated
memory management, see Chapter 4.
4 Applications can define a try block using the MATLAB C Math library
macro, mlfTry. When a library function included in a try block encounters a
run-time error, it outputs an error message and then passes control to a
catch block in the program. In a catch block, an application can free arrays
that have been assigned to variables or perform other processing before
2-4
Introduction
exiting. For more information about defining try and catch blocks, see “Error
Handling Overview” on page 8-3.
5 This call to mlfScalar(), which converts the number input by the user from
an integer to a MATLAB array, illustrates routine nesting. The application
can use nesting because it only uses the array returned by mlfScalar() as
input to mlfFactor(). With automated memory management enabled, the
library frees the array after mlfFactor() is finished using it.
In contrast, because the example uses the array returned by mlfFactor()

several times, it assigns this array to a variable, factors1, using the
mlfAssign() routine. Any array that you assign to a variable, you must also
free, using mxDestroyArray(). (Arrays returned as output arguments by
library routines are implicitly assigned to the variables by the library and
must also be destroyed.) For more information about assigning arrays to
variables, see Chapter 4.
6 This call to mlfIntersect() illustrates how to call library routines that

optional input arguments. The C Math library version of these functions
include in their signatures all optional input and output arguments. If you
do not use these optional arguments, you must pass NULL in their place. For
more information about calling MATLAB C Math library routines, see
Chapter 6.
7 The routine mlfIsempty() returns an array containing the value 1 (TRUE) if

the array is empty and zero (FALSE) if the array contains data. However,
because mlfIsempty() returns these values as MATLAB arrays, you cannot
use the return value directly in the if statement. Instead, pass this return
value to the mlfTobool() routine, which converts the return value to a
standard C Boolean value.
You can also access individual elements in an array using standard

MATLAB indexing syntax; however, the values returned by indexing are
MATLAB arrays, not scalar values. For more information about indexing
into arrays, see Chapter 5.
8 This call to the mlfCatch macro defines the start of the application’s catch
block. The call to the mlfEndCatch macro defines the end of the catch block.
Catch blocks contain error handling code. This sample catch block calls the
mlfLasterr() routine to retrieve the text of the error message associated
2-5
with the last error and then outputs the message to the user. For more
information about handling errors with try and catch blocks, see Chapter 8.
9 The application frees the MATLAB arrays that were assigned to variables
using mlfAssign(). The library automatically frees arrays that were not
assigned to variables. For example, the arrays returned by the nested calls
to mlfScalar() are deleted automatically. The arrays assigned to factors1
and factors2 are not deleted automatically. For more information about
assigning an array to a variable using the mlfAssign() routine, see Chapter
4.
10 The sample application ends by disabling automated memory management

using the mlfRestorePreviousContext(). For more information about
enabling automated memory management, see Chapter 4.
Output
This sample program, when run in a DOS Command Prompt window, produces
the following output:
Enter a number: 333
Enter a second number: 444

333 and 444 share common factor(s): 3 37
A second run illustrates the alternate output:

Enter a number: 11
Enter a second number: 4

11 and 4 are relatively prime
2-6
Building Stand-Alone C Applications
Building Stand-Alone C Applications

After you write your C code, you must compile and link it to create your C
application. The section:
• Provides an overview of the compiling and linking process, introducing the

MATLAB mbuild utility.
• Explains how to build stand-alone C applications on UNIX systems
• Explains how to build stand-alone C applications on PCs running Microsoft
Windows.
• Describes how to build shared libraries
• Details the libraries with which you must link your C application if you do
not use the mbuild utility.
Note You may freely distribute applications you develop with the MATLAB C
Math Library.
Packaging Stand-Alone Applications

To distribute a stand-alone application, you must include the application’s
executable as well as the shared libraries with which the application was
linked. The necessary shared libraries vary by platform and are listed within
the individual UNIX and Windows sections that follow.
Overview
To build a stand-alone application using the MATLAB C Math Library, you
must supply your ANSI C compiler with the correct set of compiler and linker
options (or switches). To help you, The MathWorks provides a command line
utility called mbuild . The mbuild script makes it easy to:
• Set your compiler and linker settings

• Change compilers or compiler settings
• Switch between C and C++ development
• Build your application
2-7
On UNIX and Microsoft Windows systems, follow these steps to build C

applications with mbuild:
1 Verify that mbuild can create stand-alone applications.
2 Build your application.
You only need to reconfigure if you change compilers or upgrade your current
compiler.

mbuild stores compiler and linker settings in an options file. Options files
contain the required compiler and linker settings for your particular C
compiler. The MathWorks provides options files for every supported C
compiler.
Much of the information on options files in this chapter is provided for those
users who may need to modify an options file to suit their specific needs. Many
users never have to be concerned with how the options files work.
2-8
Building UNIX Applications
mbuild [-options] filename1 [filename2 …]
Table 2-2: mbuild Options on UNIX
Option Description
-c Compile only; do not link.

-D<name>[=<def>] Define C preprocessor macro <name> [as having
value <def>].
-f <optionsfile> Use <file> to override the default options file;
<file> is a full pathname if it is not in the current
directory.
-g Build an executable with debugging symbols
included.
-h[elp] Help; prints a description of mbuild and the list of
options.
-I<pathname> Include <pathname> in the list of directories to
search for header files.
-inline Inlines matrix accessor functions (mx*). The
generated MEX function may not be compatible with
future versions of MATLAB.
-l<file> Link against library lib<file>.
-L<pathname> Include <pathname> in the list of directories to
search for libraries.
-lang <language> Override language choice implied by file extension.
<language> = c for C
cpp for C++
This option is necessary when you use an
unsupported file extension, or when you pass all .o
files and libraries.
2-15
Table 2-2: mbuild Options on UNIX (Continued)
Option Description
<name>=<def> Override options file setting for variable <name>. If

<def> contains spaces, enclose it in single quotes, for
example, CFLAGS='opt1 opt2'. The definition,
<def>, can reference other variables defined in the
options file. To reference a variable in the options
file, prepend the variable name with a $,
for example, CFLAGS='$CFLAGS opt2'.
-n No execute flag. Using this option displays the
commands that compile and link the target but does
not execute them.
-outdir Place any generated object, resource, or executable
<dirname> files in the directory <dirname>. Do not combine this
option with -output if the -output option gives a
full pathname.
-output <name> Create an executable named <name>. (An appropriate
executable extension is automatically appended.)
-O Build an optimized executable.
-setup Set up the default compiler and libraries. This option
should be the only argument passed.
-U<name> Undefine C preprocessor macro <name>.
-v Verbose; print all compiler and linker settings.
2-16
Distributing Stand-Alone Applications
Distributing Stand-Alone Applications

You may freely distribute applications you develop with the MATLAB C Math
Library, subject to The MathWorks software license agreement. When you
package your application for distribution, remember to include, along with
your application executable, these additional files
:
directory as your application executable
• Any custom MEX files your application uses
• All the MATLAB math run-time libraries
To make packaging an application easier, the C Math Library has prepackaged

all the necessary MATLAB run-time libraries into a single, self-extracting
archive file. For more information about how you can use this archive, see
“Packaging the MATLAB Math Run-Time Libraries”. For information about
how customers who receive your application can use this archive, see
“Installing Your Application” on page 2-28.
Packaging the MATLAB Math Run-Time Libraries

The MATLAB C Math library has prepackaged all the MATLAB run-time
libraries required by stand-alone applications into a single, self-extracting
archive file, called the MATLAB Math and Graphics Run-Time Library
Installer . Instead of including all the run-time libraries individually in your
stand-alone application distribution package, you can simply include this
archive file.
The following table lists the name of the archive file for both PCs and UNIX
systems. In the table $MATLAB represents your MATLAB installation directory
and $ARCH represents your UNIX platform.
Platform MATLAB Math and Graphics Run-Time Library Installer
UNIX systems $MATLAB/extern/lib/$ARCH/mglinstaller
PCs $MATLAB\extern\lib\win32\mglinstaller.exe
2-27
Installing Your Application

To install your application, your customers must:
• Run the MATLAB Math and Graphics Run-Time Library Installer . This
program extracts the libraries from the archive and installs them in
subdirectories of a directory specified by the user.
• Add the bin/$ARCH subdirectory to their path . This is the only MATLAB
Math and Graphics Run-time library subdirectory that needs to be added to
the path.
Note If a customer already has the MATLAB math and graphics run-time
libraries installed on their system, they do not need to reinstall them. They
only need to ensure that the library search path is configured correctly.
On UNIX Systems
On UNIX systems, your customer runs the MATLAB Math and Graphics
Run-Time Library Installer by executing the mglinstaller command at the
system prompt. Your customer can specify the name of the directory into which
they want to install the libraries. By default, the installer puts the files in the
current directory.
After the installer unpacks and uncompresses the libraries, your customers
must add the name of the bin/$ARCH subdirectory to the LD_LIBRARY_PATH
environment variable. (The equivalent variable on HP-UX systems is the
SHLIB_PATH and LIBPATH on IBM AIX systems.)
For example, if a customer working on a Linux system specifies the installation

directory mgl_runtime_dir, then they must add
mgl_runtime_dir/bin/glnx86 to the LD_LIBRARY_PATH environment variable.
On PCs
On PCs, your customer can run the MATLAB Math and Graphics Run-Time
Library Installer by double-clicking on the mglinstaller.exe file. Your
customer can specify the name of the directory into which they want to install
the libraries. By default, the installer puts the files in the current directory.
must add the bin\win32 subdirectory to the system path variable (PATH).
2-28
MATLAB C/C++ Graphics Library
The MATLAB C/C++ Graphics Library
component is a collection of approximately
350 graphics routines that work with the GRAPHICS LIBRARY KEY FEATURES
MATLAB C/C++ Math Library. By using
■ MATLAB 2-D and 3-D plot types, such as scatter, line, bar,
the Graphics Library with the MATLAB
pie, polar, surface, mesh, contour, area, stem, and
Compiler and the MATLAB C/C++ Math
quiver
Library, you automatically convert programs
that create MATLAB GUIs, graphics, and ■ MATLAB GUI controls, such as dialog boxes, radio buttons, menus,
images to C and C++ code. frames, list boxes, sliders, edit fields, and pop-up menus
■ MATLAB image displays—lighting and shading of 3-D surfaces,

rotate, zoom, and scroll plots
■ Graphics print-out capability
■ z-buffer or Painter’s algorithm rendering
Functions Overview
Basic Functions
The library allows you to compile M-files containing basic graphics
functions such as set, get, figure, colormap, gcf, gca, and
axes, which are commonly used for MATLAB 2-D, 3-D, GUI, and other
figure-based graphics.
Advanced Graphics Functions

The library also contains higher-level 2-D and 3-D graphics functions
such as plot, surface, image, light, line, axis, legend,
polar, zoom, and view that you can use for general analysis,
visualization, and scientific reports. Functions for lighting 3-D surfaces in
MATLAB are included in the library to provide the same high quality
surface and image resolution in your C and C++ code.
GUI Functions
Library functions such as uicontrol, uimenu, uigetfile,
uisetcolor, and uiputfile make it possible to compile applications
that contain GUI controls. These functions allow you to create C and
C++ applications that include MATLAB GUIs.
A plot of surface normals for the function
Additional Functions z=xe(-x2-y2) compiled using the MATLAB
The Graphics Library allows you to compile 105 additional MATLAB Compiler and the C/C++ Math and
graphics M-file functions not already included in the library. For example
Graphics Libraries.
the Graphics Library provides the core functionality necessary to compile
functions such as surf, bar, stem, and quiver.

MATLAB C/C++
Graphics Library
Computation
Visualization
Programming
User’s Guide
Version 2
1 Introduction
The MATLAB ® C/C++ Graphics Library is a collection of MATLAB graphics

routines distributed as a single library. The graphics library makes the
MATLAB plotting and visualization capabilities available to stand-alone C and
C++ applications.
A stand-alone C or C++ application is an executable program that can run
independently of the MATLAB interpreted environment. Stand-alone
applications are a convenient way to package and distribute custom MATLAB
applications.
Using the graphics library with the MATLAB Compiler and the MATLAB
C/C++ Math Library, you can compile M-files that include lines, text, meshes,
and polygons, as well as graphical user interface (GUI) components such as
menus, push buttons, and dialog boxes.
Note You may freely distribute applications you develop with the MATLAB
C/C+ Graphics Library, subject to The MathWorks software license
agreement.
This chapter includes the following topics:
• “Components of the MATLAB C/C++ Graphics Library”

• “Restrictions” on page 1-6
• “System Requirements” on page 1-9
After reading these sections, see “Configuring the MATLAB C/C++ Graphics
Library” on page 1-10.
1-2
Components of the MATLAB C/C++ Graphics Library
Components of the MATLAB C/C++ Graphics Library

The MATLAB C/C++ Graphics Library contains more than 100 routines,
including:
• MATLAB 6.0 built-in graphics functions, such as surf, plot, get, and set
• Some commonly used MATLAB 6.0 M-file graphics functions, such as
newplot, gcf, gca, gco, and gcbf
Note The MATLAB C/C+ Graphics Library includes only a subset of

MATLAB M-file graphics functions. If you application includes graphics
functions that are not included in the library, the MATLAB Compiler will
compile them when it creates your application.For information about
MATLAB features that are not supported by the Graphics Library, see
“Restrictions” on page 1-6.
Files Installed on PCs

Table 1-1 lists the shared libraries (DLLs), include files, and other files
installed on a PC as part of a MATLAB C/C++ Graphics Library installation.
In the table, <MATLAB> stands for your top-level MATLAB installation
directory.
For more information about the installation process, read the Installation
Guide for PC, available in PDF format from the MathWorks Web site. Click on
the Documentation link and go to the Online Manuals page to find the
documentation in PDF format.
Note On PCs, the MATLAB C/C++ Graphics Library installation includes

new versions of several standard MATLAB dynamic link libraries (DLLs).
1-3
1 Introduction
Restrictions
The MATLAB C/C++ Graphics Library supports most MATLAB 6.0 features,
including multidimensional arrays, cell arrays, and structures. However, there
are some MATLAB features the graphics library does not support, including:
• MATLAB objects
• MATLAB Java objects
• plotedit command
• propedit command
In addition to these restrictions, the graphics library provides limited support

for certain callback coding practices.
Note The graphics library is subject to the same limitations as the MATLAB
Compiler. For example, MATLAB functions that require the MATLAB
interpreter, most notably eval() and input(), are not fully supported. See the
MATLAB Compiler documentation for information about their restrictions.
Graphics Library Printing Support

If your application uses default print command settings, it should require no
modification. The default print command sends the current figure to whatever
printer has been set up as the default printer on the system on which your
application is running. However, if your application uses print command
switches to specify device drivers and other options, be aware that the graphics
library supports only a subset of these switches.
For example, the graphics library supports most of the MATLAB built-in
drivers, such as the PostScript drivers, but it does not support any of the
Ghostscript drivers.
1-6
1 Introduction
Configuring the MATLAB C/C++ Graphics Library

After installing the MATLAB C/C++ Graphics Library, you should configure it
using the mbuild -setup command . When you run mbuild, you specify:
• The ANSI C or C++ compiler you intend to use to compile the code generated
by the MATLAB Compiler
• The libraries you want to link your application with; specifically, the
MATLAB C/C++ Math Library alone, or the math library and the MATLAB
C/C++ Graphics Library together.
This section includes the following topics:
• Configuring the Graphics Library on PCs

• “Configuring the Graphics Library on UNIX Systems” on page 1-12
After configuring the graphics Library, see Chapter 2, “Creating Stand-Alone

Graphics Applications”, to learn how to use it to build a stand-alone graphics
application.
Configuring the Graphics Library on PCs

To configure the graphics library on a PC running Microsoft Windows, run the
mbuild -setup command. You can run mbuild at the MATLAB prompt or in a
DOS Command Prompt window.
mbuild uses options files to specify all the compile and link command line
options necessary to create a stand-alone graphics application using a
particular compiler. When you configure the graphics library, you determine
which options file mbuild uses to create stand-alone applications.
When you run mbuild, you specify the name and version of the compiler you
intend to use. mbuild locates the options file specific to that compiler, and
creates a copy of it in your system’s user profiles directory. From then on,
whenever the MATLAB Compiler calls mbuild to invoke your C or C++
compiler, it uses this local copy of the options file.
This example illustrates how to specify a compiler running mbuild -setup on
a PC. mbuild can also determine the name and location of your C or C++
compiler automatically.
1-10
2
Creating Stand-Alone
Graphics Applications
Overview . . . . . . . . . . . . . . . . . . . . . 2-3
Building a Stand-Alone Graphics Application . . . . . 2-5

Building Graphics Applications on a PC . . . . . . . . . 2-5
Building Graphics Applications on a UNIX System . . . . . 2-7
Running the MATLAB Compiler Outside MATLAB . . . . 2-9
Compiling and Linking Without mbuild . . . . . . . . . 2-9
Changes in Run-Time Behavior and Appearance . . . 2-11

Changes to Figure Window Menu Bar Options . . . . . . . 2-11
Changes to the Figure Window File Menu Options . . . . . 2-13
Accessing Help in Stand-Alone Applications . . . . . . . . 2-13
Ctrl+C Handling . . . . . . . . . . . . . . . . . . . 2-13
Distributing Stand-Alone Graphics Applications . . . 2-14

Packaging the MATLAB Run-Time Libraries . . . . . . . 2-14
Installing Your Application . . . . . . . . . . . . . . 2-15
Overview
Overview
You use the MATLAB Compiler (mcc) to create a stand-alone C or C++ graphics
application. In this process, the MATLAB Compiler:
• Translates the specified M-files into a C or C++ source code modules

• Generates additional C or C++ source code modules, called wrapper files,
required by stand-alone applications
• Compiles and links the source modules into a stand-alone application, by
invoking an ANSI C or C++ compiler and linker that you have installed on
The Compiler links your application with the MATLAB C/C++ Graphics
Library, several other MATLAB libraries, and an ANSI C/C++ math library.
The MATLAB API and MAT-file libraries come with MATLAB. The
MATLAB Math Built-In Library and the MATLAB Math M-file Library are
components of the MATLAB C/C++ Math Library. Figure 2-1 graphically
illustrates this process.
Note To avoid confusion between the MATLAB Compiler and an ANSI C or

C++ compiler, this documentation uses “Compiler” with a capital C to refer to
the MATLAB Compiler and “compiler” with a lowercase c refer to an ANSI C
or C++ compiler.
2-3
2 Creating Stand-Alone Graphics Applications
M-file that includes graphics functions
MATLAB Compiler
C or C++ source file version of M-file
C or C++ compiler
MATLAB C/C++ Graphics Library

Object files
MATLAB Math M-file Library
MATLAB Math Built-In Library
MATLAB API Library
MATLAB MAT-File Library

Linker
ANSI C or C++ Library
Stand-alone C or C++ graphics application
Figure 2-1: Creating a Stand-Alone C or C++ Graphics Applications
2-4
Building a Stand-Alone Graphics Application

The best way to learn how to build a stand-alone graphics application is to see
an example. This section shows how to create a stand-alone graphics
application by converting one of the demo programs included with MATLAB,
lorenz.m. The Lorenz demo program is a good example of a graphics
application because it uses graphics functions and includes several
user-interface objects, such as push buttons. (To get more information about
the Lorenz application, type help lorenz at the MATLAB prompt.)
This section includes these topics:
• “Building Graphics Applications on a PC”

• “Building Graphics Applications on a UNIX System” on page 2-7
• “Running the MATLAB Compiler Outside MATLAB” on page 2-9
• “Compiling and Linking Without mbuild” on page 2-9
Building Graphics Applications on a PC

To create a stand-alone graphics application on a PC, you must use the
MATLAB Compiler (mcc), specifying the Compiler’s Graphics Library bundle
file.
Bundle files are ASCII text files that contain Compiler command line options
and arguments. The MATLAB Compiler supports separate bundle files for
creating C stand-alone graphics applications and C++ applications.
MATLAB Compiler’s Graphics Library Bundle Files on PCs
C applications <MATLAB>\toolbox\compiler\bundles\sgl
C++ applications <MATLAB>\toolbox\compiler\bundles\sglcpp
For example, to convert the Lorenz application into a stand-alone application,

enter these commands at the MATLAB prompt.
mbuild -setup
!copy <MATLAB>\toolbox\matlab\demos\lorenz.m .
mcc -B sgl lorenz.m
!lorenz
2-5
Editing the Search Path on Windows 95. On Window 95 systems, you must edit your
autoexec.bat file to add the shared library directory to the PATH variable.
Editing the Search Path on Windows NT. On Windows NT systems, go the Settings
option on the Start menu and choose Control Panel. Double-click on the
System icon to view the System Properties dialog box. Use the Environment
panel to edit the PATH variable.
Building Graphics Applications on a UNIX System

To create a stand-alone graphics application on a UNIX system, you must use
the MATLAB Compiler (mcc), specifying the Compiler’s Graphics Library
bundle file.
Bundle files are ASCII text files that contain Compiler command line options
and arguments. The MATLAB Compiler supports separate bundle files for
creating C stand-alone graphics applications and C++ applications.
MATLAB Compiler’s Graphics Library Bundle Files on UNIX Systems
C applications <MATLAB>/toolbox/compiler/bundles/sgl
C++ applications <MATLAB>/toolbox/compiler/bundles/sglcpp
For example, to convert the Lorenz application into a stand-alone application,

enter these commands at the MATLAB prompt.
mbuild -setup
!cp <MATLAB>/toolbox/matlab/demos/lorenz.m ./
mcc -B sgl lorenz.m
!lorenz
Note the following:
• The example uses mbuild -setup to set up the environment to create

stand-alone applications. This is only required the first time you create a
stand-alone graphics application. See “Configuring the MATLAB C/C++
Graphics Library” on page 1-10 for more information about mbuild.
2-7
• The example uses the UNIX cp command to copy the Lorenz application
M-file into the current MATLAB directory. Use the ! symbol to execute an
operating system command inside the MATLAB environment. (This is
suggested because you may not have permission to create a new file in the
MATLAB demos directory.) Replace <MATLAB> with the name of your top-level
MATLAB installation directory.
• The example invokes the MATLAB Compiler, using the -B flag to specify the
bundle used to create C stand-alone graphics applications, sgl
Results of Compilation
The MATLAB Compiler generates multiple C or C++ source code modules in
your current working directory. These include wrapper files that contain
necessary components of a stand-alone application
, such as a main() entry
point.
In addition, the first time you run the MATLAB Compiler to create a
stand-alone graphics application, it creates a subdirectory, named /bin, in
your current working directory.The Compiler puts in this directory versions of
the MATLAB menu bar and toolbar figure files that are used by stand-alone
graphics applications at run-time. (Stand-alone graphics applications use a
special menu bar and toolbar. For more information, see “Changes in Run-Time
Behavior and Appearance” on page 2-11.) Subsequently, when you run the
Compiler, it checks for the existence of these files in the /bin directory and does
not overwrite them if they exist.
Running a Stand-Alone Graphics Application

The Compiler creates the stand-alone graphics application as an executable
program in your current working directory, giving it the same name as your
M-file. You can run your stand-alone graphics application at the MATLAB
prompt if you precede the executable name with a !, as shown in the example.
You can also run a stand-alone application outside of the MATLAB
environment. However, you must add to your path the location of the shared
libraries to which your application is linked.To set your path, use the
command from this table that is specific for your system.
2-8
Architecture Command
HP700 setenv SHLIB_PATH <MATLAB>/extern/lib/hp700:<MATLAB>/bin/

hp700:$SHLIB_PATH
All others setenv LD_LIBRARY_PATH <MATLAB>/extern/lib/<ARCH>:<MATLAB>/bin/

<ARCH>:$LD_LIBRARY_PATH
where:
<MATLAB> is the MATLAB root directory.
<ARCH> is your system architecture
To avoid having to reissue this command at the start of each login session,
include it in a startup script such as ~/.cshrc or ~/.login. Use the ~/.login
option, if your system supports it, because it only gets executed once.
Running the MATLAB Compiler Outside MATLAB

You can run the MATLAB Compiler outside the MATLAB environment,
invoking it at the system prompt. If you do, you must use the -I option on the
Compiler command line to specify the locations of the M-files that your
application depends on.For example, the Lorenz application uses functions in
the graph2d, graphics, demos, and graph3d subdirectories of the
<MATLAB>/toolbox/matlab/ directory. When you run the Compiler from within
MATLAB, it can locate these files by referencing the MATLAB path.
A convenient way to provide the Compiler with this path information is to start
MATLAB and run the mccsavepath command. This command creates a path
information file, named mccpath, in your current directory. When you run the
Compiler outside the MATLAB environment, it automatically looks in your
local directory for this path information file.
Compiling and Linking Without mbuild

For graphics applications, you must use the MATLAB Compiler to generate C
or C++ source code modules. The graphics library does not support the direct
coding of graphics applications. You can, however, perform the compilation and
linking of your source modules without using mbuild.
2-9
Changes in Run-Time Behavior and Appearance

Stand-alone versions of graphics applications typically look and operate the
same as their M-file counterparts. However, because stand-alone applications
run outside the MATLAB environment, there are some differences, highlighted
in these sections:
• “Changes to Figure Window Menu Bar Options”

• “Changes to the Figure Window File Menu Options” on page 2-13
• “Accessing Help in Stand-Alone Applications” on page 2-13
• “Ctrl+C Handling” on page 2-13
Changes to Figure Window Menu Bar Options

Stand-alone graphics applications use a special version of the Figure window
menu bar that contains only the File menu option. The graphics library
excludes the other standard menu bar items, such as Edit, Tools, and Help,
from the menu bar because stand-alone graphics applications cannot support
many of the options available through these menus.
To illustrate these differences, compare Figure 2-2, which shows the Lorenz
application running as an M-file on a PC, with Figure 2-3, which shows the
Lorenz application running as a stand-alone application.
2-11
Changes to the Figure Window File Menu Options

The graphics library excludes options from the File menu that are not
supported by stand-alone applications, such as the Page Setup option.
Note The graphics library includes the Print option in the File menu of
stand-alone graphics applications. However, the Print option in stand-alone
applications does not display the Print dialog box, as it does for M-file
applications.
Accessing Help in Stand-Alone Applications

Some M-file applications include GUI components that provide access to
MATLAB help. For example, the Lorenz application includes an Info push
button that displays the M-file help for the Lorenz function in a separate
window.
The stand-alone version of the Lorenz application does not have access to
MATLAB help files. If you click on the Info button, you get this error message:
An error occurred in the callback : lorenz('info')
The error message caught was : Function "helpwin" is not
supported in standalone applications
Ctrl+C Handling
When you run a graphics application within MATLAB, you can press Ctrl+C
to break infinite loops. For example, you can press Ctrl+C to stop an
animation. When you run a C or C++ stand-alone application, Ctrl+C handling
is not supported.
2-13
Distributing Stand-Alone Graphics Applications

You may freely distribute applications you develop with the MATLAB C/C++
Graphics Library, subject to The MathWorks software license agreement.
However, when you package your application for distribution, remember to
include, along with your application executable, these additional files:
directory as your application executable
• Any custom MEX files your application uses
• All the MATLAB math and graphics run-time libraries
To make packaging an application easier, the graphics library has prepackaged

all the necessary MATLAB run-time libraries into a single, self-extracting
archive file. For more information about how you can use this archive, see
“Packaging the MATLAB Run-Time Libraries”. For information about how
customers who receive your application can use this archive, see “Installing
Your Application” on page 2-15.
Packaging the MATLAB Run-Time Libraries

The MATLAB C/C++ Graphics Library has prepackaged all the MATLAB math
and graphics run-time libraries required by stand-alone graphics applications
into a single, self-extracting archive file, called the MATLAB Math and
Graphics Run-Time Library Installer. Instead of including all the run-time
libraries individually in your stand-alone application distribution package, you
can simply include this archive file.
The following table lists the name of the archive file for both PCs and UNIX
systems. In the table <MATLAB> represents your MATLAB installation
directory and <ARCH> represents your UNIX platform.
Platform MATLAB Math and Graphics Run-Time Library Installer
UNIX systems <MATLAB>/extern/lib/<ARCH>/mglinstaller
PCs <MATLAB>\extern\lib\win32\mglinstaller.exe
2-14
Distributing Stand-Alone Graphics Applications
Installing Your Application

To install your application, your customers must:
• Run the MATLAB Math and Graphics Run-Time Library Installer . This
program extracts the libraries from the archive and installs them in
subdirectories of a directory specified by the user.
• Add the bin/$ARCH subdirectory to their path. This is the only MATLAB
run-time library subdirectory that needs to be added to the path.
Note If a customer already has the MATLAB math and graphics run-time
libraries installed on their system, they do not need to reinstall them. They
only need to ensure that the library search path is configured correctly.
On UNIX Systems
On UNIX systems, your customers run the MATLAB Math and Graphics
Run-Time Library Installer by executing the mglinstaller command at the
system prompt. Your customers can specify the name of the directory into
which they want to install the libraries. By default, the installer puts the files
in the current directory.
must add the name of the bin/<ARCH> subdirectory to the LD_LIBRARY_PATH
environment variable. (The equivalent variable on HP-UX systems is the
SHLIB_PATH.)
For example, if your customers working on a Linux system specify the

installation directory mgl_runtime_dir, then they must add
mgl_runtime_dir/bin/glnx86 to the LD_LIBRARY_PATH environment variable.
On PCs
On PCs, your customers can run the MATLAB Math and Graphics Run-Time
Library Installer by double-clicking on the mglinstaller.exe file. Your
customers can specify the name of the directory into which they want to install
the libraries. By default, the installer puts the files in the current directory.
2-15

(Ebook) MatLab - C C++ Compiler Suite 2.1 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

(Ebook) MatLab - C C++ Compiler Suite 2.1 PDF

Uploaded by

Copyright:

Available Formats

C/C++ Compiler Suite 2.

freely distributable stand-alone C and C++ code

The C/C++ Compiler Suite consists of

■ Generate, rotate, zoom, and scroll MATLAB 2-D and 3-D

■ Display lighting and shading on 3-D surfaces

This example shows how MATLAB and

Sample Command-Line Options

Generate C code for use with Simulink models

Turn compiling graphics on or off

Turn on trace back error message to display M Line—number line

• C source code for building MEX-files.

Before You Begin

pause and continue. These commands are now supported.

Note As of Compiler 2.1, Compiler 1.2 is no longer available due to the

Compiler Licensing Changes

• From the MATLAB command prompt

Running Compiler from MATLAB

Running Compiler from DOS/UNIX Shell

Uses of the Compiler

1 Translates your M code to C code.

2 Generates a MEX wrapper.

This figure illustrates the process of producing a MEX-file. The MATLAB

• Shaded block is user-written code.

MEX Math Library

Figure 1-1: Developing MEX-Files

Creating Stand-Alone Applications

C++ Stand-Alone Applications

Developing a Stand-Alone Application

M-File function to find the

• Shaded block is user-written code.

C version of C File • Shadowed blocks are tools.

MATLAB M-File Math Library MATLAB API Library

MATLAB Math Built-In Library MATLAB Utility Library

Figure 1-2: Developing a Typical Stand-Alone C Application

Why Compile M-Files?

• To create stand-alone applications or C shared libraries(DLLs on Windows)

Stand-Alone Applications and Libraries

Hiding Proprietary Algorithms

• Compiled code usually runs faster than interpreted code.

• Are heavily vectorized

Cases When Performance Does Improve. Compilation is most likely to speed up

Limitations and Restrictions

• Script M-files (See “Converting Script M-Files to Function M-Files” in

is disallowed by the Compiler.

The Compiler cannot compile built-in MATLAB functions (functions such as

Table 1-2: Unsupported Functions in Stand-Alone Mode

add_block add_line applescript assignin

callstats close_system cputime dbclear

dbcont dbdown dbquit dbstack

dbstatus dbstep dbstop dbtype

dbup delete_block delete_line diary

echo edt errorstat errortrap

evalin fields fschange functionscalled

get_param hcreate help home

hregister inferiorto inmem isglobal

isjava isruntime java javaArray

javaMethod javaObject keyboard linmod

lookfor macprint mactools methods

mislocked mlock more munlock

new_system open_system pack pfile

Table 1-2: Unsupported Functions in Stand-Alone Mode (Continued)

simget simset sldebug str2func

superiorto system_dependent trmginput type