Compiling MATLAB with Release 2006b
Compiling MATLAB under MATLAB 2006b
Here are the steps for MATLAB compilation.
Introduction
MATLAB Compiler Setup at PSU
MATLAB Compiler Setup at LSC grids
Testing your MATLAB compiler setup
After this, you will want to find out
how to deploy MATLAB executables
on grid computers.
The 2006b release of MATLAB (called both MATLAB 7.5 and Release 2006b) comes with
a new Compiler 4.5. The
documentation
for the compiler is available online from MathWorks.
This uses the MATLAB Component Runtime (MCR) which allows the use of
nearly every function in the MATLAB libraries in a stand-alone executable.
Because the MCR runs M-files instead of compiling an
executable, compiled code is no faster than interactive code.
Getting the MATLAB Compiler
It is important to compile MATLAB programs on the same operating system type
where the executables will be run. As the LSC Grid utilities all use Linux at present,
you need to run the compiler on a Linux system. The license can be purchased for an existing MATLAB installation
from MathWorks. The cost for an academic license for the compiler is ~ $200. If you are using
the Penn State or LSC clusters for development, the license and installation are already provided.
In addition, you should also generate the executable on a Linux/gcc version similar to
that you will run on. The PSU Gravity cluster (gravity.psu.edu) and Pleiades grid computer
(pleiades.aset.psu.edu) presently use RedHat Enterprise Linux (termed RHEL).
The 32-bit machines of the Gravity cluster (where compilation is done) are at RHEL3, which uses Linux kernel 2.4 and gcc 3.2.3.
The Pleiades grid computer (as of Feb 2006) is at RHEL4, which uses Linux kernel 2.6 and gcc 3.4.5.
The LSC grid computers at Caltech, Hanford and Livingston
(ldas-grid.ligo.caltech.edu, ldas-grid.ligo-wa.caltech.edu and ldas-grid.ligo-la.caltech.edu)
use Fedora Core 4 (termed FC4). FC4 uses Linux kernel 2.6 and gcc 4.0.2.
The PSU grid computer is 32-bit, while the LSC grid computers are both 64-bit (CIT)
and 32-bit (LHO,LLO). 32-bit machines are available for compilation at CIT.
The new UWM grid computer (hydra.phys.uwm.edu) is now 64-bit with Fedora Core 4.
As of Release 2006b, MathWorks is doings its builds on Debian 3.1 platforms. It now supports both Linux kernels
2.4.x and 2.6.x, and requires glibc 2.3.2 and higher for 32-bit (glibc 2.3.4 and higher for 64-bit).
This is a much better match to the LSC grid computers, so build customization is either not needed, or greatly simplified.
Compiling MATLAB on PSU Gravity Cluster
MATLAB Release 2006b is installed on the gravity cluster at /usr/local/matlab-r2006b.
It is now the default version. However,
for the following we want to be specific about which version is invoked.
Thus, we enter matlab-r2006b &
at the command prompt to start that version
in interactive mode.
1) Create build options file
As detailed in the MathWorks documentation, after installing the
compiler each user should make a build options script
(mbuildopts.sh).
On the PSU Gravity cluster, do the following at the command line:
/usr/local/matlab-r2006b/bin/matlab -nodisplay
(NOTE: I have used the -nodisplay option to allow non-X-Windows operation, but that is not necessary)
At the MATLAB prompt, enter the following:
>> mbuild -setup
Choose the default option (if asked) and allow it to override the existing mbuildopts.sh.
This creates a file mbuildopts.sh in a .matlab/R2006b sub-directory of
your home directory. Here is a log file
of the mbuild process.
2) Modify the build options file
The R2006b MATLAB libraries were built with libstdc++.so.6.
This is not the default 'stdc++' on the 32-bit Gravity cluster machines
(presently libstdc++.so.5) , so we must explicitly point to the libstdc++.so.6 library
distributed with R2006b for 32-bit builds.
1) Open mbuildopts.sh in an editor
2) On or about line 49, modify the code to point to libstdc++.so.6 library
within the MATLAB release files as below for 32-bit (glnx86) compiles:
#----------------------------------------------------------------------------
;;
glnx86)
#----------------------------------------------------------------------------
RPATH="-Wl,--rpath-link,$TMW_ROOT/bin/$Arch"
CC='gcc'
CFLAGS="$MFLAGS -ansi -D_GNU_SOURCE -pthread -fexceptions"
CLIBS="$RPATH $MLIBS -lm $TMW_ROOT/sys/os/$Arch/libstdc++.so.6""
3) Save the modified mbuildopts.sh
Here is a reference mbuildopts.sh
file with the gcc_s change .
3) Fix your startup.m file to running executables
When testing a stand-alone build, you need to make sure it sees
the local encrypted m-files instead of ones from your CVS sandbox.
We wrap any addpath
commands (which let us see the CVS sandbox files) with a conditional to
prevent their use when running an
executable. For Release 2006b, the
version('-release') function returns
a text string 2006b that can not be converted to a numeric value. This complicates things if you wish to preserve backward compatibility
with Release 13. A complete syntax of the startup.m file should now be:
verNum = str2num(version('-release'));
if(~isempty(verNum))
verOld = verNum < 14;
else
verOld = false;
end
if( (verOld == true) || (~isdeployed))
...
addpath commands
...
end
clear verNum;
clear verOld;
Here is an example
startup.m for the Gravity cluster and the psurg CVS.
The startup.m file should be in your ~/matlab
directory.
4) Add MATLAB R2006b run-time to your path
To test the stand-alone executables on a file system where you have MATLAB
installed on, you need to have the MATLAB Component
Runtime (located within the MATLAB installation) in your dynamic library
path. This is detailed in on page 5-4 of the Compiler manual.
For 32-bit compiliation on the Gravity cluster,
add the following to your .cshrc or in a separate shell script
# Setup to test 32-bit MATLAB executables on PSU Gravity cluster
# MATLAB version R2006b
#
setenv MATLAB_ROOT /usr/local/matlab-r2006b
setenv ARCH glnx86
#
if ( $?LD_LIBRARY_PATH ) then
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}
else
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnx86
endif
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386/native_threads:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnx86:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MATLAB_ROOT}/X11/app-defaults
#
unsetenv MATLAB
Note that this is in 'reverse' order from the Compiler documentation list to ensure correct order
in LD_LIBRARY_PATH. Also, I have added a library (/sys/opengl/lib/glnx86) which previous experience
with Compiler 4.1 showed was often necessary. I have also added the definition of environment
variable ARCH, which is actually needed when save plot files due to a bug in
calls to ghostscript. I have provided an example
csh script which handles a non-existent LD_LIBRARY_PATH and
checks if MATLAB was already added to it.
** NOTE: Do NOT define an environment variable named "MATLAB" under MATLAB R2006b.
This will screw up the compiler in quite subtle ways.
For 64-bit compiliation on the Gravity cluster (such as on jaynes.gravity.psu.edu),
add the following to your .cshrc or in a separate shell script
# Setup to test 64-bit MATLAB executables on PSU Gravity cluster
# MATLAB version R2006b
#
setenv MATLAB_ROOT /usr/local/matlab-r2006b
setenv ARCH glnxa64
if ( $?LD_LIBRARY_PATH ) then
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnxa64:${LD_LIBRARY_PATH}
else
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnxa64
endif
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64/native_threads:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/extern/lib/glnxa64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/glnxa64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnxa64:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MATLAB_ROOT}/X11/app-defaults
unsetenv MATLAB
I have provided an example
csh script which handles a non-existent LD_LIBRARY_PATH and
checks if MATLAB was already added to it.
Compiling MATLAB on LSC Development Nodes
The LSC grid clusters have nodes specifically set aside for development work, as opposed to running jobs
on the grid nodes. These have the ldas-pcdev1 name (i.e. ldas-pcdev1.ligo.caltech.edu). All systems are
presently at Fedora Core 4. The new CIT grid computers are 64-bit. However, they can run 32-bit code and
there is one development node (ldas-pcdev2.ligo.caltech.edu) that is still 32-bit. The LLO and LHO grid
computers are 32-bit.
MATLAB Release 2006b is installed in the same place (/ldcg/matlab_r2006b) on these machines. Also note that
these development computers see the same drives as the grid computers at that site, which simplifies
deployment of MATLAB executables.
1) Create build options file
As detailed in the MathWorks documentation, after installing the
compiler each user should make a build options script
(mbuildopts.sh).
On an LSC development node, do the following at the command line if X-Windows is active:
/ldcg/matlab_r2006b/bin/matlab &
If X-Windows is not active, do the following at the command line:
export DISPLAY=:0.0
/ldcg/matlab_r2006b/bin/matlab -nodisplay
I have routed the DISPLAY to a null device to ensure the -nodisplay option works properly.
At the MATLAB prompt, enter the following:
>> mbuild -setup
Choose the default option (if asked) and allow it to override the existing mbuildopts.sh.
This creates a file mbuildopts.sh in a .matlab/R2006b sub-directory of
your home (HOME) directory. Here is a log file
of the mbuild process.
2A) **Normal 32-bit,64-bit builds** - No changes needed!
As Release 2006b now is compatible with Fedora Core 4, no customization is needed to the
'mbuildopts.sh' file.
Here is a reference mbuildopts.sh if you are wondering
what is in it.
2B) **32-bit builds on 64-bit systems** Get modified mbuild options file
There is a great difficulty doing a 32-bit build ('glnx86' option) if you are using
a 64-bit node (i.e. ldas-pcdev1.ligo.caltech.edu). It appears NOT possible to force the
architecture to be 'glnx86' instead of 'glnxa64'. However, MathWorks has provided a
work-around mbuildopts.sh that overrides the 'glnxa64' stuff with 'glnx86'. You
can look at this MathWorks support page
1) Get this mbuildopts.sh modified to force 32-bit builds.
2) Either copy this to the ${HOME}/.matlab/R2006b folder with the original mbuildopts.sh file
created above or to the folder where you are doing a 32-bit build while at CIT.
** NOTE: ONLY overwrite the default file in ${HOME}/.matlab/R2006b if you are not going
to do 64-bit builds at this time.
3) Fix your startup.m file to running executables
When testing a stand-alone build, you need to make sure it sees
the local encrypted m-files instead of ones from your CVS sandbox.
We wrap any addpath
commands (which let us see the CVS sandbox files) with a conditional to
prevent their use when running an
executable. For Release 2006b, the
version('-release') function returns
a text string 2006b that can not be converted to a numeric value. This complicates things if you wish to preserve backward compatibility
with Release 13. A complete syntax of the startup.m file should now be:
verNum = str2num(version('-release'));
if(~isempty(verNum))
verOld = verNum < 14;
else
verOld = false;
end
if( (verOld == true) || (~isdeployed))
...
addpath commands
...
end
clear verNum;
clear verOld;
The startup.m file should be in your ~/matlab
directory.
4A) **32-bit Compiles** Add MATLAB R2006b run-time to your path
To test the stand-alone executables built under glnx86 on the machine you have MATLAB
installed on (or to run them on the LSC grid computers), you need to have the MATLAB Component
Runtime in your dynamic library path. This is detailed in on page 5-4 of the Compiler manual.
On the LSC grid development node, add the following to your .cshrc
or to a separate shell script you can source as needed for 32-bit executables
setenv MATLAB_ROOT /ldcg/matlab_r2006b
setenv ARCH glnx86
#
if ( $?LD_LIBRARY_PATH ) then
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}
else
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnx86
endif
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.5.0/lib/i386/native_threads:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnx86:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MATLAB_ROOT}/X11/app-defaults
#
unsetenv MATLAB
Note that this is in 'reverse' order from the Compiler list to ensure correct order
in LD_LIBRARY_PATH. Also, I have added a library (/sys/opengl/lib/glnx86) which previous experience
with Compiler 4.1 showed was often necessary. I have also added the definition of environment
variable ARCH, which is actually needed when saving plot files due to a bug in
calls to ghostscript. I have provided an example
csh script which handles a non-existent LD_LIBRARY_PATH and
checks if MATLAB was already added to it.
** NOTE: Do NOT define an environment variable named "MATLAB" under MATLAB R14.
This will screw up the compiler in quite subtle ways.
4B) **64-bit Compiles** Add MATLAB R2006b run-time to your path
To test the stand-alone executables built under glnxa64 at CIT on the machine you have MATLAB
installed on, you need to have the MATLAB Component Runtime in your dynamic library path.
This is detailed in on page 5-4 of the Compiler manual.
On the CIT LSC grid development node, add the following to your .cshrc
or to a separate shell script you can source as needed for 64-bit executables
setenv MATLAB_ROOT /ldcg/matlab_r2006b
setenv ARCH glnxa64
#
if ( $?LD_LIBRARY_PATH ) then
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnxa64:${LD_LIBRARY_PATH}
else
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnxa64
endif
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.5.0/lib/amd64/native_threads:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/extern/lib/glnxa64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/glnxa64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnxa64:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MATLAB_ROOT}/X11/app-defaults
#
unsetenv MATLAB
Note that this is in 'reverse' order from the Compiler list to ensure correct order
in LD_LIBRARY_PATH. This setup does not match that in the MATLAB documentation.
I have had to add a library (/sys/opengl/lib/glnxa64) which previous experience with Compiler 4.3
showed was often necessary. I have provided an example
MatlabSetup_R2006b_glnxa64.csh which handles
a non-existent LD_LIBRARY_PATH and checks if MATLAB was already added to it.
** NOTE: Do NOT define an environment variable named "MATLAB" under MATLAB R2006b.
This will screw up the compiler in quite subtle ways.
Testing your compiler setup
We will now follow the stand-alone application example (page 5-3 of the Compiler manual).
1) Get the magicsquare.m sample code
This is located in <matlabroot>/extern/examples/compiler,
but I have also made it available following this
magicsquare.m link.
Create a directory (~/mat_test)
and copy the file to it.
2A) Build a 32-bit application on 32-bit node
Here we start up MATLAB and invoke the mcc compiler for the 'glnx86' compiler. This
is the default at PSU, LLO and LHO.
You must use ldas-pcdev2.ligo.caltech.edu to
do 32-bit builds at CIT !
Use the following at the command prompt (assumes 'matlab' points to the MATLAB R2006b bin file)
[thorne@auriga ~/mat_test]$ cd ~/mat_test
[thorne@auriga ~/mat_test]$ export DISPLAY=:0.0
[thorne@auriga ~/mat_test]$ matlab -nodisplay
>>getenv('ARCH')
ans =
glnx86
>>mcc -mv magicsquare.m
We used the 'getenv' as a sanity check that we are on a 32-bit Linux machine.
This will create the following files
magicsquare --> the executable
magicsquare_main.c --> 'main' wrapper
magicsquare_mcc_component_data.c
magicsquare.prj --> project file (in XML)
magicsquare.ctf --> encoded matlab files
When the compilation is progressing, a long blow-by-blow listing is
shown because we added the -v option (for verbose).
Once things work, you can skip this option. Here is a
copy of the compilation log.
Warning:
when you first run the executable it will unpack the .ctf file into an _mcr directory. Having this (or any _mcr) directory in your matlab path may cause problems when trying to compile! This is probably your problem if you get an error:
Error: File: dirname Line: 1 Column: 25
in which case, you will want to check the verbose listing to see what _mcr directory is in your path.
2B) Build a 64-bit application on a 64-bit node
Here we start up MATLAB and invoke the mcc compiler for the 'glnxa64' compiler. This
is possible at CIT, using the ldas-pcdev1.ligo.caltech.edu node, and at
PSU on the jaynes.gravity.psu.edu node. Use the following at the command prompt
[thorne@ldas-pcdev1 ~/mat_test]$ cd ~/mat_test
[thorne@ldas-pcdev1 ~/mat_test]$ export DISPLAY=:0.0
[thorne@ldas-pcdev1 ~/mat_test]$ matlab -nodisplay
>>getenv('ARCH')
ans =
glnxa64
>>mcc -mv magicsquare.m
We used the 'getenv' as a sanity check that we are on a 64-bit Linux machine.
This will create the following files
magicsquare --> the executable
magicsquare_main.c --> 'main' wrapper
magicsquare_mcc_component_data.c
magicsquare.prj --> project file (in XML)
magicsquare.ctf --> encoded matlab files
When the compilation is progressing, a long blow-by-blow listing is
shown because we added the -v option (for verbose).
Once things work, you can skip this option. Here is a
copy of the compilation log.
Warning:
when you first run the executable it will unpack the .ctf file into an _mcr directory. Having this (or any _mcr) directory in your matlab path may cause problems when trying to compile! This is probably your problem if you get an error:
Error: File: dirname Line: 1 Column: 25
in which case, you will want to check the verbose listing to see what _mcr directory is in your path.
3A) Test the 32-bit application
Here we exit MATLAB, and run the application from the command line, after
we setup the LD_LIBRARY_PATH to find 32-bit MCR in our MATLAB installation:
>> quit
[thorne@auriga ~/mat_test]$ source ${HOME}/MatlabSetup_R2006b_glnx86.csh
[thorne@auriga ~/mat_test]$./magicsquare 4
Extracting CTF archive. This may take a few seconds, depending on the
size of your application. Please wait...
...CTF archive extraction complete.
m =
16 2 3 13
5 11 10 8
9 7 6 12
4 14 15 1
[thorne@auriga ~/mat_test]$
There is a subtle change from previous versions, in that the variable name 'm'
is shown when displaying the value.
3B) Test the 64-bit application
Here we exit MATLAB, and run the application from the command line, after
we setup the LD_LIBRARY_PATH to find 64-bit MCR in our MATLAB installation:
>> quit
[thorne@ldas-pcdev1 ~/mat_test]$ source ${HOME}/MatlabSetup_R2006b_glnxa64.csh
[thorne@ldas-pcdev1 ~/mat_test]$./magicsquare 4
Extracting CTF archive. This may take a few seconds, depending on the
size of your application. Please wait...
...CTF archive extraction complete.
m =
16 2 3 13
5 11 10 8
9 7 6 12
4 14 15 1
[thorne@ldas-pcdev1 ~/mat_test]$
Handling function inputs on the command line
Any function inputs are passed as command line arguments.
One difficulty is that numbers are passed as doubles within MATLAB,
but as text strings when entered at the command line. A way to handle
this is shown in the example code
function magicsquare(n)
%MAGICSQUARE generates a magic square matrix of the size specified
% by the input parameter n.
% Copyright 2003 The MathWorks, Inc.
if (ischar(n))
n=str2num(n);
end
magic(n)
The ischar(n) test checks that if text is encountered for a numeric
input, it is converted from a string to a numeric equivalent. This will even
work for MATLAB constructs like [1:5].
Keith Thorne t h o r n e @ g r a v i t y . p s u . e d u
Last modified: Mon, Oct 16, 2006