INSTALLATION

Release notes

This documentation covers version 1.2.3 of the Edinburgh Speech Tools
Library. While previous versions of the speech tools were primarily
released solely to support the Festival Speech Synthesis System, the
Edinburgh Speech Tools Library now contains sufficiently useful tools
that it is of use in its own right.

Although hope that the speech tools has stabilised to a certain extent
and less structural changes will occur in future versions we don't
guaranteed future compatibility, although every effort will be made to
make upgrading as easy as possible. In addition, we warn that while
several programs and routines are quite mature, others are young and
have not be rigorously tested. Please do not assume these programs
work.

Requirements

In order to compile and install the Edinburgh Speech Tools you need
the following

GNU make

Any recent version, the various make programs that come with different
UNIX systems are wildly varying and hence it makes it too difficult to
write Makefiles which are portable, so we depend on a version of make
which is available for all of the platforms we are aiming at.

A C++ compiler

The system was developed primarily with GNU C++ (various versions from
version 2.7.2), but we also have compiled it successfully with a
number of other versions of gcc, and Visual C++.

Hopefully we have now sanitized the code sufficiently to to make it
possible for ports to other C++ compilers without too much
difficulty. But please note C++ is not a fully standardized language
and each compiler follows the incomplete standard to various
degrees. Often there are many but simple problems when porting to new
C++ compilers. We are trying to deal with this by increasing our
support. However, it is likely that small changes will be required for
C++ compilers we have not yet tested the system under.

However we feel this is stable enough to make it worthwhile attempting
ports to other C++ compilers that we haven't tried yet.

Before installing the speech tools it is worth ensuring you have a
fully installed and working version of your C++ compiler.  Most of the
problems people have had in installing the speech tools have been due
to incomplete or bad compiler installation. It might be worth checking
if the following program works, if you don't know if anyone has used
your C++ installation before.

          #include <iostream.h>
          int main (int argc, char **argv)
          {
             cout << "Hello world\n";
          }


Supported Systems

We have successfully compiled and tested the speech tools on the
following systems, except where specified we include support for both
shared and static versions of the libraries:

Sun Sparc Solaris 2.5.1/2.6/2.7
      GCC 2.7.2, GCC 2.8.1, gcc-2.95.1, gcc-3.2

Linux (2.0.30) for Intel (RedHat 4.[012]/5.[012]/6.[01],7.[01],8.0)
      GCC 2.7.2, GCC 2.7.2/egcs-1.0.2, egcs-1.1.2, GCC 2.95.[123],
      GCC "2.96", GCC 3.0, GCC 3.0.1, GCC 3.2, GCC 3.2.1

Windows NT 4.0, Windows95, Windows 98
      GCC with egcs (from Cygwin b20.1), Visual C++ 6.0.

As stated before C++ compilers are not standard and it is non-trivial
to find the correct dialect which compiles under all.  We recommend
the use of GCC 2.95.3 if you can use it, it is the most likely one to
work. Some of the compilers listed above produce a large number of
warnings when compiling the code.

Previous versions of the system have successfully compiled under SGI
IRIX 5.3, 6.x, OSF (Alphas) and HPUX but at time of writing this we have
not yet rechecked this version.  AIX4.3 probably works.

NOTE gcc-2.8.1 and egcs-1.0.2 fail to compile stats/wagon/wagon.cc and
main/ngram_test_main.cc when OPTIMISE is set to 3. This is due to bugs
in those versions of the compilers.  As both these compilers are now
old and on the way out we decided not to make our code unneccessarily
baroque in order to support these compilers.  Hence for those files
(alone) it is necessary to unset OPTIMISE in config/config.  Note
there are a few other files that have this problem but we have partial
support of control of optimization and use that facility when it
works.

Java Support

The java directory contains optional Java classes which give some
access to speech tools facilities from Java programs.  This has been
created to support the fringe graphical interface. There are three
levels of support enabled by the JAVA JAVA_MEDIA and JAVA_CPP options
in the config file. JAVA compiles some very basic classes intended to
allow very simple simulation of speech tools facilities in pure Java
programs. JAVA_MEDIA is similar but uses the Jva Media Framework to
play sound. JAVA_CPP compiles classes which use the Java native
interface to provide access to the actual speech tools C++ classes.

You may (for instance on Solaris using gcc) need to make shared
libraries for some compiler support libraries in order to comple the
full JAVA_CPP support. See Appendix A for details.

Windows 95/98/NT Port

We have done two ports of this code to Windows machines, one uses the
Cygwin package, which provides a Unix like environment under on Win32
systems, the other is a native port using Visual C++.

For our full Windows NT and Windows 95/98 ports we use the Cygnus
Cygwin environment (version b20.1) available from
http://sourceware.cygnus.com/cygwin/. Windows 98 is significantly more
stable than Windows 95, especially when many processes are started and
stopped as is the case when compiling with Cygwin. We strongly
reccoment 98 rather than 95 be used if at all possible. However with
both 95 and 98 you can expect Windows to occasionally lock up or
complain it is unable to start new processes or otherwise
missbehave. You will be restarting windows regularly. A Windows NT
system should not have these problems.

If you do use windows 95 or 98 the following rules (collected from the
cygwin mailing list) may give improved stability:

*	Run sh.exe not bash.exe. You lose command line editing but seem to
	gain massively in stablity.

*	Don't run sh.exe from a bat file (like cygwin.bat which comes with
	cygwin to run bash), rather set any variables you need (copied from
	cygwin.bat) in autoexec.bat.

*	Be sure to set CYGWIN32=tty

A recent experimental version of the cygwin system is supposed to fix
at least some of the win85/98 problems (see the cygwin web site), but
we haven't tried it.

The port using Visual C++ does not provide all of the features of the
Unix and Cygwin versions. You will need access to a Unix or Cygwin
system to create the makefiles used for the Visual C++ compilation.

Both Cygwin and Visual C++ ports have a number of limitations. 

Shared library creation is not supported.
      Creation of Windows DLLs is different enough from creation of Unix
      shared libraries that the support does not carry directly accross, and
      we haven't yet had time to work on it.

Java not supported
      Because the Java support is related to the creation of shared 
      libraries, this is also not yet implemented for Windows. 

Command line editing limited
      Because of the limits of the Windows DOS console window, the 
      command line editing in siod is less reliable (for instance on 
      very long lines). 

(Visual C++) Networking not supported
      Networking under Win32 is different from Unix in a number of 
      fairly fundamental ways, we haven't tackled this at all. 

There are no doubt other differences we hve not noticed. We don't use
Windows for any of our work and so the Windows builds of our systems
don't get the extensive use the unix builds do.

BUILDING IT

Configuration

All compile-time configuration for the system is done through GNU 
configure.  On most systems you can configure the system
by

          unix$ ./configure

This creates the file config/config which for most machines will be
suitble.  In some circumstances the default.s generated from this
may not be what you want and you may wish to edit this file.

For Linux we now fully support shared libraries and even recommend
them. However if you are going to do alot of development and don't
understand the consequences of shared libraries and getting
LD_LIBRARY_PATH correct (or what that is) we recommend you compile
unshared, the default. If you are going to simply run the speech tools
(and festival) then shared is a reasonable option. Uncomment the line
in the config file

          # SHARED = 1

Shared support under Solaris is complete for all the speech tools. If
you need to exec festival scripts using a version of festival built
with shared libaries, you must either execute them from a featureful
shell (e.g. bash), install the shared libraries in a standard place or
explicitly set LD_LIBRARY_PATH. Solaris's standard shell doesn't
support script excutaiton of shells within shells.

Simple choices for common set ups are given near the top of this
file. But for some sub-systems you will also need to change pathnames
for external library support.

Compilation

Once you have configured config/config you can compile the system. 

          unix$ gmake

Note this must be GNU make, which may be called make on your system,
or gmake or gnumake. This will compile all library functions and all
the executables. If you wish to only compile the library itself then
use

          unix$ gmake make_library

Note that if you compile with -g (uncommenting DEBUG = 1 is
config/config the library and the corresponding binaries will be
large. Particulary the executables, you will need in order of 150
megabytes to compile the system, if your C++ libraries are not
compiled as shared libraries. If you compile without -g the whole
library directory is about 12 megabytes on Linux (which has shared
libraries for libstdc++ or about 26 megabytes of Sparc Solaris (which
does not have a shared library libstdc++ by default). This is almost
entirely due to the size of the executables. C++ does not make small
binaries.

In general we have made the system compile with no warnings. However
for some compilers this has proved to be near impossible. SunOS
include files have a number of system declarations missing, so many
system functions (e.g. fprintf) will appear to be undeclared. Sun's CC
compiler also likes to complain about missing source for some code
even though the code exists within our system and is deliberately in
separate files ro make it modular.

To test the system after compilation 

          unix$ gmake test

Installing the system

All executables are linked to from speech_tools/bin and you should add
that to your PATH in order to use them.

Include files are speech_tools/include/ and the three generated
libraries are speech_tools/lib/libestools.a,
speech_tools/lib/libestbase.a and speech_tools/lib/libestring.a. For
most cases a three will be required.

If space is a preminium, compiled with the shared option (binaries
will be then be substantially smaller) and you can delete all .o files

Some aspects of the system have further dependencies which depend of
the option selected at compile time. Specifically the readline
libraries and Netaudio libraries.

Building on Windows 95/98/NT

There are two ways to build the system under Windows. The Cygwin
system provides a unix-like environment in which you can perform a
compilation as described in the previous sections. Cygwin is probably
the best choice if you can use that route.

Requirements:
MS Windows 2000
Visual C++ 6.0 + service pack 1
cygwin 1.1
speech_tools-1.2.3
festival-1.4.3

Download and install cygwin.
Optionally download emacs so you have a decent editor :)
Download speech_tools and festival tar.gz files.
Download required festival lexicons and voices.

Using cygwins bash shell:
  mkdir C:/festival
  cd C:/festival

Using cygwin's tar command unpack:
  tar xvfz speech_tools-1.2.3.tar.gz 
  tar xvfz festival-1.4.3.tar.gz
  tar xvfz festlex... festvox...
(where festlex... and festvox... are the voice and lexicon files you
need.  Do not use winzip to unpack the voices it corrupts them!)

Create Vsual C++ make files: (this may be slow...)
  cd speech_tools
  make VCMakefile
  cp config/vc_config_make_rules-dist config/vc_config_make_rules

  cd ../festival
  make VCMakefile
  cp config/vc_config_make_rules-dist config/vc_config_make_rules

Finally make festival init_modules code. (If you add new modules you
either need to edit init_modules.cc by hand or rerun this step.)
  make -C src/modules init_modules.cc

edit config/vc_config_make_rules and change:
  SYSTEM_LIB=c:\\festival\\lib
to:
  SYSTEM_LIB=c:\\festival\\festival\\lib
(or to wherever you unpacked festival)

Now switch to a windows command prompt.
If necessary execute: VCVARS32.BAT form the VC++ directory to set up
VC++ environment. (you may do this automatically at boot or login.)

Build speech_tools and festival:
  cd c:\festival\speech_tools
  nmake /nologo /FVCMakefile

  cd ..\festival
  nmake /nologo /FVCMakefile

At this point you should be able to run festival by typing:
  src\main\festival



