Human Echolocation WebApp

h1. Overview of the MATLAB Compiler

h2. What it is

The "MATLAB compiler" is a program called "mcc" that ships with MATLAB. It compiles MATLAB code into (encrypted) binary code for the current platform. That is, it appears you must compile on the same machine architecture and operating system as you want to use the code on -- it doesn't cross-compile. You can then take this code to a different machine and run it using the (free) MCR runtime.

The compiler has a pretty wide range of options, described in the command-line help text (run @mcc -?@). Note that there are examples at the bottom of the help.

The most basic usage is

<pre>

$ mcc -m function

</pre>

to compile the MATLAB file @function.m@ into a standalone executable.

h3. Executing the file

If the compiled file is called @foo.exe@, it should be called as: 

<pre>

foo.exe arg1 arg2 

</pre>

*Note* that MATLAB assumes that *all arguments to be strings*, so if you are expecting doubles, integers, etc these should be *handled inside the function*. For instance, if arg1 is an integer, one can do the conversion using

<pre>

if ischar(arg1)

    arg1=str2num(arg1);

end

</pre>

Read more (including how to use matrices as arguments) here: 

http://www.mathworks.co.uk/support/solutions/en/data/1-18448/?solution=1-18448

h2. How to run the result on a different machine

The "target" machine doesn't have to have MATLAB installed or a MATLAB licence. You will need to install the "MCR runtime":http://www.mathworks.co.uk/help/compiler/working-with-the-mcr.html, but you don't need to be root to do it -- you can just install into a random directory somewhere. If you're doing that, note that the installer puts all manner of crap directly in the directory you give it, so be sure to make a new directory for it.

If you run @ldd@ or @otool -L@ (depending on platform) on your compiled binary, you'll see that it depends on various shared libraries:

<pre>

	libmwlaunchermain.so => not found

	libmwmclmcrrt.so.8.1 => not found

	libmwcpp11compat.so => not found

</pre>

You get these (in two separate locations, a @bin@ and a @runtime@) when you install the MCR. You can make the executable run by adding both locations to the @LD_LIBRARY_PATH@ when you run it. The MCR comes with lots of instructions, but you don't really need them if you don't want a GUI.

(The default compiled application is very slow to start up, and will either need additional configuration for GUI support or else will complain about the lack of it when it starts. Adding the @-R -nojvm -R -nodisplay@ options to the @mcc@ command-line should fix this, assuming a GUI is not in fact required.)

h2. Creating a C++ shared library 

http://blogs.mathworks.com/loren/2011/02/03/creating-c-shared-libraries-and-dlls/

On OSX I had to add the following to @DYLD_LIBRARY_PATH@: 

<pre>

  /Applications/MATLAB_R2011a.app/runtime/maci64/:/Applications/MATLAB_R2011a.app/bin/maci64/:/Applications/MATLAB_R2011a.app//sys/os/maci64/

</pre>

h3. Creating the shared library

(Example for the following code, using OSX 10.7.5 and MATLAB_R2011a)

File gensin.m:

<pre>

function gensin(freq)

%% generates a 2 second long sine wave of a given frequency

% freq should be in Hz

% writes the output to file out.wav

if ischar(freq)

    freq=str2double(freq);

else

    freq=double(freq);

end

fs = 44100;

t = 0:1/fs:2; % 2 second clip

y = sin(2*pi*freq.*t);

% writes the file - NBITS = 16

wavwrite(y, fs, 'out.wav');

end

</pre>

h3. Generating the library

<pre>

  /Applications/MATLAB_R2011a.app/bin/mcc -W cpplib:libmysine -T link:lib gensin

</pre>

This will create several files: 

* libmysine.h

* libmysine.cpp

* libmysine.dylib

* libmysine.exports

* mccExcludedFiles.txt

* readme.txt

h3. An example c++ program

<pre>

// testsin.cpp: generate a 2 sec sine wave

// code to exemplify how to use MATLAB code as a C++ library

//

// Example adapted from:

//   http://blogs.mathworks.com/loren/2011/02/03/creating-c-shared-libraries-and-dlls/

//   and http://www.mathworks.com/matlabcentral/answers/1720

#include "libmysine.h"

#include <iostream.h>

int run_main(int argc, const char *argv[])

{

    // I expecty only one argument which is the frequency

    // Initialize the MATLAB Compiler Runtime global state

    if (!mclInitializeApplication(NULL,0))

    {

        std::cerr << "Could not initialize the application properly."

                  << std::endl;

        return -1;

    }

    // Initialize the MySine library

    if( !libmysineInitialize() )

    {

        std::cerr << "Could not initialize the library properly."

                  << std::endl;

        return -1;

    }

    // Must declare all MATLAB data types after initializing the

    // application and the library, or their constructors will fail.

    // 100 Hz

    mwArray freq(100);

    gensin(freq);

    libmysineTerminate();

    mclTerminateApplication();

    return 0;

}

int main() {

    mclmcrInitialize();

    return mclRunMain((mclMainFcnType)run_main,0,NULL);

}

</pre>

h3. Compiling the C++ source with the library 

In order to do this you should use *mbuild*:

<pre>

/Applications/MATLAB_R2011a.app/bin/mbuild testsin.cpp libmysine.dylib

</pre>