Welcome to the wonderous world of Brown software.  In this directory you
will find the software you requested (and possibly more).  It is all
being distributed in source form with the hope that you can compile it
on your machine.  We have actually tested this on a variety of machines
(notably suns) and things seem to work most of the time.




The Software:
--- --------


BWE

The Brown Workstation Environment.  This package provides an easy to
program interface to the window system.  It includes a wide variety of
tools including menuing utilities, a powerful base editor, window
layout, and structured displays.  It is used as the basis for all the
other packages.

DL

Brown's Dynamic Loader.  Several of the packages (not bwe but it
include here anyway) use dl in order to load objects files at run
time.

IDYL

A incremental dynamic loader.  Still experimental.  Works on sun4s
currently.  Limited distribution only.	Please contact us if you want
more information.

THREADS

A package that provides multiple threads of control in a single
address space.	Much like the MACH threads package except that it does
not require kernel support.  It does, however, require a 4.2 source
license so you must order this from Brown separately.

GARDEN

An extremely powerful (and large) programming and prototyping
environment.  GARDEN supports multiparadigm design.  Users are able to
design and use a variety of programming tools.	For example, a user
can draw a picture of an FSA, petri net, or flowchart and directly
execute it.  Depends on BWE, DL and THREADS.

FIELD

Brown's Unix based programming environment.  Unlike our earlier work,
such as PECAN and GARDEN, field is an open programming environment in
that it is easy to add standard Unix utilities such as debuggers to
the environment.  This all happens through a powerful message passing
based system that able to work across processes and machines.  Depends
on BWE and DL.


TANGO

Brown's newest algorithm animation package.  Unlike, our earlier
work with BALSA which required extensive programming effort to produce
high quality animations, Tango is designed to be easy to program.
Users annotate their source (using the field annotation editor) to
provide messages to animation software.





Building the Software
-------- --- --------


The scripts here are all restartable, i.e. if there is a problem, just
begin them again.  Most of the problems you will encounter (other than
hardware, etc) probably will relate to environment variables you have
set that overwrite those that we use in the makefiles.	Someday we'll
add lines to the install scripts to unset all of these.  For now, you
might want to try building with a relatively clean environment. Other
problems you will encounter deal with resources.  You will need to
have sufficient disk space (both here and in /tmp) and swap space in
order to compile (and eventually run) everything.

The software here is designed to exist in a common directory.  At
Brown, this is the directory /pro (soft linked to who knows where).
You can put it anywhere, but will probably want to set the environment
variable PRO to point to this location. The software also wants (at
times) the environment variables ARCH which should be set to the
architecture name (sun3 or sun4 on the suns -- see the arch (1)
command).  On non-sun systems you should define an arch command that
does something like "echo vax" or whatever you want to call the
architecture.

The INSTALL in this directory will install any combination of bwe, dl,
idyl, threads, gnumake, field, tango and garden.  Note that if you
ordered threads separately, then this should be installed in the same
directory as everything else here in order for the distribution to
work.  Bwe, field, garden, and tango all have separate INSTALL scripts
that can be run once the top level install script has built the
necessary tools.  The file example.install.out is a sample transcript of a
full installation.  In addition to building everything, the install
script will install it.  It currently installs it in $PRO/bin,
$PRO/include, and $PRO/lib.  At Brown, these are links to machine-type
dependent directorys and some of the names are changed to reflect the
fact that items in these directorys are implicitly machine dependent
(i.e. the bwe library is named libbwe_sun4.a in $PRO/bwe/lib but
libbwe.a in $PRO/lib).

The software we have runs on sun3 and sun4 under 4.0.3 (and 4.0.1 and
4.0 for that matter). If you really want to install it under 3.2 or
3.5 which does not support shared libraries, you should set the
environment variable NO_SHARED_LIBS before doing the install.  (This
only affects the dynamic loader, dl.)  Also, if you plan to run under
3.2 or 3.5 you might have to define the variable NOSIGIO (-DNOSIGIO in
the makefile appropriately) since SIGIO's do not quite work correctly.
This only occurs in the threads package.  Much of the software also
runs on vaxes and DECstation 3100's.  Porting to other systems is
doable, but not particularly easy.

The software also should work with sun's xnews.  There is a separate
font.family file in $PRO/bwe/ash/src and a separate font conversion
script in $PRO/bwe/fonts that can be used to set things up correctly.


Build Summary:

1)  Set the environment variable PRO to point the proper place.
2)  Make sure the 'arch' command works.
3)  Make sure you have enough room in tmp and on swap.
4)  Type 'INSTALL' in this directory.


Possible problems:

1)  Building these systems require about 8-10M of space in /tmp.
2)  Be sure that you are in X11.  The last thing done in building bwe requires
	a program open the display specified by the DISPLAY environment
	variable.
3)  gprof does not build on the decstation 3100.  Its not needed for field, but
	there will be a considerable number of errors.
4)  tango has a definition PRO=/pro in its Makefiles.  This is overridden by
	the install script, which should work correctly, but should be changed
	if you are going to work within the tango directorys.
5)  Building EVERYTHING takes about 2.5-3 hours on a sun4.  It leaves 36M of
	disk space used (including the initial 10).  Probably more space is
	required during the build.
6)  Your path should include the location of the X11 binarys, including
	the commands to build fonts (bdftosnf on a MIT X11, convertfont on
	xnews, etc.)



Road map for the BWE distribution:
---- --- --- --- --- ------------


README			This file.
INSTALL 		Executable shell script.  Type 'INSTALL' to build all
bwe			Brown Workstation Environment.
dl			Dynamic Loader
gnumake 		Free Software Foundation make program.
example.install.out	Example output from 'INSTALL' above.
threads.dummy		If you do not have the Brown threads package.






Documentation:
-------------


Documentation for the various packages can be found in the doc
directorys.  Much of the documentation is scanty right now, but
whatever we have is included.  Currently there is postscript format
documention in 'bwe/doc/*.ps'.






Copyright Information:
--------- -----------

The software located in bwe, dl, treads.dummy is not copyrighted by
others or directly derived from software copyrighted by others, is
copyrighted by Brown University, 1989, whether the individual pieces
are labeled so or not.	See bwe/include/copyright.h for the details
regarding this copyright.  The same holds for garden, tango, and those
parts of field that are not directly derived from UNIX tools.

The software located in gnumake is copyrighted by the Free Software
Foundation.






Bug Reports:
--- -------

Your assistance in making the installation process less painful is welcome.
Please report any and all problems to bwe@cs.brown.edu (or if that fails
to spr@cs.brown.edu or 401-863-7641).  We also welcome reports of bugs,
bug fixes, questions, suggestions, etc. related to any of the distributed
software.  Email to the above address is probably best, but any form will
suffice.  We are also in the process of setting up an anonymous ftp site
at brown that will allow us to distribute the latest versions and to post
bug reports and fixes.

The current status of bug reports, bugs fixed, enhancements and changes is
contained in the file $PRO/bwe/data/bug.status.



Steve Reiss
Brown University




