This directory contains Uni, the central part of the UniForM workbench.
The source of Uni is in the following directories.  The further you get
down the list, the less reliable things will be!


   directory    |  contents
   
   mk           |  Makefile magic which set up default rules and variables
   util         |  Miscellanous Haskell functions used all over Uni
   events       |  Events, providing a way for concurrent events to 
                |  communicated
   reactor      |  Miscellaneous things for running processes and tools
   posixutil    |  Various utilities that only work under Posix.
   htk          |  This is an encapsulation of Tcl/Tk in Haskell
                   See htk/examples for a few short introductory examples.
   graphs       |  General framework for shared graphs.
   davinci      |  This is an encapsulation of DaVinci in Haskell
   HaXml-1.11   | This contains the complete source of HaXml.  This is
                | included by uni, but is completely unchanged from the
                | official distribution, which is currently the responsibility
                | of Malcolm Wallace. 
  
   HaXml        | We compile HaXml, if necessary, in this directory.
   server       |  Stuff for client-server relationships
   simpledb     |  A very simple database system.
   types        |  Repository
   emacs        |  Contains the code for editing MMiSS objects with XEmacs
   mmiss/parser |  (Un)Parses LaTeX sources for MMiSS objects.
   mmiss        |  General code for MMiSS objects.
   mmiss/api    |  Code for interfacing MMiSS via an API (UNDER CONSTRUCTION)

   appl         |  Stand-alone UniForM applications


Only the Haskell code in util, events, reactor and htk is known to work under
Windows.  Everything else requires Posix, and so, Unix/Linux.

This module does not contain uni or HTk documentation.  For that you need
the uni-docs module.  This can be obtained (in binary form) from
the HTk homepage, 
   http://www.informatik.uni-bremen.de/htk

Requirements for compiling UniForM
----------------------------------

The following are required or at least recommended. 
(1) gcc.  Ideally what I use -- gcc version 2.95.2.
    Do not use 2.8* versions since they are known not to work at all with 
    Glasgow Haskell.  Version 2.71 might work but I suspect Glasgow Haskell 
    will not support it for much longer.  I have had problems with version
    3.*.  I think the current situation (March 2003) is that Glasgow Haskell
    can probably work with gcc 3.* on Linux, but not on Solaris.
(3) GNU make.  Again, use the latest one - 3.77.  But I think slightly earlier
    ones may well work.
(4) A recent version of Glasgow Haskell.  We are currently using 6.0.1.
(5) If you want to compile the HTk documentation, you will need hdoc
    whose homepage is
       http://www.fmi.uni-passau.de/~groessli/hdoc/
    You will need version 0.8.1 or later.
(6) A lot of memory will help during HTk (or virtual memory and a lot of
    patience).  250MB would be nice.  If you still get problems see the
    section on "Restarting compilation".
(7) If you are unfortunate enough to be using Windows, you will also need
    Cygwin or MinGW.  The following instructions assume that you are in a 
    Cygwin or MinGW shell where the usual Unix utilities (sed, find and so on)
    are available.  However you will be glad to know that you do NOT need
    a version of GHC which is Cygwin-aware.  We convert filenames into their
    Windows equivalents (well, more or less) before passing them to GHC.
(8) If you want to compile the repository stuff (not needed for HTk or
    daVinci) you will need to compile and install the Berkeley Database.  You 
    can get this from 
       http://www.sleepycat.com
    You should give BDB's configure a special option, --disable-shared.  
    This means that BDB is produces static libraries, so you won't need
    to set up LD_LIBRARY_PATH and carry around the BDB dynamic libraries
    to call MMiSS executables. Thus, in BDB's directory 
    [BDB source]/build_unix you might use the command
       ../dist/configure --disable-shared
    You might also want a "--prefix" option, to specify a directory BDB
    should write its compiled stuff to, if you do not have write access to
    the standard system directories.

    UniForM does also of course need to know where to find the compiled BDB
    stuff, if they are not in the standard place.  You can tell it either
    by setting the environment variable BDBDIR, or by giving UniForM's
    ./configure script an option --with-bdb=[directory path].
(9) To run MMiSS and TeX the output, you will need MMiSS TeX.  This is 
    *not* currently in the public domain.  However assuming you have it,
    and have configure'd it, UniForM again needs to know where to find it.
    It will guess /usr/local/MMISS/tex, but if MMiSS-LaTeX is not there
    you can specify its location with the environment variable MMISSLATEXDIR,
    or by a ./configure option --with-MMiSS-LaTeX=[MMiSS-LaTeX directory]).
    (The name of this directory will most likely end "MMISS/tex".)

Of course you also need the sources to Uni!  They should be with this
README file, but in case they are not, or in case you want to update
your copies, here are details.  The Uni sources are kept in a 
publicly accessible CVS repository at cvs-agbkb.informatik.uni-bremen.de.  
For general details about this repository, see
   http://www.informatik.uni-bremen.de/~ger/cvs/CVS.html
So for example to get a complete set of the latest version of the sources you 
type (in bash or sh)

export CVSROOT=:pserver:cvsread@cvs-agbkb.informatik.uni-bremen.de:/repository
cvs login
# when cvs login asks for a password, type "cvsread"   
cvs checkout uni

This will create a directory uni in your current directory containing
the latest sources for uni.  

Type "man cvs" to find out other CVS commands.

What To Ask Before Compiling
----------------------------

1) Do you want a debugging version of Uni?  By default you won't
   get it.  To compile a debugging version, 
      cd uni/mk
      cp local.mk.debug local.mk
   The file local.mk is included, if present, by every Makefile.
   Thus it's also a good thing to use for other Makefile hacking.
2) Do you want to use the Tk-encapsulation (in directory "htk")?  
   Then you will need to a copy of Wish, which should be provided as 
   part of your X-system.  It needs to be in your PATH when you
   run the ./configure step (see the next section).  If, when you
   type "wish", a square blank window pops up with the title "wish"
   then you should be alright.  Type "info tclversion" to see what version
   you have.  For Unix, you will need at least version 8.0; for Windows,
   you need at least 8.1.1 (I think), though in both cases it is probably
   better to use a later version if you have one.

   Some of the programs in HTk use a more sophisticated Tk-encapsulation
   known as tixwish.
3) Do you want to draw graphs using Uni's daVinci encapsulation
   (in directory "davinci")?  Then you need DaVinci.  You can get 
   this from:
      http://www.informatik.uni-bremen.de/daVinci/
   Once you have it, put it in your PATH, with the name "daVinci",
   for the ./configure step.
4) Do you want to use our versioning system (in "cvs" and "types")?
   Then you need cvs, probably version 10.7 or thereabouts.
   Again, put it in your PATH for the configure step.

Compiling
---------

Once you've done all that, the following commands are supposed to do
it, assuming that you are in the same directory as this README file
(that is, at the top of the Uni distribution).
   
# Configure the Makefiles
./configure
# Work out what order to do compilation in
gmake boot
# Compile Uni
gmake all

Other Make targets for UniForM developers
-----------------------------------------

The 
   ./configure
   gmake boot
   gmake all
sequence described above is just if you want to build the whole thing from
scratch.  Once you've done this, you may want to modify a file and then
recompile. 

The Make targets described in this section all work in any directory of uni
that contains a Makefile.  If you use then in a subdirectory, they will only
apply to that subdirectory.  For example, if you have modified a file, you
can do
   gmake all
in the directory containing that file

As described in the next section "Makefiles for uni", source files are
divided into package files, test files and main files.  You can use
   gmake package
   gmake test
or
   gmake main
to compile just the files you are interested in.  Of course, to compile
the test or main files, you should already have compiled the package files.

You can also compile any individual file.  This is often useful when you
modify one file and want to get GHC to check it.  First, as preparation, you
need to do
   gmake depend
and then you can use
   gmake [object file]
where the object file for, say, Foo.hs is Foo.o.

If you add a source file, or want to add a whole new subdirectory with its
own Makefile, you will need to modify a Makefile.  These are described in
the next section.

Makefiles for uni
-----------------

In each subdirectory of uni there is a file Makefile.in.  If you want to
create another new package you will need to copy this file.  It normally has
the following format:

---- cut here --------------
SRCS = foo1.hs foo2.hs foo3.lhs . . .
PACKAGE = [package name]
PACKAGES = package1 package2 . . .

include @TOP@/mk/boilerplate.mk
---- cut here --------------
Thus we have a list of variable settings (which may be in any order),
then we include the general Make magic.  

SRCS contains all the Haskell source files in this directory.
   The Makefiles interpret these specially according to name.
   Files with names of the type "Test*.hs" or "Test*.lhs" are test programs,
      should contain a module Main, and will be compiled to an executable
      with name "test*", or "test*.exe" on Windows, for example "TestFoo.hs"
      will go to "Foo" or "Foo.exe"
   Files with names "Main*.hs" or "Main*.lhs" are just the same
      as files "Test*.hs" or "Test*.hs", except that the final executable
      is just called "*", so "MainFoo.hs" goes to "Foo".
   All other files are package files.  They should contain a module with the
      name of the file (so the file Foo.hs must contain the module Foo; the
      module subdir/Bar.hs must contain the module Bar).

PACKAGE is the name you want to give to the package contained in this 
   directory.  Normally this name begins with "uni-". This should be
   specified if and only if the directory contains library files.
PACKAGES is the list of packages you will need.  This includes
   GHC packages (net and posix for example) and also UniForM packages
   (like uni-htk).  You only have to give direct dependencies here; for
   example uni-htk imports uni-util, so if you specify uni-htk, you do not
   need uni-util.   

The following variables also occur occasionally:
SUBDIRS specifies a list of subdirectories of this directory also containing
   Makefiles, into which we should recurse.
SRCSC is like SRCS, but expects a list of C files.

Some special targets are occasionally optionally defined.  These include
   dochere
If a Makefile defines this target it will be executed when gmake doc is
done; it should compile any documentation in this directory.
   wwwhere
If a Makefile defines this target it will be executed when gmake www is done.
This should copy any appropriate files over to the Web page.

Makefile.in can also contain variable settings which, for example, specify
   special GHC options to use, but I shall not explain this here.  You may
   be able to work some of them out by looking at the Makefiles, for example
   htk/Makefile.in.

After you've modified a Makefile, if you have time on your hands you should run
   ./configure 
(from the top directory)
followed by 
   gmake packagesquick
to reset the package file.  You may also need to run
   gmake depend
if the import dependencies between the files you are working on have changed
and you want Make targets "lib" or individual object files to work.
 
However in many cases it will be possible to get away with
   gmake makefilequick
to regenerate the Makefile in the current directory.  (This assumes that
one is already there.)  This technique assumes you've changed that Makefile, 
and nothing else relevant to configuration.  (For example, it assumes you
haven't added any new Makefiles.) 

Making documentation
-------------------------


gmake doc should work.

However at present no documentation should be in this directory; it
should all be in the module uni-docs.

How to Make a Binary Distribution
---------------------------------

The following (should) work.

# of course you can skip the next three commands if you've already done them
   ./configure
   gmake boot
   gmake packages
#
   gmake doc
   gmake prepareexports
   gmake exports

This will create .tar.gz and .zip files containing a binary distribution
(the names begin with uni- and includes version numbers and so on).  
You should afterwards re-run ./configure as gmake prepareexports (currently) 
alters the default_options code in util, to put in generic locations for wish,
daVinci & co.

For systems where hdoc & LaTeX are not installed you could for example
find a machine where you CAN build the documentation, do it there,
and prepare a .tar.gz archive containing the documentation with the
following:
# cd to the documentation directory.  This is the only one at present.
   cd htk/doc
# Make the exports for just this directory
   gmake exports
You will get two archives, one .tar.gz and one .zip.  Pick whichever is
most convenient and unpack on the machine where you are preparing the binary
distribution.  You can then gmake exports at the top directory for the
target directory.

How to copy the documentation and binaries onto the web site
------------------------------------------------------------

Assuming that the web site and binaries are mounted on your machine set
the variable WWWPREFIX to its location as a file path for the directory,
not including the final slash.  You can do this either as an environment
variable, on the make command line, or in mk/local.mk.  Then do
   gmake www


Restarting compilation
----------------------

If you try to compile HTk with too little memory, Glasgow Haskell will
fall over, because it is trying to compile too many files at once, and suddenly
comes across a really big one it can't handle.  You can try making the
individual object file which GHC gave up on:
   cd htk
   gmake toolkit/Notepad.o
where instead of toolkit/Notepad you put whatever module caused the problems.
Then restart with
   gmake packages
and hope the problem doesn't reoccur.

If this fails you can go back to the old method of compiling the modules
one by one.  The simplest way is probably to do (from the top directory)
   gmake packagesquick # Needed if you haven't already completed a build
   gmake depend # Sets up .depend files for Make
   gmake lib # Compiles everything, but one by one.
   gmake packagesquick # Complete the build.  (Yes, you've already done this.)

In theory object files produced by this method should be just the same 
as those produced by the new one.

Other documentation
-------------------

The htk/doc directory contains various documentation about htk.

You should start with htk/doc/intro, which is an introduction.

htk/doc/hdoc contains hdoc-style information indexing modules, variables,
   classes and so on.  The files (once documentation is made) are in HTML.

htk/doc/internal/HOWTO.tex contains a description of the internals of the HTk
   encapsulation; this will be most useful if you want to modify this
   encapsulation in some way.  Hence it is heavily technical.  Just to make
   things more fun, it is in German.  Do let us know if you want a translation.


docs/future contains some notes on the future development of UniForM
(some of which has already happened).

More information about Make targets
-----------------------------------

Make targets are those names you put after "gmake", like "depend" and "all"
in the above instructions.

Most Make targets can be used in any directory of the UniForM source
containing a makefile, not just the top one.  
"depend" does various necessary setting up.
"all" does the actual compilation, once depend has been run.
"packages" is like "all", but just compiles the packages, not the stand-alone
   executables.
"test" makes all the test programs, that is stand-alone executables compiled
   from Haskell modules beginning with "Test".
"main" makes all the main programs, that is stand-alone executables compiled
   from Haskell modules beginning with "Main".  (The prefix "Main" is removed)

"clean" deletes all the output of "all".

The following two options fall into this class, but are experimental and
likely to change in the near future.
The following targets are provided by the top-level Makefile:

"tarball.tar.gz" makes a tarball (with that name) of all UniForM sources.

There are some other targets, but you will have to look in mk/suffix.mk
and Makefile.in to see what they are.

Other Makefile Hacking
----------------------

The file mk/local.mk (mentioned above) is included in every Makefile if
present, and can be used to change the options and provide extra targets.

Conclusion
----------

Please report problems to me.  I am George Russell and my e-mail
address is ger@tzi.de .

Good luck!


