File: sather/doc/STARTING
Copyright (C) International Computer Science Institute, 1991
SEE COPYRIGHT NOTE AT END OF FILE.


Welcome to Sather! This document is a short guide to setting up your
Sather environment and using the Sather tools. The primary components
you will want to know about are the Sather compiler, the Sather
debugger, the GNU Emacs Sather programming environment, and the Sather
library classes. We will assume that the Sather system has already
been installed on your machine (see the document "sather/doc/INSTALL"
for the description of this process). We will also assume that you are
using the GNU emacs editing environment.  While it is certainly
possible to use Sather without using Emacs, many of the environment
tools are built on it and your programming facilities will be greatly
enhanced by using it. GNU emacs is available for free from the Free
Software Foundation and may be ftp'ed from "prep.ai.mit.edu".


Sather Home Directory
=====================

The Sather directories will have been installed in a location referred
to as "SATHER_HOME" in the installation procedure. A typical location
is "/usr/local/src/sather". The sather system (compiler and other
tools) refer to this directory by means of the SATHER_HOME environment
variable and the binaries of system (compiler and other tools) are
found in the subdirectory $SATHER_HOME/bin.$ARCH where the environment
variable ARCH refers to the architecture on which you are running
Sather.  If you are uncertain about what architecture you are using,
typically you can run the shell arch (in /bin, /usr/bin, or
/usr/local/bin) to find out the current architecture.

Adding the lines or more appropriate versions of these lines

setenv SATHER_HOME /usr/local/sather
setenv ARCH sun4
setenv SATHER_MAKE make
set path = ($path $SATHER_HOME/bin.$ARCH)

to either your "~/.cshrc" or "~/.login" file you define this variable
in your environment and instruct the system to look in the Sather
"bin.$ARCH" directory. It holds the compiler and the debugger.  The
compiler is named "cs" which is short for "compile Sather" and the
debugger is named "sdb" for "Sather debugger".

The SATHER_HOME variable is important for the compiler to find basic
classes and other general system information.


Emacs Environment
=================

If Emacs is your editor of choice, you may add a line like:

(load "$SATHER_HOME/etc/.emacs") 

to your "~/.emacs" file. Or you may copy and modify the
$SATHER_HOME/etc/.emacs to your likings.  The file contains several
customizations of the Emacs environment including autoload
instructions for a Sather mode. 


Sample Program: Hello World
===========================

You are now ready to compile a Sather program. The simplest Sather
program is "$SATHER_HOME/etc/hello.sa" which simply prints out "Hello
world.". The file essentially just contains:

class HELLO is
   -- Simplest program, just prints "Hello world." on stdout.
   main is
      -- Print "Hello world" on stdout.
      OUT::s("Hello world").nl
   end; -- main
end; -- class HELLO

To compile Sather programs you use a ".sather" file which specifies
the source files and which compiler options to use. A suitable
".sather" file for this program is "$SATHER_HOME/etc/hello.sather".
It essentially contains:

(source_files) $SATHER_HOME/etc/hello.sa


Compiling and running "Hello World" from a shell
================================================

To do the compile, move to the directory you want to compile in. Copy
"$SATHER_HOME/etc/hello.sather" into a file named ".sather" in this
directory. Type "cs hello". The compiler will output something like:


Created directory --/da/om/sather/test/hello_test/hello.cs

Current version is dated Fri May 31 04:09:43 1991

Doing make....:"(cd /da/om/sather/test/hello_test/hello.cs/;make -f makeHELLO)"
cc -DGC_  -c MAIN_.c
cc -DGC_  -target sun4 -c  hello_22.c
cc -DGC_ *.o *.a -o hello 


You will see that a directory named "hello.cs" has been created which
contains the C and object files generated by the Sather compiler as
well as the program called "hello". If you type "hello" the response
should be to print out "Hello world.".


Compiling "Hello World" from within Emacs
=========================================

To do the same compile within Emacs, you would first edit the
".sather" file. Type "M-x compile" and it will respond with "Compile
command: make -k". Edit this to be "cs hello" instead of "make -k".
Hit return and it will ask whether you want to save each unsaved
buffer. It will then open up a buffer called "*compilation*" where the
compile will proceed. If you type "M-x shell" in the compile window,
you can try out the program from within Emacs. For programs which
compile correctly, there is not a great advantage to working this way.
The benefit arises when there are bugs. In this case the compiler will
generate a series of error messages. When they begin arriving you may
type "C-x `". This causes Emacs to parse the first error message and
bring up a buffer with the source file with the cursor at the line of
the error. You can use the Emacs Sather source browsing tools to find
more about the current class and routines. You fix the error and type
"C-x `" again until all errors have been repaired. Then "M-x
compile" will start a new compile (and the default compile command
will be the same as the last one). This process is particularly
convenient if you split your main Emacs window into several
subwindows.


Other useful Emacs functions
============================

Another useful function of the Emacs environment is that it makes
searching and editing Sather source files easier. First edit the
".sather" file you are working on. Type "M-x sather-tags" in this
buffer.  This will generate an Emacs "tags" table for the source files
in your program. The two files generated are named "TAGS" and
"TAGS.compl".  They record the names of the files and the routines and
classes defined in them. You can type "M-." to cycle through all
routines with a given name. For example, if you generate sather-tags
for the "hello.sa" example it will include information about the
source file "hello.sa" and the library source files which are
automatically included along with it. Type "M-. main" and it will put
you immediately at the routine "main". Type "M-.  create" and it will
put you at the "create" routine in the class "STR". Type "M-," and it
will cycle through all the classes which have a routine named "create"
in your program. If you put the cursor on a routine name such as
"create" and type "M-x sather-documentation" it will make a buffer
with a documentation line for each routine named "create". In this
case the generated buffer might look like:


STR::create: SELF_TYPE is                                     [public]
   An empty string.

STR_CURSOR::create(st: STR): SELF_TYPE is                     [public]
   Make a scanner for the string `st'.

FILE::create:SELF_TYPE is                                     [public]
   A new unitialized file object.


If you type "M-x sather-documentation" when the cursor is over a class
name, it will generate documentation for a whole class. For example
"M-x sather-documentation <ret> HELLO" generates:


HELLO is                                                       [class]

   Simplest program, just prints "Hello world." on stdout.


Public definitions of class HELLO: 

main is
   Print "Hello world" on stdout.


Try typing "M-x sather-documentation <ret> STR" for documentation on
the more extensive string class. There are many more features of the
editing mode which may be found described in the documentation. (A
short form may be seen by typing "C-h m".)

Under X windows, the emacs environment supports both point-and-click
and multi-style editing.  With the point-and-click functions, one need
only point to a feature name with the mouse and the system will
immediately move to its definition or display its documentation.
Similarly one may point to an attribute name in SDB to show its value.
The multi-style support highlights keywords and comments in Sather
sources on the screen and in formal code documentation. It is only
available under Epoch.  Usually no extra setup is necessary once
.emacs is loaded.  However, the doc/sa-emacs.txt also contains hints
on how to setup your X resource and window manager definitions to take
full advantage of this interface. More details of the sather Emacs
support can be found in "$SATHER_HOME/doc/sa-emacs.txt".


Prefabricated Demo Programs
===========================

To try out more complex programs, look in the directory
"$SATHER_HOME/etc/test". This contains suitable ".sather" files for
compiling programs which run all the tests in different portions of
the Sather library. For example "data_structure_classes_test.sather"
will exercise each of the data structure classes. Simply copy this
file into one named ".sather" in the directory where you want to do
the compile and type "cs data_structure_classes_test". If you are
using the sunview window system, then "sunwind_test.sather" will
demonstrate a simple program using graphical interfaces.


Using the Sather Debugger SDB
=============================

To use the debugger, you must compile your program with the "-sdb"
flag. Compile with the commmand: "cs -sdb hello". Once
compiled, type "M-x sdb" and at the query give it the name of the
program "hello". Sdb will start up in a buffer called "*sdb-hello*"
with information like:


Current directory is /n/icsib29/da/om/sather/test/hello_test/
SDB (bilmes), Copyright (C) 1991 International Computer Science Institute.
            Copyright (C) 1989 Free Software Foundation, Inc.
There is ABSOLUTELY NO WARRANTY for SDB; type "info warranty" for details.
SDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "info copying" to see the conditions.
Type "help" for a list of commands.
Reading symbol data from /n/icsib29/da/om/sather/test/hello_test/hello...done.
Reading Sather specific symbol information...
done
Reading Sather line number information
(sdb) 


Switch to the buffer with the "hello.sa" source code in it and move to
the first line of "main". Type "C-x <space>" to set a breakpoint. In the
sdb buffer you should see something like

(sdb) Breakpoint 1 at 0x5448:  (hello.sa line 31) (C file hello_22.c line 23).

Move to the SDB buffer and type "run". You should see:


run
Starting program: /n/icsib29/da/om/sather/test/hello_test/hello 

Bpt 1, HELLO<0x0>::main  (hello.sa line 31)
(sdb) 


And a second window will show the "hello.sa" source file with an arrow
pointing at the current line. You may single step through the program
by typing "s". A wide variety of other debugging operations (such as
examining objects, changing variables, and calling functions) may be
performed. Type "help" to the "sdb" prompt to see the options. For more
information on the debugger, see the file doc/sdb_info.txt.  

This has introduced the basics of the Sather environment. The key to
Sather programming is the use of powerful reusable library classes.
These classes are in the directory "$SATHER_HOME/lib" and should be self
documenting. Most classes have a corresponding "_TEST" class defined
in the same file. It is often convenient to study the test class to
see an example use of the class itself.





Good luck in Sather programming!


-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
This document is part of the Sather distribution.
Author: Stephen M. Omohundro
	Heinz Schmidt
Copyright (C) International Computer Science Institute, 1991
Changes: Heinz Schmidt (hws@csis.dit.csiro.AU)
Copyright (C) CSIRO Division of Information Technology, 1992

COPYRIGHT NOTICE: This file is provided "AS IS" WITHOUT ANY WARRANTY
and is subject to the terms of the SATHER LIBRARY GENERAL PUBLIC
LICENSE contained in the file: "sather/doc/license.txt" of the Sather
distribution. The license is also available from ICSI, 1947 Center
St., Suite 600, Berkeley CA 94704, USA.

* HISTORY:
* Last edited: Feb 20 21:56 1992 (hws)
* Created: Mon Jun  3 12:51:56 1991 (om)
