 -*- Mode: Text;  -*-
 File: PORTING
 Author: Heinz Schmidt (hws@csis.dit.csiro.AU)
 Copyright (C) CSIRO Division of Information Technology, 1992
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

The current installation should run on the following platforms:

	* Sun4 SunOS Release 4.1.1 (and a few earlier versions)
	* HP9000s300, HP-UX 7.05, HP-UX 8.00 (at least with developer)
	* Decstation 5000/300 ULTRIX V4.2
	* MIPS RC6280/RC3230 
	* Sony NEWS 3000
	* Sequent Symmetry, DYNIX(R) V3.0
        * SCO, UNIX SYSV R3.2
	* NeXT, OS Release 2.1

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 here
and so you have to take the above ports claim AS IS and WITHOUT ANY
IMPLIED WARRANTY. People sent patches to sather-admin and we
(sather-admin) have integrated them to the best of our knowledge.  The
current setup is very much due to an international effort. Thanks to
many colleagues around the world who contributed to this release
(whether knowingly or not) by sending their context diffs and port
reports, by interacting with us or by testing this release on alien
platforms:

  Michael Arnoldus, Gerd Aschemann, Andrew Duckworth, Hiroshi Harada, 
  Nobuyuki Hikichi, Patrick Moran, Jean-Jacques Moreau, Kevin Trojanowski

It is quite possible that some of the merged changes do not solve the
problems on your platform. Complain about it!  We heard about ports to
the following systems but we do not know about the state.

        * Vax ULTRIX V4.0
        * SGI mips

Before starting a major effort, you may also contact
	<sather-admin@icsi.berkeley.edu> 
to find out whether there are ports to other platforms. 

The following sections explain machine dependencies of the system and
how we have set up the structure to work with the currently supported
architectures. You will also find instructions for where to change
things if you need to change them.

IF YOU NEED TO CHANGE A FILE TO MAKE IT WORK ON YOUR PLATFORM, PLEASE
CARE TO SEND A SHORT DIFF TO <sather-admin@ICSI.Berkeley.EDU>. You may
perhaps save many people a little effort (= avoid a lot of effort?).

In order to simplify installing and porting the system across a number
of platforms we must make minimum assumptions about the availability
of basic features and also sometimes conditionalize the code and
installation procedure.  For instance we used "include" in make files
in an intermediate version of the system. But "make" does not support
it on all platforms and users may choose different make facilities,
such as the Berkeley pmake, which does not support "include" either.
For this purpose we concatenate the right machine dependent files in a
first installation step called "make config". Many conditionalizations
are already expressed in our make files. Some are expressed by the
user such as the pathname of the Sather directory tree and the
architecture of the current installation. The resulting make files are
tuned for the current architecture and used to do the installation
proper.  This first step also creates a number of architecture
dependent directories to hold architecture specific executables and
data needed by the user running Sather on the given architecture. In
contrast to intermediate executables and other generated data, these
directories will survive the "make clean" step when Sather is compiled
and installed for yet another architecture.


ARCH -- Selecting an Architecture
=================================

A machine type can be characterized by an architecture, assembler
syntax and sometime we need to know what OS is run.  We assume that
the necessary distinction can be made in terms of a single macro ARCH
whose value is used to tap the right Sather directories, select the
right system functions and find the system libraries.

Currently directory switches include

	bin.$ARCH and 
	sys/C/pre.$ARCH

Moreover the sather compiler needs to know about some of the
dependencies too since it generates a make file too to compile the C
files it generates.  We want that a naive call to the compiler works
too, such as "cs hello". While users can exploit (c_flags) options in
the .sather file to pass architecture specific information into make
files generated by the Sather compiler, the make files used in the
system installation use command line options to the Sather compiler to
avoid the need to conditionalize system .sather files for different
architectures like the compiler/.sather.  The only conditionalization
is in terms of pathnames. The compiler interprets all environment
variables that appear in a .sather file, including the file
sys/sys_dot_sather which defines compilation defaults for all
compilations. Currently this file only includes the variables
$SATHER_HOME and $ARCH.

In a similar way we place links in bin.$ARCH to link system files
like libm.a to allow all architectures to share one sys_dot_sather and
still obtain architecture specific versions like in

  (c_files) $SATHER_HOME/bin.$ARCH/libm.a

(We have avoided sys_dot_sather.$ARCH differentiations here to keep
the dependencies as simple as possible. Should bin.$ARCH grow too
large in the future we can easily split it into bin.$ARCH and
lib.$ARCH using the same scheme.)


Mkf.mach.cpp et al -- Machine Dependent Settings
================================================

All machine dependend make conditionalization are gathered in a single
file called Mkf.mach.cpp.  This file is pushed through the C
preprocessor in the "make config" installation step. Beside the
settings of CFLAGS and related options, you may want to check whether
the Unix platform for your system has all the default commands used in
"make" plans in the standard system directories.  You will find some
conditionalizations using #ifdef that choose different places for
particular architectures.

All site specific settings such as the make pathnames are in the file
Mkf.site. The file Mkf.gen contains the make plans and is assumed not
to change often.

These different Mkf files will be used in the "make config" step to
create several Makefile's (cf. the Mkf.gen config plan) without
requiring "make" to support "include".


#ifdef -- Machine Dependent Files
=================================

Several runtime and basic support C sources are conditionalized.

        compiler/timer.c
	lib/base/C/*_.c
	  lib/base/C/time_.c (particularly)
	sys/C/*_.c
          sys/C/envivars_.c (particularly)
	  sys/C/macros_.c
	sys/C/all_.h

Moreover all the GC and DBG support is conditionalized, for these
see the section below.

In general you have to watch out for a few files in sys/C and
lib/base/C directories should something go wrong in the installation
on a new platform. lib/base/C contains the basic system dependent C
code that Sather base classes may refer to. sys/C contains things like
the runtime system and files needed in Sather code in general.


Sather compiler
===============

The compiler itself does use only a few of the lib/base C files.
Cf. compiler/.sather for more details.

The compiler has a few files that are machine dependent, although
Sather does not support compile time conditionalization for now.
Most importantly these are:

	compiler/install.sa
	compiler/common_data.sa

Normally you should not touch install.sa. This file is edited in a
make step automatically. Relevant site and target system defaults are
burned into it before the boot compiler (C) compiles this file.  Make
file settings will be passed on into the Sather code.  Indeed, the
boot compiler only compiles an architecture specific version of the
file called in-$ARCH.sa. You can create this file using "make
arch-install" in the compiler directory once you have setup the system
using "make config". How does the boot compiler (distributed C code)
know the options? The compiler relies on as few options as possible.
These are passed by environment variables. Even if you have not set
them, make steps will export make settings to environment variables
before invoking the boot compiler.

common_data.sa gave rise to several gray hairs so far. More
specifically, the compiler passes text commands to an inferior shell
using the UNIX::system(s: STR) function. We have reduced this to a
bare minimum, but of course this is thin ice. If you see *** shell
command .... not executed *** messages, you have to watch out for the
procedure copy_user_cfile in common_data.sa. Even if the commands are
acceptable to the target system, the shell execution may fail.  You
will find an explanation of the error code, that comes in the message,
in the include file <errno.h> of your system.  One incompatibility we
ran into was missing support for the "cp -p" option. Your system may
not support "-p" but may not be in the current list of targets that
use "-p" instead. Add the value of your ARCH setting in
copy_user_cfile. Make sure that the boot compiler file glob<funny
number>.c also runs into the proper part of the if, so that you get
past booting the compiler and can create a new boot compiler (cf. the
file DISTRIBUTE). All this assumes that "cp" on targets without
support of "-p" works for archives, too, without requiring an extra
ranlib step.  Otherwise ... more work and you are on your own. (This
could be much cleaner when written using exception handling and
conditional compilation!)

Beside such a temporary hack of boot compiler C sources, you should
not change boot compiler C files. Some of the early port reports
that we received contained hacks of the boot compiler that of course
will get lost with the next distribution when a new boot compiler C
directory is created from the current compiler sather sources!


sys/C/GC -- The Garbage Collector
=================================

The current version of the GC is V1.9. It is a public domain GC and
runs on several architectures including little and bigendian mipses.
Beside lots of #ifdef conditionalizations, for some architectures
there is one assembler patch that may be relevant. You will find a
description in the GC documentation should this be relevant for your
architecture. Should the GC not run on your machine, we recommend to
skip its installation and postpone GC extensions to later. This can be
done in the Mkf.mach.cpp file, by setting SKIPGC=YES.
The current setup is such that the GC archive gc_.a will still be
created since it is called upon by default. However programs that 
require it resolving ALL GC references will not be compiled and
linker errors will thus be avoided.

Once your system works without GC, it is a small step to change GC to
work on your platform. It is unlikely but you may have to edit Mkf.cpp
to include the right flags for your system.  The main extensions will
be in gc.h and the few sys/C/GC/*.c files at places indicated by
comments like
        >>> fix it here <<< 
 Read the documentation to find out about the function of each of
these files. Note that on some systems you may need to write about ten
lines of assembler code that copy the contents of data registers
(possibly references to objects) to be traced by the GC when it starts
chasing objects.


debugger/C -- The Sather Debugger
=================================

The current distribution contains the Sather debugger SDB for Sun
sparc processors only. This is not a fundamental problem but a matter
of not having found time to include other versions. SDB builds on GNU
GDB. The debugger/C directory contains a copy of the relevant GDB
files configured for sparc processors. 

If you are familiar with the GDB installation you may go ahead and
install your version.  Do not forget to change Mkf.mach.cpp to NOT SKIP
the sdb installation on your architecture, once you have added the
right GDB files. Cf. the macro SKIPSDB there.

Here is how you might proceed. Our plan was to create a subdirectory
gdb.$ARCH that contains only the $ARCH dependent files of gdb. I
believe these are 4 or 5 files. And they should be linked to the
debugger/C directory. The debugger/C make file can be changed to take
care of linking the respective debugger/C files to the right gdb.$ARCH
files. Then "make" taps the right directory for each architecture.
You will perhaps find a better scheme that could serve several
architectures in one directory tree.


Pathname Problems?
==================

All pathname canonicalization of the Sather compiler goes through one
function in the class UNIX_PATH now (lib/base/pathname.sa) now. This
substitutes an earlier C file called tilde_expand that created several
problems.

pathname.sa allows users to have arbitrary environment variables in
.sather files. Note that this includes canonicalization of any tokens
in .sather files since the compiler passes them all through this
function.

BEWARE OF RANDOM USE OF VARIABLES IN .sather, YOU MAY WANT TO
DISTRIBUTE SOURCES AT SOME POINT IN TIME!

However variables used in moderation can help conditionalize your
compilations appropriately.


Untested Archtitecture Dependencies
===================================

We have integrated several changes that were reported on the list to
be necessary to make Sather run on a particular architecture. As
mentioned above, we do not have all machines around for testing and
therefore it is quite probable that you will find some fixes
introduced for your sort of machine but still other parts missing.  If
you have to fix Sather, once again, care to send fixes to
<sather-admin@icsi.berkeley.edu> and also tells us whether our "dry"
ports work if you run the system without changes on a machine not
mentioned in the list above. Of course we like to extend the list.

If you are porting to a new target architecture / Unix system and add
a dependency on a new flag of architecture or Unix system, please
update the Mkf.mach.cpp comments that list all the flags used so far.
This may help others in detecting problems with #idefs that catch on
their machines but are not meant to. You may use a unique flag
for your kind of machine and introduce it in the make config step,
cf. the comments in the file doc/INSTALL.


	Happy Sather hacking!
