speech-tools/config/ReadMe

		Edinburgh Speech Tools Configuration
		====================================

Contents
--------
	1 How Configuration Works
	2 Quick Configuration
	3 Adapting The Configuration For Your System
	4 Adding a New Optional Module

			--o--oOo--o--

1 How Configuration Works
-------------------------

The configuration for the system is set in 4 sections

    A system description in `config/systems/' describes the common
	layout for this kind of system.

    A compiler description in `config/compilers/' describes the
	options available for the compiler, how to build shared
	libraries etc.

    Configuration descriptions in `config/configs/' describe some
	common differences from the default configurations.

    Anything you put at the end of config/config.

The next two sections describes some of the things you might need to set


			--o--oOo--o--

2 Quick Configuration
---------------------

Copy the file `config/config-dist' to `config/config'.

Load `config/config' into your editor and read through it, selecting
what compiler to use, which festures you wish to include in the system
and so on.

Run `gnumake info' in the top level speech_tools directory to see what
the system thinks of your configuration.

If all looks well, `gnumake' will build the system.

We have tried to make it compile `out of the box' on as many systems
as possible. However the idiosyncratic details of your system may
mean you have to do some 


			--o--oOo--o--

2 Quick Configuration
---------------------

Copy the file `config/config-dist' to `config/config'.

Load `config/config' into your editor and read through it, selecting
what compiler to use, which festures you wish to include in the system
and so on.

Run `gnumake info' in the top level speech_tools directory to see what
the system thinks of your configuration.

If all looks well, `gnumake' will build the system.

We have tried to make it compile `out of the box' on as many systems
as possible. However the idiosyncratic details of your system may
mean you have to give some information.

We have included a mechanism for noting common variations from the
default configuration for a given system type. These variations can be
listed in the CONFIGURATIONS line of the config file. At the moment
only one generally useful variation is defined

	egcs_as_gcc	This system has the egcs C++ compilation
			system installed under the names gcc and g++.

If you need to give the system more detailed information about your
situation, for instance where libraries are located, you will need to
add definitions to the end of `config/config' as desribed in the next section.


			--o--oOo--o--

3 Adapting The Configuration For Your System
--------------------------------------------

We have included pre-defined configurations for a number of different
types of system. Also some variants we know about are described by
options which can be included in the CONFIGURATION line in the config
file, as described in the previous section.

However, if your system has some of the libraries or programs which
the speech tools use installed in unusual locations you will need to
add settings to the end of `config' to say where they are.

Below are the settings you are most likely to need to fix in this way
and typical values. Copy the relevant ones to the position indicted at
the very end of config and customise as necessary.

###########################################################################
## Location of libraries.

###########################################################################
## Where to find Network Audio

NAS_INCLUDE = /usr/X11R6/include
NAS_LIB = /usr/X11R6/lib

###########################################################################
## Where to find X11

X11_INCLUDE = /usr/X11R6/include
X11_LIB     = /usr/X11R6/lib

###########################################################################
## TCL support

TCL_INCLUDE = /usr/local/include
TCL_LIB     = /usr/local/lib

###########################################################################
## Efence library for malloc debugging

EFENCE_LIB = /usr/local/lib

###########################################################################
## Java class path

JAVA_HOME = $(pack $(shell echo "$$JAVA_HOME"))

SYSTEM_JAVA_CLASSPATH = $(pack $(shell echo "$$CLASSPATH"))

JAVA_INCLUDES  = -I$(JAVA_HOME)/include -I$(JAVA_HOME)/include/solaris

###########################################################################
## Programs

## make dependancies
MAKE_DEPEND = makedepend $(INCLUDES) $(TEMPLATES) $(TEMPLATE_SPECIFIC)

## Normal library building
BUILD_LIB =$(AR) cruv

## library indexing
INDEX_LIB = $(RANLIB)

## shrink executables
STRIP = strip

## different types of awk. For our purposes gawk can be used for nawk
AWK = awk
NAWK = nawk

## Just in case someone has a broken test
TEST = test

## Must understand -nt
GNUTEST = gnutest

## Avoid clever RMs people may have on their path
RM = /bin/rm

###########################################################################
## Any other command line arguments which you need to pass to your
## compiler to compiler the system.

CONFIG_DEFINES = 
CONFIG_INCLUDES = 
CONFIG_TEMPLATES = 
CONFIG_LIBS = 

			--o--oOo--o--

4 Rationale
-----------

It may help to know why this configuration system is how it is.

Most of the pieces of software distributed in source form via the
internet and similar channels are simpel tools. The aim of people
getting them is to have a working system as quickly and easily as
possible. For such systems having a configuration script which when
run works out some combination of options and so on which will let the
system compile is ideal.

However, the Edinburgh Speech Tools and Festival are designed as
research platforms. While many people just want to compile and go,
many want to be able to change how the system is configured, what
compiler to use, what facilities to include and so on easily. To
support this the configuration system needs to:

	(a) Determine what kind of system we are on, which awk to use
	    and so on.

	(b) Find out where the required third party libraries and
	    so on are hidden on this system.

	(c) Allow the user to change between compilers, java
	    development systems etc.

	(d) Allow the user to select compilation options (optimisation
	    level, debugging, whether to compile shared libraries)

	(e) Allow the user to include and exclude the various optional
	    sections of the system.

A normal configuration script can, with various amounts of ingenuity,
do (a), but for the rest it would be necessary to supply information
on the command line to the script. 


			--o--oOo--o--

5 Adding A New Optional Module
------------------------------

If you wish to add new code to the speech tools you should, initially
at least, make a new optional module. This will let you include or
exclude your extension from your config file.

First you must decide on a unique name for your module. There is a
list of existing module names in `config/project.mak'. For the example
below we'll assume this new module is called `widgets'.

Create a directory for your module. Where you put it will depend on
where you think it fits logically into the existing hierachy. For the
example we will imagine the `widgets' module is used to manipulate
some kind of representation of linguistic structures and put it under
`ling_class'.

	mkdir ling_class/widgets

In the `widgets' directory you need to create 2 files, a `Makefile'
controlling the compilation of that directory and a `widgets.mak' file
which describes how it fits into the speech_tools.

Follow the structure of `example.Makefile' and `example.module.mak' in
this directory.

Once you have created your module you just need to turn it on in your
`config' file. Add a line like:

	INCLUDE_MODULES += WIDGETS