annotate INSTALL.txt @ 67:b8f8ed1ef8dd tip

Provide .wav suffix in delivered filename

=== Build Instructions ===


== Prerequisites ==


= MATLAB Compiler Runtime (MCR) =

The MCR allows you to run compiled MATLAB applications or components
without installing MATLAB.

In this WebApp we are redistributing pre-compiled MATLAB code in
isvr.jar (found at WebContent/WEB-INF/lib/isvr.jar).

To install MCR, please proceed to:

    http://www.mathworks.co.uk/products/compiler/mcr/

and follow the installer's instructions.  You need to install MATLAB
MCR 2013b (8.2).

Attention: take a note of the environment variable DYLD_LIBRARY_PATH
which the MCR installer will show - if this is not correctly set the
webapp will not run.


= System variables =

On OSX you need to do the following (if you installed MCR to the
/Applications/MATLAB/MATLAB_Compiler_Runtime/ folder):

        export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Applications/MATLAB/MATLAB_Compiler_Runtime/v82/runtime/maci64:/Applications/MATLAB/MATLAB_Compiler_Runtime/v82/sys/os/maci64:/Applications/MATLAB/MATLAB_Compiler_Runtime/v82/bin/maci64

        (Please not that only the above paths are necessary.)

If you have MATLAB installed, the path is probably:

        export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Applications/MATLAB_R2013b.app/sys/os/maci64/:/Applications/MATLAB_R2013b.app/runtime/maci64/:/Applications/MATLAB_R2013b.app/bin/maci64/


= Other jar files =

1. Copy your web server's servlet-api.jar file into this directory:

        (For example, on Linux you might find this file in /usr/share/java/tomcat7/servlet-api.jar)

        cp $CATALINA_BASE/libs/servlet-api.jar .


2. Copy the javabuilder.jar file from your MATLAB or MCR install root
into the webapp lib folder:

        (if you installed the MATLAB MCR to /Applications/MATLAB/MATLAB_Compiler_Runtime/)

        cp /Applications/MATLAB/MATLAB_Compiler_Runtime/v82/toolbox/javabuilder/jar/javabuilder.jar ./WebContent/WEB-INF/lib/


== Building the Web Application (echoapp.war) ==

3. Run 'ant -f build.xml'. This should create the echoapp.war file. If
this fails, follow "Compiling and Generating the echoapp.war file"
instructions below.

4. Copy the echoapp.war file to your web server's webapps folder:

        cp echoapp.war $CATALINA_BASE/webapps

5. Start/Restart Tomcat, making sure the webapp is correctly deployed;

6. Start the web server and navigate in a browser to the following url:

        http://localhost:8080/echoapp/


== Compiling and Generating the echoapp.war file ==

Note: You only need to follow this instructions if run 'ant -f build.xml'
correctly and you were unable to generate the echoapp.war file. The
steps described in this section assume that you already have a working
version of the isvr.jar package. The isvr.jar file should be located
in WebContent/WEB-INF/lib/isvr.jar.

1. Copy the deployed component from the scratch folder to the web
applications lib folder:

    cp ./scratch/isvr.jar ./WebContent/WEB-INF/lib

2. Compile the web application, making sure to reference the
servlet-api.jar, the deployed component jar, and the javabuilder.jar:

    javac -cp servlet-api.jar:./WebContent/WEB-INF/lib/javabuilder.jar:./WebContent/WEB-INF/lib/examples.jar: -d ./WebContent/WEB-INF/classes ./src/HumanEchoServlet.class

This will create the servlet:

    WebContent/WEB-INF/classes/HumanEchoServlet.class

3.4. Navigate to the web applications directory and create the war file.

    cd WebContent
    jar -cvf ../echoapp.war .
    cd ..


== Building isvr.jar ==

If you have access to the MATLAB code and wish to make any changes to
its core functionality, you can recompile the isvr.jar package.

You can only compile the isvr.jar if you have MATLAB and the
JavaBuilder toolbox: please check this with you systems administrator.

To compile isvr.jar, simply run 'ant -f build-isvr.xml'.

If this fails, you may be able to recompile the MATLAB component by
running the following MCC command:

    /Applications/MATLAB_R2013b.app/bin/mcc -W "java:uk.ac.soton.isvr,HumanEcho" -d ./scratch -T "link:lib" -v "class{HumanEcho:./mcode/simulateBinauralSignals.m}"