 -*- Mode: Text;  -*-
 File: doc/INSTALL
 Author: Heinz Schmidt (hws@csis.dit.csiro.AU)
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
 
This file describes how to install version 0.2 of the Sather
distribution.

If you have problems with this installation, send email to:

	<sather-admin@icsi.berkeley.edu>

The system should build straight from the distribution on the
following platforms:

	* Sun4 SunOS Release 4.1.1 (and a few earlier versions)
	* HP9000s300, HP-UX 7.05, HP-UX 8.0
	* Decstation 5000/300 ULTRIX V4.2
	* MIPS RC6280/RC3230 
	* Sony NEWS 3000
	* Sequent Symmetry, DYNIX(R) V3.0
        * SCO, UNIX SYSV R3.2 (see end of file)
	* NeXT, OS Release 2.1 (without GC for now)

The current system can be installed using gcc, we did this in the
Sequent and the NeXT port.  We do not have all of these machines and
so the above claim is WITHOUT WARRANTY.  Users have sent patches to
sather-admin and we have integrated them to the best of our knowledge.

If you want to run Sather on other platforms, read the file
"doc/PORTING" before continuing with the steps described in
"Installation" below.  The doc/PORTING file contains information about
what we know of ongoing ports at the current point in time and
instructions for how to port Sather to a new platform.

If you want to support sather on different architectures at your site
from the same Sather directory tree, see the paragraph "Shared
Installations" below.


Installation
============

First, edit the top level make file 'Mkf.site' and change the three make 
variables "TOPDIR", "SATHER_HOME", and "ARCH", perhaps also the
"SATHER_MAKE" as follows:

  "TOPDIR" should contain the path of the directory containing the top
  level Makefile. This file here is $TOPDIR/doc/INSTALL. 

  "SATHER_HOME" should point to the final location you wish to place the
  sather distribution. If you wish SATHER_HOME and TOPDIR may be the same. 
  In that case, Sather will compile directly into its ultimate location 
  and the "make install" step below will take less time.

  "ARCH" should contain the name of the architecture. Typically you can
  run the shell arch (in /bin, /usr/bin, or /usr/local/bin) to
  find out the name of the current architecture if you are not certain.
  This variable is used to choose an architecture dependent directory
  for executables and for conditional compilations.

  "SATHER_MAKE" should contain the name of the make utility of your choice.
  This will be used only for compiling Sather generated classes. The default
  setting is make. Note that this setting does not affect others uses
  of make in the installation procedure. 

Although normally you do not want to change the file Mkf.mach.cpp, you
may want to take a look and check the setting of CC, CFLAGS etc., for
your type of machine. Note the C compiler chosen, as users may need
this compiler to be able to link with binaries precompiled during the
installation.
  
After editing the make variables you need to generate machine
dependent make files implicitly using the C prepocessor. Normally you
just follow with  "make config" BUT FIRST read on. Your system
may not properly support the C preprocessor or you may need to
pass on a flag so the installation can distinguish what kind
of Unix it is happening on.
On one NeXT: 
   we found it necessary to use
           make CPP="(/lib/cpp | sed s,' #','#',g ) <" config
   since gcc was installed without the -E option and then
   cpp would introduce blanks preceding the make comment sign "#"
   subsequently confusing make. 
On HPUX:
   you need to do
          make CPP="cc -E -Dhpux7" config
   or     make CPP="cc -E -Dhpux8" config
   to pass the non-standard flag to the preprocessor. This flag
   is used in some make files and C files in this distribution to 
   distinguish HP-UX 7.0 from HP-UX 8.0. We did not find a good
   distinction in hpux but there were differences in basic support.
On SCO Unix:
   you need to do
          make CPP="cc -E -DSCO" config
   to pass the non-standard flag to the preprocessor. This flag
   is used in some make files and C files in this distribution.
On OTHER Unixes:
   you type    "make config".

This config step will create various Makefile's in the Sather
directory tree. Then you type 	"make", or "pmake" if you have it
around, (and then go have a cup of coffee or tea). Using make, the
build takes about 30 minutes on a SPARCStation 2. At ICSI, this takes
about 10 minutes using pmake which can be ftp'd from
ginger.berkeley.edu.

Once "make" is done, type "make install" which will copy the relevant
files to the directory given by SATHER_HOME. If you wish, you may do
a "make clean" in TOPDIR. Don't do a "make clean" in SATHER_HOME  8-O
however, since that will delete some needed precompiled Sather classes
(thus, don't do "make clean" if SATHER_HOME = TOPDIR).

Now you are ready to try compiling some example Sather programs.
See the files "doc/STARTING", "doc/cs_options.txt",
"doc/sdb_info.txt", and "doc/sa-emacs.txt" for more information.


If something goes wrong :-( 
===========================

NOTE1: You should ignore any C compiler warning messages about
unreachable code, i.e., "warning: statement not reached". You can make
the compiler run quietly by using cc with -w option.  (We suggest
setting CFLAGS appropriately in Mkf.mach.cpp before doing "make
config").  Perhaps, however, you want to see what is going on.  Also
make steps may tell you that directories exist or steps need not be
done, if you run make a second time without cleaning, see below.

NOTE2: Some people found problems with their make not exporting
environment variable settings to the environments of Sather compiler
runs. If you experience problems with this please drop us a note on
which system this happens and in which step. Just include the whole
make protocol if you're uncertain. You may perhaps overcome the
problem by appropropriate setenv's for SATHER_HOME, SATHER_MAKE, and
ARCH before typing "make" a second time, in this case. These are the
only variables currently used by the compiler.

NOTE3: Depending on the load of the installation machine you may
experience memory problems when Sather compiles the compiler. One way
this can show up is in not being able to copy files because the memory
is already exhausted. Beside finding or buying a larger machine ;-)
there are a number of ways to overcome this, you will know them, but
others may not: minimize the number of other processes running on the
machine, or, add more swap space, we use 64MB swap on our machines and
100MB swap on the development machine, ("pstat -s" tells you the
"available" swap figure, we had a situation where 30MB available
before running make was not enough but this may be due to GC settings.
We did not find time to tinker with this, if you do and push it down
to the bare minimum let us know, please  :-).)

NOT4: If the installation was interrupted by you or for any other
reason and a second attempt to build the system using make fails, you
can cleanup the Sather directory by typing "make clean".  This removes
most of the generated executables and also other intermediate
information and allows you to start all over again by typing "make".


Moving the Sather directory tree
================================

The sather tree is relocatable, i.e. it can be moved around in a file
system without requiring rebuilding. There are a few possible
overriding ways for users to refer to the Sather directory, in the
following order:

* SATHER_HOME environment variable (cf. STARTING)
* is overridden by the (sather_home) compiler directive in the .sather
  file (cf. manual.txt)
* is overridden by the -hom command line option to cs (cf. cs_options.txt)

Only if none of these directives is used will the Sather compiler try
to access the directory tree using the pathname that was used at the
time of installation as the value of SATHER_HOME.


Shared Installations
====================

Typically one assumes that the Sather system is build once for a
particular hardware platform for which a port exists. Major parts of
the system are written in Sather itself or in conditionalized C.
Different installations for different architectures can share the same
directory tree. I.e., Sather and C source directories may be common
while there are different bin directories bin.AA for each architecture
AA supported by the same directory tree.

Shared installations are created by running through the installation
procedure several time (serially!). Each time you change the "ARCH"
macro as described above, "make config" will use different directories
for binaries and of course some of the machine dependent make settings
will be different. "make clean" only removes the intermediate compiles
for the current architecture "ARCH".

Once again, you cannot run multiple installations concurrently from
different target hosts accessing the same directory tree
simultaneously.  The typical order of steps is reflected by the
following regular expression:
	
  <edit make files>; make config; make [; make install];
   (<edit make files>; make config; make clean; make [; make install]; )*
	                            !!!!!!!!!!

Don't forget the "make clean" step (!!!!!!!!!!). Note that in this
form of sharing different debuggable versions of the compiler may
interfere because in the current setup the compiler subdirectory will
be used to store intermediate executables including debugger
information. These shared directories contain the information of the
last installation only.  Usually this is ok. In a clean version (make
clean) temporary executables and other intermediate files are removed
anyway. These files may sometimes be valuable to a Sather developer,
though. For Sather-compiler development projects we therefore
recommend to keep istallation trees separate for different
architectures to avoid confusion.

Having read all this, you are now ready to run your next installation
towards a different architecture. Edit the make files as described in
the first installation. The SATHER_HOME and TOPDIR will typically be
the same, if your file system is mounted appropriately.  If you have
chosen a different mounting scheme in your site, that is also fine.
You can change the two variables accordingly.  Make sure that you set
the ARCH variable properly too.

Now login to the host for whose architecture you want to support
Sather via the network file system. (This beta version does not
separate host and target architecture.) "cd" to the sather directory
and run "make config", "make clean" and the "make".

As indicated by the regular expression above, you may do several
installations for several architectures. Perhaps you may do them
several times for the same architecture if you just want to create
compilers with different compile options, say. However, in this case
you may want to ignore irrelevant make warnings like

	mkdir: /proj/hop/topdir/bin.sun4: File exists
        make: *** [install] Error 1 (ignored)

You can avoid such warnings by having make run quietly. Perhaps
however you want to know what's going on.


			    SCO Unix fixes
			    ==============

A small number of fixes for SCO Unix have been made temporarily and
require a better solution. We hope that the next release will have
less BSD dependencies or more Sys V BSD emulations will be available
for the few things we need.

1. For SCO config step use 
	make CPP="cc -E -DSCO" config
   See also the comments for the config step above.

2. Watch out for the BOOTFLAGS and CSFLAGS in the file Mkf.mach.cpp.
   We have temporarily included -lsocket to have some of the functions
   around that are not normally part of SYS V but are available
   in the TCP/IP software. Do you have it?

3. Remaking the compiler from the Sather sources is a second step once
the boot compiler is compiled. This step changes some defaults in the
compiler. But otherwise the compilers are the same. (However this 2nd
step might tell you that the compiler runs or where things still fail
if you are porting.)  

The virtual memory capacity of your system may be too low to allow
this step. Or you may simply want to save this step.  If you need/want
to you can avoid this step by commenting the following lines in the
top level Mkf.gen.

	@echo
#	(cd ./compiler ; ${MAKE} SATHER_HOME=${TOPDIR} ; )
#	${CP} ./compiler/cs ./bin.${ARCH}/cs
	if [ ${SKIPSDB} = NO ] ; then \

But note that the compiler defaults are not properly set now. This
does not matter as long as users use the relevant compiler options
and/or environment variables to set SATHER_HOME, ARCH, and
SATHER_MAKE. Think twice about commenting these lines out before you
decide to! Sather users at your site may get confused!


Enjoy Sather! :-)


PS: Sather is meant to combine the simplicity, ease and efficiency
needed for serious OO programming. It takes time and you to achieve
this goal. If you are not satisfied don't sit and blame yourself -
complain, discuss and improve Sather!  You may use the mailing list
sather@icsi.berkeley.edu to do so. However, send requests to
sather-admin@icsi.berkelely.edu.

-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Smiley legend since we can't hear voice inflection over Unix...
:-) Happy  ;-) Winky 8-) Big eyes :-( Frowning 8-O Omigod rm -r *
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
