Human Echolocation WebApp

h1. Modifying the MATLAB

h2. Context

You want to change something in the MATLAB code and deploy the changed version.

h2. You will need

 * A computer with a licensed copy of MATLAB. This step uses the "mcc" compiler included in the MATLAB distribution.

 * The Java development kit (JDK) of whichever version your MATLAB installation expects. Current MATLAB seems to call for Java 7.

You do *not* need the separate MATLAB compiler runtime package at this stage.

The computer you run this build step on does *not* need to be the same kind (make, platform, architecture, operating system) as the server you intend to deploy the web app on. However, you do need to make sure you have the same version of MATLAB as the compiler runtime you will be using on the server.

The most likely "production" setup is to have a workstation or server with a licensed copy of MATLAB on it, and to use that for this step; and then to have a separate, different machine (such as a Linux server) without MATLAB installed but with the MCR, which is used for the subsequent web app build and deploy (see [[Modifying the webapp]]).

h2. What to change; limitations

The webapp repository includes the MATLAB code as a sub-repository, in a directory called @mcode@. Any MATLAB code in this directory can be called from the web app. The calling convention uses a MATLAB struct to pass the arguments, as you can see in the existing examples.

File access is a thorny subject. Compiled MATLAB is usually run in its own environment in which the current working directory is an unpredictable temporary location. It's safest to assume that the current working directory is unavailable or unknown, and to pass in a working or scratch directory as one of the MATLAB function arguments and then use paths relative to that.

h2. How to rebuild

In the main directory of the web app project (i.e. above the @mcode@ directory), either run the @mcc@ compiler directly or use the @build-isvr@ Ant task.

To run @mcc@ directly, you need a command like this (which is also documented in the INSTALL file)

<pre>

$ /Applications/MATLAB_R2013b.app/bin/mcc -W "java:uk.ac.soton.isvr,HumanEcho" \

    -d ./scratch -T "link:lib" -v "class{HumanEcho:./mcode/simulateBinauralSignals.m}"

</pre>

The paths will depend on your operating system and MATLAB version.

To use Ant, you just need to run

<pre>

$ ant -f build-isvr.xml

</pre>

However, the paths and suchlike are still system-dependent, so the Ant build file may have the wrong paths in it and may need fixing itself!

This should produce a file called @isvr.jar@ in the @scratch@ directory.

You will need to copy that file into the @WebContent/WEB-INF/lib/@ directory in the equivalent build tree on your server (or whatever machine you are going to rebuild the web app on -- see the rebuild section of [[Modifying the webapp]] -- that one *does* need to be at least the same kind of computer as your server).

One way to accomplish that might be to copy it to @WebContent/WEB-INF/lib/@ on this machine, then commit and push to version control, and then pull from the machine you are building the web app on.

Now proceed to the rebuild section of [[Modifying the webapp]].