== HOW TO USE MARY IN ECLIPSE ==
----

This document describes how to import the MARY source code as a project into Eclipse. 
These steps are written based on Eclipse 3.5. 
They should work under linux and, with minor adaptations, under windows.

'''Dependencies:'''
 

 - JRE 1.5 (JRE 5)	
 - JDK 1.5	 (JDK 5)
 - Eclipse (http://www.eclipse.org/downloads/)
 - svn (tested with svn version 1.4.6)


There are two possibilities to get access to the MARY source code: 

 - '''From the installed version of MARY TTS system''' 

    '''Precondition:''' You must have installed the MARY TTS system including the "source" package. We will refer to the installation directory (e.g., "/home/myself/MARY_TTS" on linux or "c:\Program Files\MARY_TTS" on windows) as $MARY_BASE.

 - '''From the 'svn' repository available at [http://mary.opendfki.de/wiki]'''

    '''Precondition:''' Checkout OpenMary from current trunk (Lets say checkout directory as $MARY_BASE )
{{{
$ svn checkout https://mary.opendfki.de/repos/trunk $MARY_BASE 
}}}

    Ex:
{{{
$ svn checkout https://mary.opendfki.de/repos/trunk /home/myself/openmary 
}}}



'''Common instructions for Eclipse configuration:'''


1. Verify/adapt a number of general settings in Eclipse. From the Eclipse
   menu, select "Windows"->"Preferences...". In the dialogue window that opens,
   verify/adapt the following settings:
   - Source file encoding: "Workbench"->"Editors"->"Text file encoding"
     must be UTF-8 (Note: may be under "General"->"Editors"->"Text file encoding"
     on the Linux version of Eclipse)
   - Java version used: "Java"->"installed JREs" must be 1.5
   - Java source compatibility: "Java"->"Compiler"->"Compliance and Classfiles"
     "Use default compliance settings" must NOT be ticked; all of the following
     must be set to 1.5:
     "Compiler compliance level"
     "Generated .class files compatibility"
     "Source compatibility"

2. Import the MARY-project in Eclipse:
   In Eclipse, select from the "File" menu "Import", then click on
   "Existing Project into Workspace".
   Click "Next", then "Browse" and select the mary directory $MARY_BASE 
   (for example "/home/myself/MARY_TTS").
   Then click "Finish".
   If you get errors about jar files missing, verify the project settings
   under "Project"->"Properties"->"Java build path"->"Libraries". Remove or 
   "Add external JARs" as appropriate -- all required .jar files should be
   found under MARY_BASE/java.

At this stage, the code should compile without errors. Now, we need to
add some more settings in order to start the MARY server from within
Eclipse (e.g., for quick debugging).

{{{
#!comment

3. Define a number of environment variables.
 a) Under linux, add to the file ~/.bashrc:
      export MARY_BASE=/home/myself/MARY TTS
      export SHPROT_BASE=$MARY_BASE/lib/modules/shprot
      export LD_LIBRARY_PATH=$MARY_BASE/lib/linux:$LD_LIBRARY_PATH
 b) Under Windows, right click "My computer"->"Properties"->"Advanced"->
    "Environment variables...".
    Under "user variables", add new variables using the "New..." button:
       MARY_BASE "c:\Program Files\MARY TTS"
       SHPROT_BASE "c:\Program Files\MARY TTS\lib\modules\shprot"
    Under "system variables", "Edit..." the variable "Path". To the existing
    content of the Path variable, append the following:
       ;c:\Program Files\MARY TTS\bin;c:\Program Files\MARY TTS\lib\windows
}}}

3. To define a run target: From the menu, select "Run"->"Run configurations..".
   Click "New" in order to add a Mary process:
   Name=Mary, "Main"->"Main class"=de.dfki.lt.mary.Mary
   In the "Arguments" tab, add the following lines into the "VM Arguments"
   field:
   
   -Xmx256m -Dmary.base=$MARY_BASE -ea
   
   If you don't use Java 1.5, you also have to add the following into the same
   field:

   -Djava.endorsed.dirs="$MARY_BASE/lib/endorsed"

   For debugging informations displayed in Eclipse, you also have to add the 
   following:

   -Dlog.tofile=false -Dlog.level=debug
   
   If you don't plan to use the Tibetan voice, add:
   
    -Dignore.tibetan.config

   Click "Apply" to save these settings.

4. If you click on "Run" now, the process (MARY Server) will start.
   

5. If you want to start a MARY Client, open following link in web browser (ex: firefox 3.5)
   
   [http://HostName:59125/]  (HostName = MARY Server running system;  Ex: [http://localhost:59125/])