Compiling MATLAB with Release 2008a

Compiling MATLAB under MATLAB 2008a

Here are the steps for MATLAB compilation.
Introduction
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.

Introduction

The 2008a release of MATLAB (called both MATLAB 7.8 and Release 2008a) comes with a new Compiler 4.8. 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) (except for hydra) presently use CentOS 5, which uses Linux kernel 2.6 and gcc 4.1.2. The Pleiades grid computer (pleiades.aset.psu.edu) presently use RedHat Enterprise Linux 4 (termed RHEL4), which uses Linux kernel 2.6 and gcc 3.4.6. 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 2007a, 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 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 2008a is installed in the same place (/ldcg/matlab_R2008a) 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_r2008a/bin/matlab &

If X-Windows is not active, do the following at the command line:

export DISPLAY=:0.0
/ldcg/matlab_r2008a/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/R2008a sub-directory of your home (HOME) directory. Here is a log file of the mbuild process. As Release 2008a 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.

2) Fix your startup.m file for 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 2008a, the version('-release') function returns a text string 2008a 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.

3A) 32-bit Compiles Add MATLAB R2008a 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. There was no real change from R2007b.

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_R2008a
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.6.0/lib/i386:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.6.0/lib/i386/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.6.0/lib/i386/native_threads:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/extern/lib/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/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 two libraries (/sys/opengl/lib/glnx86, /extern/lib/glnx86) which previous experience with Compiler 4.3 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 examples in csh (MatlabSetup_R2008a_glnx86.csh) and bash (MatlabSetup_R2008a_glnx86.sh) that handle 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 R2008a. This will screw up the compiler in quite subtle ways.

3B) 64-bit Compiles Add MATLAB R2008a 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_R2008a
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.6.0/lib/amd64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/server:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.6.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}/sys/os/glnxa64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/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 two libraries (/sys/opengl/lib/glnxa64, /extern/lib/glnxa64) which previous experience with Compiler 4.3 showed was often necessary. I have provided examples in csh (MatlabSetup_R2008a_glnxa64.csh) and bash (MatlabSetup_R2008a_glnxa64.sh) that handle 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 R2008a. 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. Here we show a build on ldas-pcdev2 at CIT.
Use the following at the command prompt.

[thorne@ldas-pcdev2 ~]$ cd ~/mat_test
[thorne@ldas-pcdev2 ~/mat_test]$ export DISPLAY=:0.0
[thorne@ldas-pcdev2 ~/mat_test]$ /ldcg/matlab_r2008a/bin/matlab -nodisplay 
>>getenv('ARCH')
 
ans =
 
glnx86
 
>>mcc -mv magicsquare

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)
readme.txt --> deployment instructions
run_magicsquare.sh --> example shell script for running deployed code

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.

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 ~]$ cd ~/mat_test
[thorne@ldas-pcdev1 ~/mat_test]$ export DISPLAY=:0.0
[thorne@ldas-pcdev1 ~/mat_test]$ /ldcg/matlab_r2008a/bin/matlab -nodisplay 
>>getenv('ARCH')
 
ans =
 
glnxa64
 
>>mcc -mv magicsquare

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)
readme.txt --> deployment instructions
run_magicsquare.sh --> example shell script for running deployed code

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.

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@ldas-pcdev2 mat_test]$ tcsh
[thorne@ldas-pcdev2 ~/mat_test]$ source ${HOME}/MatlabSetup_R2008a_glnx86.csh
[thorne@ldas-pcdev2 ~/mat_test]$ ./magicsquare 4
Warning: Unable to open display ':0.0'.  You will not be able to display graphics on the screen.

ans =

    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

[thorne@ldas-pcdev2 ~/mat_test]$

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]$ tcsh
[thorne@ldas-pcdev1 ~/mat_test]$ source ${HOME}/MatlabSetup_R2008a_glnxa64.csh
[thorne@ldas-pcdev1 ~/mat_test]$ ./magicsquare 4
Warning: Unable to open display ':0.0'.  You will not be able to display graphics on the screen.

ans =

    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

[thorne@ldas-pcdev1 ~/mat_test]$

Embedding of CTF file

Those with long memories will note that there is no 'ctf' file produced. This is because by default the CTF file embedded in the executable (file `magicsquare' above). Each time you run the executable, it will unpack the embedded CTF file to get the encoded MATLAB files and then use them. Under this operation, a magicsquare_mcr directory is no longer created for later re-use. This default behavior may actually improve using deployed code on grid computers. Since the *_mcr directory and files are no longer cached, there is less chance for conflict. However, it will take up several minutes at the start of each job (except the first). If you want to avoid this, or already have your infrastructure set to transfer two files (executable + CTF), you can get the separate CTF file by using the -C option in the 'mcc' compilation request.

Reduce memory usage for codes without graphic outputs

You can reduce the memory footprint and avoid issues with `headless nodes if you are compiling MATLAB codes that do not output graphics. You want to add `-R -nojvm -R -nodisplay' to your compilation command, as in

mcc -m -R -nojvm -R -nodisplay magicsquare

The -R means pass on to the run-time environment. `-nojvm' means no Java Virtual Machine, which is only needed for GUIs and graphics. `-nodisplay' means don't attempt to display on the DISPLAY device.

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: Fri, June 13, 2008