NAME
cs - Sather compiler
SYNOPSIS
cs [ files and options ]
DESCRIPTION
cs is the Sather/pSather 1.1 compiler. A specification of
the Sather language and more information can be obtained by
anonymous ftp from "ftp.icsi.berkeley.edu:/pub/sather" or in the
WWW at "http://www.icsi.berkeley.edu/~sather". Postscript
should also be in the "Doc" directory of the distribution.
There is also a newsgroup "comp.lang.sather".
USAGE
The environment variable SATHER_HOME must be set to the ins-
tallation directory of the compiler at your site. Then a
file "foo.sa" with the FOO class containing main can be com-
piled with the command "cs foo.sa -main FOO". For example,
at ICSI users should set their environment variable
SATHER_HOME to "/usr/local/lang/sather" and add
"/usr/local/lang/sather/Bin" to their path.
To compile pre Sather 1.1 sources, please either use a com-
piler option -V1.0, or convert old sources to 1.1 syntax
using options -convert file_name or -convert_all. The second
solution is preferred.
FILES
File names must be in one of the following forms:
file.sa - A Sather source file.
file.module - A Sather commands file.
file.c - A C source file.
file.o - An object file.
file.a - An archive file.
If the environment variable SATHER_LIBRARY is not set, then
the standard libraries will be loaded from the installation
automatically. If SATHER_LIBRARY is set, it is interpreted
as additional command line arguments before other arguments
are processed. If you compile a pSather program, the com-
piler will first check PSATHER_LIBRARY, then SATHER_LIBRARY
and then use the standard pSather library.
GENERAL OPTIONS
-V1.0
Compile Sather 1.0 source files. Please, note that
options -convert file and -convert_all can be used for
automatic conversion of Sather 1.0 source files to
Sather 1.1 syntax.
-convert file
Converts a source file with a given name from Sather
1.0 to Sather 1.1 Syntax. The original file is renamed
to file.1.0 It is advantageous to use this option
together with -only_parse
It is safe to attempt more than one conversion of the
same file. Also, see convert_all and -V1.0
-convert_all
Converts all reachable Sather 1.0 source files to 1.1
syntax. Original files are renamed to file.sa.1.0 It
is safe to attempt conversion of already converted
files. It is advantageous to use this option together
with -only_parse. Also, see convert and -V1.0
-main class
Specifies the class whose main routine will become the
first executed function. If this option is not pro-
vided there must be a class MAIN containing a routine
main which will be used.
-o file
Produce the executable file. If this is not provided
the default file name is `a.out'.
-output_C
Do not delete the directory containing C files after
compilation. The directory is the executable name fol-
lowed by `.code'. Not deleting this directory allows
the compiler to re-use object files from previous com-
piles, which sometimes results in a dramatic speedup.
-pretty
Generate C files that are as readable as possible,
doing proper indentation and adding comments when pos-
sible.
-verbose
Give information about what the compiler is doing.
-prolix
Give mountains of information about what the compiler
is doing.
-only_parse
Stop compilation after all Sather files have been
parsed.
-has file class(es)
Inform the compiler what classes are in a file. Files
for which this is provided will only be parsed if there
is a reference to a listed class. This option is used
to avoid parsing library code which is not reached.
Classes with different numbers of parameters are not
distinguished.
-only_check
Perform typechecking but do not generate C for any
code.
-only_C
Stop the compile after the C code has been generated
and do not invoke the C compiler. Also generates C
files in the current directory as if "-output_C" had
been given.
-only_reachable
Inhibit type checking of unreachable code; by default
all code is checked.
-V,-version
Prints a compiler version, list of installed platforms,
default platform, and compiler home directory
CODE GENERATION OPTIONS
These options may affect compile time, execution time, and
executable size.
Checking options
There are a number of checks that may be enabled. Checks
have the useful property that if a program runs to comple-
tion with checks on, it will run to completion with them
off, given the same input and computational environment.
(This may not be true for nondeterministic code such as
pSather programs.) All checking options are of the form
-chk_chk and may be disabled by using an option of the form
-chk_no_chk. Most checking options accept a class list.
Giving the class name "all" (illegal as a class name because
it is lower case) is a shortcut for listing all classes.
-chk_when class(es)
It is not legal for a case or typecase statement to not
provide a suitable when or else clause for its argu-
ment. If when clause checks are enabled, this results
in a fatal error. When clause checks are usually inex-
pensive.
-chk_void class(es)
It is illegal access an attribute, access an array ele-
ment, or dispatch on the type of void. Void checks are
usually inexpensive.
-chk_arith class(es)
It is possible for certain routines in INT to cause
fatal errors. Examples are overflowing or division by
zero. Some arithmetic checks are inexpensive and some
may be quite expensive, depending on the processor and
compiler. Because arithmetic operations account for
the bulk of the processing time of many programs, by
default only those operations which are very inexpen-
sive have checking turned on (such as those that can be
performed without additional code in-line, often divi-
sion by zero.)
-chk_bounds class(es)
It is not legal to access AREF elements with indices
below zero or above asize -1. Out-of-bounds checks
ensure that attempting such an access results in a
fatal error.
-chk_pre class(es)
-chk_post class(es)
-chk_assert class(es)
-chk_invariant class(es)
pre, post, assert and invariant are Sather language
constructs which allow programmers to provide checks of
their own. These may be expensive, especially invari-
ants, which are checked after every routine call.
-chk_destroy
The routine SYS::destroy($OB) allows programmers to
assert that objects should no longer be accessed by the
program. With optimization on and destroy checking
off, this becomes a memory deallocation and potential
source of dangling pointer errors. With destroy check-
ing on, the compiler tests every object access to make
sure it is not to an object which has been destroyed.
Because of garbage collection, explicit calls to des-
troy are not necessary except in time critical applica-
tions. Because it is dangerous, destroy should only be
used by experts. "-chk_destroy" and "-chk_no_destroy"
do not accept a class list.
-chk_psather
Generate code to sanity check pSather code; for exam-
ple, it is illegal to unlock a lock more times than it
has been locked, or to unlock a lock which was not
locked by a syntactically enclosing lock statement.
This enables also deadlock detection.
-chk_return class(es)
It is a fatal error for the last statement executed by
a routine to be something other than a raise or return.
When return checks are on, a test occurs which enforces
this. Return checks are usually inexpensive.
By default only void, when clause, return, and bounds checks
are performed. It should not be possible to crash a Sather
program with the default checks enabled except by improper
external calls or destroys. It is also possible to turn on
or off all checking:
-chk_all class(es)
-chk Specify that all checks within the classes occur. " -
chk" is a shortcut for "-chk_all all" and is recom-
mended to assure the greatest level of safety.
-chk_no_all class(es)
-chk_no
Generated code will not perform any checks, except
those that will not result in less efficient code. "-
chk_no" is a shortcut for "-chk_no_all all". Use with
caution.
Optimization Options
-O Attempt optimizations; this may lengthen the compile
time in an attempt to improve code quality. By
default, only optimizations which can be done quickly
are performed. This option is turned on by -O_fast.
-O_verbose
Output optimization statistics
-O_fast
Turn on optimizations and turn off all checking. Same
as "-O -chk_no_all all". Use with caution.
-O_cse
Eliminate common subexpressions.
-O_hoist_const
Hoist loop constant expressions outside the loop. Loop
constants should be evaluated only once, outside the
loop. If this option is used, but -O_hoist_iter_init is
not, many initializations of once arguments are still
hoisted, although this option is less aggressive than
the one above.
-O_no_hoist_const
Turn off -O_hoist_const
-O_no_cse
Turn off -O_cse
-O_hoist_iter_init
Attempt to move the initializations of once arguments
of iters out of the loop. This makes the loop smaller
and removes an if statement in the loop.
-O_no_hoist_iter_init
Turn off -O_hoist_iter_init
-O_inline
Turn on inlining. By default, this inlines routines
and iters which are less than 16 statements and expres-
sions. This is also enabled by "-O" and "-O_fast".
-O_no_inline
Turn off inlining
-O_inline_routines threshold
-O_inline_iters threshold
These options set the threshold for inlining routines
and iters respectively. The threshold is a positive
integer specifying the maximum complexity of a function
to be inlined. The optimal threshold seems to be around
16 for many machines (default)
-O_move_while
Attempt to move while! and until! to the end of loop in
order to improve performance. If a while! or until! is
at the beginning of the loop, this option moves it to
the end and encloses the loop in an if statement. This
allows us to move more loop constants and iter initial-
izations out of the loop.
-O_no_move_while
Turn off -O_move_while
pSather Optimizations Options
-O_cache
Enables caching in distributed programs; uses the
default cache of 1024 cache slots of 8 bytes
-O_cache_size size
Defines the cache size. size must be a power of 2
-O_cache_slot_size size
Defines the cache slot size. size must be a power of 2.
-O_prefetch
Turn prefetching on when the compiler can prove that it
could be of benefit- the value can be used later.
(pSather only)
-O_loop_prefetch
The same as -O_prefetch, but also enables prefetching
when the value may not be used because a loop ter-
minates earlier (pSather only)
-O_specul_prefetch
The same as -O_loop_prefetch, but also enables pre-
fetching in cases where the value may not be used
because the function terminate earlier. (pSather only)
-O_prefetch_weight weight
Defines how many statements and expressions have to be
between the prefetch call and the used of the value
(default 15)
-O_post_write
Enables post-writing
-O_parloops
Enables parloop optimizations
-O_local
Enables optimizations of local attribute accesses.
-O_local_call
The same as -O_local, but the compiler emits different
function versions for special cases when some arguments
are local. If it is statically possible to decide that
that an optimized version is to be used at all times,
the call is replaced with a call to the optimized ver-
sion.
-O_local_call_access number
Define the number of of attribute accesses for attri-
butes of function arguments to emit specialized ver-
sions for the function (default is 1)
-O_local_call_dynamic
Similar to -O_local_call, but the checks of which ver-
sion of a function to call are performed dynamically at
run time.
-O_local_call_dynamic_access number
Defines the number of attribute access to insert
dynamic checks before the function call (default 3)
-O_remote_call
Emit optimized code for calls with local arguments
-O_remote_call_create
Make remote calls even if it means that some objects
will be created on another cluster.
-O_remote_call_access number
Define a number of attribute accesses for aprticular
function argument to enable a remote call.
-O_yields_in_locks
Make some optimizations regarding yields inside locks.
-O_no_yields_in_locks
Turn off -O_yields_in_locks
-O_locks_on_stack
Checks if lock statements can be left through raise. If
so, they have to be put on the exception stack. Nor-
mally all lock statements are put on the exception
stack.
-O_no_locks_on_stack
Turn off -O_locks_on_stack
Other generation options
-debug_source
Generate Sather source line symbolic debugging informa-
tion suitable for use with a debugger. This option is
mutually exclusive with "-debug_C".
-debug_C
Generate C source line symbolic debugging information
suitable for use with a debugger. Other debugging
options that would normally point to the Sather source
will point to the generated C source instead. This
option is mutually exclusive with "-debug_source".
When used without other debugging options this option
is usually equivalent to "-C_flag -g -pretty".
-debug
Adds type tables and links with additional functions
that allow printing complex data structures. It also
provides better error reporting. See Doc/Debugging for
more information.
-debug_graphical
Adds type tables and links with additional functions
that allow displaying complex data structures graphi-
cally. This option requires installing Sather GUI (by
executing "make optional"). Currenly, this option can-
not be used to debug code that uses Sather GUI. See
Doc/Debugging for more information.
-debug_deterministic
Causes compilation with deterministic object id's.
Programs compiled with "-debug_deterministic" should
always execute identically, even on different platforms
(unless there are differences in input, word size or
external classes). This is accomplished by an addi-
tional field in each object which is given a unique id
at the time of creation. Without this flag it is pos-
sible that differences in object allocation due to
dark, sinister forces can cause nondeterminism. By
default determinism is off.
-psather_stats
Causes pSather code to be emitted to collect and print
statistics about locking and remote accesses.
-C_flag flag
Specifies an additional flag that will be appended to
the C compiler command line.
Generation Options you will not want
to use unless you are working on the compiler/optimizer
-O_debug
Print out lots and lots of stuff regarding the optim-
izer, and turns all functions of the class OPT_DEBUG
into side effect free functions, so that they can be
moved by the optimizer even though they have plenty of
side effects. This way it could be checked exactly if
functions are moved.
-O_side_effects
Turn on side effect calculations. In itself, this is
useless, but some of the optimizations depend on it and
turn it on implicitly.
-O_no_side_effects
Turn off -O_side_effects
-O_side_debug
Print out debug information (more or less complete side
effects for each and every function).
-O_cse_debug
Show which expressions have been eliminated
FILE OPTIONS
-com file
The text of a command file is interpreted as additional
options in the command line at the point where `-com'
was encountered. If the environment variable
SATHER_LIBRARY is defined, its contents are interpreted
as further commands following the initial file list in
the command line. Files with the suffix ".module" are
treated as command files automatically.
Relative file names on the command line or in the
SATHER_LIBRARY variable are relative to the current
directory; those in command files are relative to the
file in which they occur. Environment variables of the
form "$(VAR)" or "${VAR}" are expanded in-line.
Comments in command files start with `--' and continue
to the end of the line. An alternate form begins with
"(*" and continues until a closing "*)".
-external CLASS file(s)
C, object and archive files can be given on the command
line, in which case they will be passed to the C com-
piler at link time. However, it is also possible to
associate files with a particular external class; these
files will not be passed to the C compiler unless the
external class is reachable from the Sather code. This
can result in faster compilation and smaller execut-
ables.
-external allows literal string arguments. Environment
variables of the form "$(VAR)" and "${VAR}" are
expanded in-line. "-l" and "-L" could be used inside a
string literal to indicate libraries and library direc-
tories: -external FOO "-L${LIB_DIR} -lfoo"
-end This option does nothing, and is useful for separating
lists of files passed to another option such as "-
external".
ENVIRONMENT
SATHER_HOME
Defines the home directory of the sather installation.
This variable must be defined.
SATHER_LIBRARY
Used to find the standard sather library. If not
defined, it will use
$SATHER_HOME/Library/Library.module
PSATHER_LIBRARY
Used to find the parallel versions of the library. If
-psather is on, the compiler will first check this
variable, then SATHER_LIBRARY and at the end use
SATHER_HOME/Library/pLibray.module
START_GDB
If this variable is defined, the sather program will
start gdb if it encounters a fatal error. If you run a
psather program you need X windows for this option.
CLUSTERS
Only used while running a pSather program. It defines
how many clusters should be used during this run. By
default the program starts 4 clusters.
DEBUG_PSATHER
If this variable is defined, the pSather program starts
an xterm with a running gdb for each cluster of a
psather program.
SEE ALSO
See the file "Doc/Debugging" for information on how to debug
Sather and pSather programs and check out
http://www.icsi.berkeley.edu/~sather.
BUGS
See the file "Doc/Bugs" in the Sather distribution. Send
bug reports to "sather-bugs@icsi.berkeley.edu".