MATLAB_COMPILER is a directory of MATLAB programs which illustrate the use of the MATLAB compiler, which allows you to create a compiled version of a MATLAB application which can then be run outside the MATLAB environment.
The compiled program can be used on another computer or by another user, who need not have a licensed copy of MATLAB. As long as the compiled program can be linked with the Matlab Compiler Runtime (MCR) library, it can be executed. Thus, before compiling a user program, one must first make sure that the MCR is available on the target computer where the executable is to be run.
One unexpected use for the MATLAB compiler is on computer clusters, where a user program will be executed on an arbitrary node. This node might not have access to the MATLAB license server, and thus, ordinarily, a MATLAB program could not run there. However, it is a relatively simple matter to make the MCR available to any node, and thus a MATLAB program can be compiled on the front end or interactive area of the computer cluster, using a licensed copy of MATLAB; the compiled executable can then be submitted to a batch queue for execution on a remote node with MCR.
Before the first time you want to use the compiler, you must run a setup command that allows MATLAB to select the options appropriate for the given version of MATLAB and the system where compilation is being carried out. To do this, start MATLAB, and issue the command:
mbuild -setup
You may have to respond to one or two questions before the
setup is completed.
To create the executable, you start up MATLAB, and then type
deploytool
which opens up a little GUI with two tabs, NEW and OPEN.
Since we're creating something, we want to work on the NEW tab,
which is probably already visible. On the NEW tab, there
are three items, NAME, LOCATION, and TYPE. In the NAME field,
you can enter a name to give your application; let's say we name it
"magicsquare". Under TYPE, you probably want to choose
"Standalone application", which is probably the default choice anyway.
Clicking OK finishes this part of the process.
You should now see your MATLAB window includes a work area titled "Standalone Application". There should be a tab called BUILD, with an item called "(Add main file)". Click on this, to get a window that allows you to select the file that is to act as the main program for your application. (Let's say our main file is called "magicsquare.m"). If this main program calls other M-files that you have written, and they are in the MATLAB path, they will be included automatically at compile time. So in the simplest case, once you have identified the main program, we are almost done.
To cause the compilation to occur, you must click on the build icon, which is NOT visible as a word, but rather as a tiny icon near the upper right corner of the Standalone Application window. I thought it looked like a little birthday cake with candles...Click on this, and the compilation will begin.
Once the compilation is completed, you will discover that a directory has been created, perhaps called "magicsquare". If we want to execute the compiled program, we will need to look at this directory.
Compiling your MATLAB application created a directory, whose name was specified by you. Inside this directory are two subdirectories, "src" and "distrib". The "distrib" directory contains the compiled information you can execute on another computer, or that you can send to a friend or colleague who does not have a copy of MATLAB.
In the distrib directory for "magicsquare", I found three items:
The executable file is "almost" executable because it cannot run without some extra information; in particular, it needs to know the directory containing the MATLAB Compiler Runtime library (MCR). On my system, all the MATLAB information is stored in the directory /usr/local/matlab. The shell script can be used to run the executable file, feeding it the information about the directory, as well as any necessary commandline arguments. For instance, the magicsquare example can be run by:
./run_magic_example.sh /usr/local/matlab 5
Here, the "5" is the commandline input to the function that
tells it the size of the desired magic square.
Now, I could have printed out a magic square hours ago by calling MATLAB's magic function directly. Or I could have run my magicsquare.m function. What have I gained by creating this almost executable file?
Suppose my laptop at home does not have a copy of MATLAB installed. I can take my almost executable file, and the shell script home. I can then run my MATLAB program there ... without MATLAB! Now actually, before I do that, I have to make sure I've installed the MCR on my home laptop, but that can be freely downloaded from the Mathworks website, perhaps at http://www.mathworks.com/products/compiler/mcr/. When I run my shell script on my laptop, I must again note where the MCR is on this machine, which might be /usr/local/matlab again, or perhaps some other directory.
But now suppose I have a colleague in another country, who uses a different kind of computer, and doesn't have MATLAB. I can send that colleague, by email, my compiled file, and if she can install the MCR, she can run my program.
Finally, note that many people have access to a computer cluster. The computer cluster may have a front end where people are encouraged to edit, compile and work interactively, and many back end or remote nodes, where only computation takes place. For various reasons, it is possible that MATLAB will be installed on the front end, but not on the remote nodes. For instance, the remote nodes may not be able to communicate with the MATLAB license server; or MATLAB may not be licensed to run on the remote nodes.
That means that you can't create a batch job for a remote node to execute a MATLAB function for you, whose "interesting" line might be
/usr/local/matlab < my_prog.m > my_output.txt
Again, the MATLAB compiler comes to the rescue. Assuming that your system administrator will install the MCR on the remote nodes, which does not require a license payment or contact with the license server, then you can run your executable on the remote node with a command something like what we saw earlier:
./run_magic_example.sh /usr/local/matlab 5
where /usr/local/matlab may need to be changed to wherever
the MCR has been installed on the remote node.
By the way, another possible advantage to using the MATLAB compiler is that your program will no longer incur the interactive overhead involved with the MATLAB interpreter; it is possible, then, that the compiled program will run with an efficiency similar to programs compiled in C or FORTRAN, if the interactive version of the program was slowed down by a lot of overhead expense.
The computer code and data files made available on this web page are distributed under the GNU LGPL license.
MATLAB_COMMANDLINE, MATLAB programs which illustrate how MATLAB can be run from the UNIX command line, that is, not with the usual MATLAB command window.
MATLAB_CONDOR, MATLAB programs which illustrate how MATLAB can be run in batch mode using the condor queueing system.
MATLAB_DISTCOMP, a MATLAB program which remotely runs a set of 5 jobs on the Ithaca cluster.
MATLAB_REMOTE, MATLAB programs which illustrate the use of remote job execution, in which a desktop copy of MATLAB sends programs and data to a remote machine for execution. Included is information needed to properly configure the local machine.
MOAB, examples which illustrate the use of the MOAB job scheduler for batch execution of jobs on a computer cluster.
SGE, examples which illustrate the use of the Sun Grid Engine (SGE), a job queueing system whose input is a modified form of shell scripts in the BASH shell, C shell, and so on.
MAGICSQUARE is a tiny example of a function that can be compiled. It expects as input from the user the size N of a magic square, calls MATLAB's magic() function, and returns the magic square as an output argument. However, when I ran this example, I didn't see the magic square, because the function doesn't print it, and I don't know how to "capture" the function's output. So this was a very unsatisfactory example.
MAGICSQUARE_PRINT repeats the previous example, but doesn't bother returning a function value (which I don't know how to retrieve or work with). Instead, I let MATLAB print the matrix by default (by removing a semicolon from the previous function) and then added some explicit printout statements with fprintf(), and luckily, the matrix actually showed up twice as output.
MAGIC3 repeats the previous example, but includes a call to a user-written M-file called "timestamp()", which simply prints out the data. I wanted to know that the compiler can handle a program that is provided in "pieces".
You can go up one level to the MATLAB source codes.