Compiling MATLAB with Release 14 SP3

Compiling MATLAB under MATLAB R14 SP3

Here are the steps for MATLAB compilation. These have been updated to cover 32-bit and 64-bit compilation on the LSC grid computers
Why create MATLAB executables?
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.

Why compile MATLAB into executables?

MATLAB has become quite popular for interactively analyzing data and doing time-series analysis within the LSC. It would be even better if one could then use the same programs and functions to do large-scale batch processing, instead of having to translate into a different language! (It would certainly eliminate an extra code walkthrough review) But you can! MATLAB now has a compiler which can be used to make stand-alone executables which have been run on LSC Grid computers for the S2, S3, S4 and S5 data analyses, with papers written on the results (This includes at least the Burst Group and Stochastic Group). While you do need to purchase a MATLAB Compiler license to build the executables (or use the licenses on the LSC grid computers), you can then freely distribute the executable and the MATLAB Component Runtime (MCR) to as many computers as you want! No licenses, no limits. The 'matapps' project has been created in the DASWG 'lscsoft' CVS repository to house MATLAB applications developed by the LSC community.

MATLAB Compiler 4.3

The current release of MATLAB (called both MATLAB 7.3 and Release 14 SP3) comes with a new Compiler 4.3. 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. This means that compilable variants of MATLAB functions (required for MATLAB 6) are no longer needed! In particular, MATLAB classes and objects can be used. Unfortunately, because the MCR runs M-files instead of compiling an executable, compiled code is now no faster than interactive code. The MCR requires a different method for distributing executables. This is most important when exporting stand-alone programs to the LSC Grid computers

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 Gravity cluster (where compilation is done) is 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 (as of Feb 2006) 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 computers are 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. As MATLAB Release 14 was built on the older gcc 3.2.3, some care has to be taken to build and run executables under the newer gcc versions (3.4, 4.0). Note that Compiler 4.3 has corrected problems with the initial compiler release. This has simplified the installation and setup from Compiler 4.0.

Compiling MATLAB on PSU Gravity Cluster

MATLAB Release 14 is installed on the gravity cluster at /usr/local/matlab-r14sp3. It is also now the default installation, so entering

matlab

at the command prompt will 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-r14sp3/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/R14SP3 sub-directory of your home directory. Here is a log file of the mbuild process.

2) Modify the build options file

There is still an error in the options script which needs to be fixed. It involves adding gcc_s as a library.
1) Open mbuildopts.sh in an editor
2) On or about line 84, add -lgcc_s to the CLIBS line for 'gcc' under 'glnx86' as below:

#----------------------------------------------------------------------------
            ;;
        glnx86)
#----------------------------------------------------------------------------
            RPATH="-Wl,--rpath-link,$TMW_ROOT/bin/$Arch"
#           gcc -v
#           gcc version 3.2.3
            CC='gcc'
            CFLAGS="$MFLAGS -ansi -D_GNU_SOURCE -pthread -fexceptions"
            CLIBS="$RPATH $MLIBS -lm -lstdc++ -lgcc_s"

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. The syntax of the startup.m file should be:

if((str2num(version('-release')) < 14) || ~isdeployed)
   addpath commands
   ...
end

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 R14SP3 run-time to your path

To test the stand-alone executables on the machine 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. It appears to be identical to that from Compiler 4.2
On the Gravity cluster add the following to your .cshrc or in a separate shell script

setenv MATLAB_ROOT /usr/local/matlab-r14sp3
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/client:${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 R14. This will screw up the compiler in quite subtle ways.

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 14 is installed in the same place (/ldcg/matlab_r14_sp3) 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 (as R14SP3 is now the default installation):

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/R14SP3 sub-directory of your home (HOME) directory. Here is a log file of the mbuild process.

2A) Normal 32-bit,64-bit builds - Modify the build options file

As Fedora Core 4 has a newer gcc version than the MATLAB 14 libraries were built with, we need to modify the build options file to point to the older libstdc++.so.5 library.
1) Open mbuildopts.sh in an editor
2) On or about line 84, modify the code to point to libstdc++.so.5 library within the MATLAB release files as below for 32-bit (glnx86) compiles:

#----------------------------------------------------------------------------
            ;;
        glnx86)
#----------------------------------------------------------------------------
            RPATH="-Wl,--rpath-link,$TMW_ROOT/bin/$Arch"
#           gcc -v
#           gcc version 3.2.3
            CC='gcc'
            CFLAGS="$MFLAGS -ansi -D_GNU_SOURCE -pthread -fexceptions"
            CLIBS="$RPATH $MLIBS -lm $TMW_ROOT/sys/os/$Arch/libstdc++.so.5""

3) On or about line 122, make the same change for 64-bit (glnxa64) compiles.

#----------------------------------------------------------------------------
            ;;
        glnxa64)
#----------------------------------------------------------------------------
            RPATH="-Wl,-rpath-link,$TMW_ROOT/bin/$Arch"
#           gcc -v
#           gcc version 3.2.3
            CC='gcc'
            CFLAGS="$MFLAGS -ansi -D_GNU_SOURCE -pthread -fexceptions"
            CLIBS="$RPATH $MLIBS -lm $TMW_ROOT/sys/os/$Arch/libstdc++.so.5""

Here is a reference mbuildopts.sh file with the libstdc++ changes.
**Note that the LSC grid admins may make this change in the default mbuildopts.sh file.

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'. I have added the libstdc++.so.5 change described above to that.

1) Get this mbuildopts.sh modifed to force 32-bit builds.
2) Either copy this to the ${HOME}/.matlab/R14SP3 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/R14SP3 if you are not going to do 64-bit builds at this time.

3) Fix your startup.m file to running executables

if((str2num(version('-release')) < 14) || ~isdeployed)
   addpath commands
   ...
end

The startup.m file should be in your ~/matlab directory.

4A) 32-bit Compiles Add MATLAB R14SP3 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. It appears to be identical to that for Compiler 4.2

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_r14_sp3
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/client:${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 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 R14. This will screw up the compiler in quite subtle ways.

4B) 64-bit Compiles Add MATLAB R14SP3 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. It appears to be identical to that for Compiler 4.2

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_r14_sp3
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.4.2/lib/amd64:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.4.2/lib/amd64/client:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnxa64/jre1.4.2/lib/amd64/native_threads:${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. Also, I have added a library (/sys/opengl/lib/glnxa64) 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 R14. 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 R14SP3 bin file)

[thorne@auriga ~/mat_test]$ cd ~/mat_test
[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.ctf --> encoded matlab files
magicsquare_mcr --> directory of m-files for application

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 only possible (for now) at CIT, using the ldas-pcdev1.ligo.caltech.edu node. Use the following at the command prompt (assumes 'matlab' points to the MATLAB R14SP3 bin file)

[thorne@ldas-pcdev1 ~/mat_test]$ cd ~/mat_test
[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.ctf --> encoded matlab files
magicsquare_mcr --> directory of m-files for application

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.

2C) Build a 32-bit application on 64-bit node!

Here we start up MATLAB on a 64-bit node but for 'glnx86', and invoke the mcc compiler for the 'glnx86' compiler. This is only required if using the 64-bit development node at CIT (ldas-pcdev1.ligo.caltech.edu) to do 32-bit builds at CIT
** Make sure you are using the special mbuildopts.sh file detailed above

Use the following at the command prompt (assumes 'matlab' points to the MATLAB R14SP3 bin file)

[thorne@ldas-pcdev1 ~/mat_test]$ cd ~/mat_test
[thorne@ldsa-pcdev1 ~/mat_test]$ matlab -glnx86 -nodisplay
>>getenv('ARCH')
 
ans =
 
glnx86
 
>>mcc -mv magicsquare.m

We used the 'getenv' as a sanity check that we are setup for a 32-bit build. This will create the following files
magicsquare --> the executable
magicsquare_main.c --> 'main' wrapper
magicsquare_mcc_component_data.c
magicsquare.ctf --> encoded matlab files
magicsquare_mcr --> directory of m-files for application

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.csh  < or use MatlabSetup_32bit.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.

ans =

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

[thorne@auriga ~/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]$ source ${HOME}/MatlabSetup_64bit.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.

ans =

    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

Last modified: Fri Mar 3, 2006

Compiling MATLAB under MATLAB R14 SP3

Why compile MATLAB into executables?

MATLAB Compiler 4.3

Getting the MATLAB Compiler

Compiling MATLAB on PSU Gravity Cluster

1) Create build options file

2) Modify the build options file

3) Fix your startup.m file to running executables

4) Add MATLAB R14SP3 run-time to your path

Compiling MATLAB on LSC Development Nodes

1) Create build options file

2A) **Normal 32-bit,64-bit builds** - Modify the build options file

2B) **32-bit builds on 64-bit systems** Get modified mbuild options file

3) Fix your startup.m file to running executables

4A) **32-bit Compiles** Add MATLAB R14SP3 run-time to your path

4B) **64-bit Compiles** Add MATLAB R14SP3 run-time to your path

Testing your compiler setup

1) Get the magicsquare.m sample code

2A) Build a 32-bit application on 32-bit node

2B) Build a 64-bit application on a 64-bit node

2C) Build a 32-bit application on 64-bit node!

3A) Test the 32-bit application

3B) Test the 64-bit application

Handling function inputs on the command line

2A) Normal 32-bit,64-bit builds - Modify the build options file

2B) 32-bit builds on 64-bit systems Get modified mbuild options file

4A) 32-bit Compiles Add MATLAB R14SP3 run-time to your path

4B) 64-bit Compiles Add MATLAB R14SP3 run-time to your path