# Installation Notes

## Preliminaries

Sather uses Boehm Garbage Collector (GC) which is distributed separately. You may get it either at the site where you found Sather or at the original site:

http:/reality.sgi.com/boehm/gc.html

Just compile it and install it before compiling Sather. This package assumes to find a library "libgc" (compiler switch -lgc) and a header file <gc/gc.h> in the normal include path.

Everything below this point may be outdated. Especially anything about the Garbage Collector should be reworked, since the GC is no longer part of the distribution but must be compiled and installed separately.

## The default installation

Usually you just have to set the environment variabe "`SATHER_HOME`" to the base directory of the Sather package and then run "`make`". For the optional part you need to have Tk/Tcl and some kind of socket support installed. File System/Common/CONFIG.proto has default settings for many variables used during the installation (the name of a make utility, C compiler, etc). These may need to be modified if, for instance, you would like to use a parallel make utility or a proprietary C compiler.

## Things you need to install the compiler

- You must have an ANSI C compiler. Gcc works well.

- Your linker must be able to distinguish identifiers up to 32 characters.

- You must be able to compile the Boehm garbage collector.

- If you choose to not install the precompiled compiler as the Sather compiler, you'll need at least 16M physical memory.

  A nice thing about the new installation procedure is that it compiles and installs the supplied bootstrap compiler generated at ICSI (which is a fast one) as your Sather compiler, without needing too much memory.

  The exact requirements to compile an own Sather compiler depend on the tools and installation you choose. If you just do not want to use the supplied boot compiler as your Sather compiler, you will need about 45MB virtual memory for a start. Moreover, if you want to have the fastest compiler possible and do not want to use the supplied boot compiler, different optimizations and static analyses will require about 60MB.

  If you are running out of memory you can separate the Sather->C compilation from the C->object Code stage, you might try something like "`sacomp .... -only_C && make -C foo.code`" to shut down the Sather compiler before C compilation starts.

## More detailed installation instructions

These are the recommended step to install the Sather compilers. Your system may have particular requirements; if I know these, they are listed later in this file.

- Look over the variables set in ../System/Common/CONFIG.proto Fill in a parallel make utility in `MAKE_COMMAND` if you have one. If you are lucky you might not have to change anything.

- The installation directory is determined from the environment variable SATHER_HOME, which MUST BE SET BEFORE RUNNING MAKE. Make sure it doesn't have trailing space or a slash "/". Use the full path name, not just a dot ".". For example: `"/usr/local/lib/sather"`

  Actually, SATHER_HOME does default to /usr/local/lib/sather, now - at least partially. Problem is, that when packaging for Debian, environment variables can't be used. A clean solution is being worked on.

- If you intend to use a precompiled binary from someone on the net, go to the top directory and type `make system'. Then copy the binary into the file `Bin/sacomp', and "touch Bin/sacomp" to make the timestamp up to date (so the make utility won't try to recreate it). You are done.

  Otherwise, go to the top directory and type `make'. That should do the following things:

  - Make the Boehm garbage collector (GC)
  - Make the system specific compiler files (CONFIG)
    CONFIG is generated from System/Common/CONFIG.proto and CONFIG files in various platform directories System/Platforms/* that may overwrite and extend any definitions in CONFIG.proto. The details are in Doc/runtime_spec.
  - Generate serial libraries Library from parallel pLibrary
    (see Doc/PP.description on how and why this happens)
  - Execute make for installation platforms
    (see Doc/runtime_spec for more information on platforms. You can edit the top level Makefile to select platforms for your system. The default platform is "unix" but could be also changed by editing the Makefile.)
  - Compile the bootstrap C for the compiler (Boot/sacomp)
  - Install the compiled boot as the installation compiler in Bin/sacomp
  - Compile and execute some test classes (in the Test directory).

  If you are porting the compiler to a new platform or simply feeling adventurous, you may want to compile Sather compiler sources using the boot compiler and install the resulting compiler as your Sather compiler. See memory requirements above. You need to type 'make full-install' which repeats the steps above up to compiling the boot compiler. Then it does the following:

  - Use the bootstrap compiler to compile the Sather compiler
  - Install the resulting compiler in Bin/sacomp
  - Compile and execute more extensive tests (including several recursive compilations).

  A common problem is for the tests of the IEEE extreme cases (such as 0.0/0.0) to not come out right. If these fail on your system, it's not a big deal and won't keep you from using the compiler.

  If you want to do a stress test compiling the new compiler with itself, do a ``make testfull`'.

- If all went well, you may want to install the executable(s) (Bin/*) and documentation (Doc/man/man1/sacomp.1) someplace appropriate. You can move the installation around; the location is obtained from `SATHER_HOME` and is not "burned in".

The default make rule then goes on to make the optional packages, the Browser, Gui and Graphical debugging.

##

Optional: Browser, Gui and Graphical Debugging

After completing the standard "make", the Makefile will go on to try and install some optional library, browsing and debugging aids (the `-debug_graphical` compiler option). The corresponding rule in the Makefile is "`optional`". For all of these you should have Tcl8.0 and Tk8.0 installed, and sockets available. Here are some useful sites for Tcl and Tk:

- Information: http://www.sunlabs.com/research/tcl/install.html
- FTP: ftp://ftp.sunlabs.com/pub/tcl/

- Take a look at the path variables specified in `System/Platforms/X/Platform.module` and `System/Platforms/tcltk/Platform.module` and change them to find your own include files and libraries.
- make Gui The optional rule will try to compile the server for the dual process Gui. This should create an executable called `System/Platforms/dualgui/dual_gui_server`.
  Installing the dual process gui requires sockets, which are configured for your platform in: `Systems/Platform/<your platform>/Platform.module`.
  Most unix platforms should work fine. You should be able to directly use the classes in `Library/System/Gui` by using the option (when compiling) of `-gui`. You can get at the dual gui (if it the server has been installed) by using the compiler option `-dualgui`. More details may be found in: Gui/index.html
- make browser. The make rule called "optional" tries to generate the browser `Bin/sabrowse`. Compile time errors can be related to
  - Bad installations of Tcl/Tk, or wrong versions
  - Take a look at the path variables specified in `System/Platforms/X/Platform.module` and `System/Platforms/tcltk/Platform.module` and change them to find your own include files and libraries.
  - Tcl related runtime errors when invoking the browser See `../Browser/README` and tcl_tk_notes. for more information.
  The browser should be used in the same manner as the compiler (see ../Browser/README).

#

Problems you might encounter

Sometimes there are simple namespace conflicts. These can be permanently eliminated by having me add the offending identifier to `System/FORBID`, and in the meantime add it yourself and do a textual search-and-replace in the boot code to change it to something else.

If you have to modify the garbage collector, please send the changes to the author, Hans Boehm (boehm@parc.xerox.com), so he can include them in his next release. If one wants to encapsulate existing c++ classes for use with Sather, one would wish to have access to the c++ extensions in the GC library. This can be accomplished by changing "make" to "make c++" in the rule for "System/GC/gc.a". This does not hinder using straight Sather or Sather with external C code while enabling the use of the garbage collector with GC compliant c++ classes.

Beware the jabberwock: if you didn't have CPP set properly on your first make, be sure to delete any bogus empty System/CONFIG file that got created by the redirect. Otherwise make may not know to generate the good versions.

Be sure to let us know what you had to add to get things running so we can include them in the next release. Whether it works or not, let us know by sending mail to "bug-sather@gnu.org". Good luck!

- Boris

# Known changes necessary to compile on ported systems

In this section, there was a whole bunch of information much of what seemed completely outdated and useless, so I decided to dump it completely and start out new. Most of this information will go into the Faq-O-Matic anyway where it can be kept up-to-date much more easily.

- Systems on which it runs without changes (there probably are many others):
  - SunOS 4.1.3, gcc 2.5.8, gcc 2.6.0 gcc 2.7.2
  - SunOS 5.4, gcc 2.5.8, gcc 2.6.0, gcc 2.7.2
  - SunOS 5.5, gcc 2.7.2
  - Ultrix 4.3
  - Linux 1.0.8, gcc 2.5.8
  - Linux 1.1.x, libc4.6.x, gcc 2.6.0
  - Linux 1.3.35, gcc 2.7.0, i486-*-linuxaout
  - Debian GNU/Linux 2.1 (i386)
  - HPUX 8.07, 9.05, using gcc 2.5.8
- FreeBSD 3.2:

  Yoshida Atsushi <yoshida@tutkie.tut.ac.jp>, Aug 26, 1999:

  Boot/sacomp did not work. The reason was gc. In the port of gc on FreeBSD, gc is to be compiled with the option "-DREDIRECT_MALLOC=GC_malloc". I made gc without this option, and compiled sacomp with it. This sacomp worked fine. So, FreeBSD users need to make gc without this option.

If you have ported it successfully to a system, send the changes to <bug-sather@gnu.org> so they can be incorporated either in the source directly, or where that is not possible, into this list, or let us know that it runs without changes.