# Annex A
Sather 'man' Page

#### sacomp - Sather 1.1 compiler

#### Synopsis

sacomp [ files and options ]

#### Description

sacomp is the compiler for the Sather language version 1.1. A specification of the language and more information can be obtained by anonymous ftp or on the WWW. Documentation in HTML or Postscript form should also be in the "doc" directory of the distribution. There is also a newsgroup "comp.lang.sather" which will be of use to communicate with the wider Sather community.

#### Usage

The environment variable SATHER_HOME must be set to the installation directory of the compiler at your site. A file "foo.sa" with the FOO class containing main can be compiled with the command "sacomp foo.sa -main FOO".

For example, a user might have set the environment variable SATHER_HOME to "/usr/lib/sather" and added "/usr/lib/sather/bin" to the execution search path.

To convert source files for versions of Sather prior to 1.1 syntax use options -convert file_name or -convert_all.

#### Files

File names must be in one of the following forms :-

- file.sa - A Sather source file
- file.module - A Sather command 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 any other arguments are processed.

#### General Options

The use of an option '-V1.0' to compile old form syntax is strongly deprecated. One of the first two options in the following table should be used to convert from pre-version 1.0 syntax to Sather 1.1 syntax instead.

-convert <file>

Converts a source file with a given name from Sather 1.0 syntax 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' (see below)

NOTE | It is safe to attempt more than one conversion of the same file. Also, see '-convert_all' below.

-convert_all | Converts all reachable Sather source files given from Sather 1.0 syntax to Sather 1.1 syntax. The original files are renamed to <file>. sa.1.0. It is advantageous to use this option together with '-only_parse' (see below)
-main <class> | Specifies the class whose main routine will become the first executed function. If this option is not provided there must be a class MAIN containing a routine main which will be used.
-o <file> | Specifies the name to be given to the final executable file image. If this is not provided then the name wil default to a.out.
-output_C | Do not delete the directory containing C files after compilation. The directory is the executable name followed by `.code'. Not deleting this directory allows the compiler to attempt to re-use object files produced from a previous compilation. This sometimes results in a dramatic speedup.
-pretty | Generate C files that are as readable as possible, providing indentation and adding comments where possible.
-verbose | Give information about the progress and timing of compilation.
-prolix | Give considerable quantities of output information indicating the files and configuration facilities being used by the compiler, classes compiled, etc. This should only be necessary when debugging compiler configuration information.
-only_parse | Stop compilation after all Sather files have been parsed.
-has <file> <class list> | 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 type checking but do not generate C for any code.
-only_C | Stop compilation after the C code has been generated; do not invoke the C compiler. C files are generated in the current directory as if '-output_C' had been used.
-only_reachable | Inhibit type checking of unreachable code; by default all code is checked.
-version | Sends the compiler versionnumber, list of installed platforms, default platform, and compiler home directory to the standard output channel.

#### Code Generation Options

These options may affect compile time, execution time, and executable size.

##### Checking Options

There are a number of run-time checks which may be enabled by using these options. Checks have the useful property that if a program runs to completion with checks on, it will run to completion with them off, given the same input and computational environment. This may not be true for non-deterministic code in concurrent programs.

All checking options of the form -chk_<check> may be disabled by using an option of the form -chk_no_<check>. Most checking options accept a list of classes for which checking code is to be generated. Giving the pseudo-class-name "all" (which is not a legal class name) is a shortcut for listing all classes.

-chk_no_line_numbers | Do not include line numbers when reporting a violated check. Omitting these improves incrementality.
-chk_when <class list> | It is not legal for a case or typecase statement not to provide a suitable when or else clause for its argument. If when clause checks are enabled, this results in a fatal error. When clause checks are usually inexpensive.
-chk_void <class list> | It is illegal to access an attribute, access an array element or dispatch on the type of void. Void checks are usually inexpensive.

-chk_arith <class list>

It is possible for certain routines in limited numeric classes 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 inexpensive have checking turned on (such as those that can be performed without additional code in-line, often division by zero.)

-chk_bounds <class list> | It is not legal to access elements of a class which includes the constructor class AREF 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 list> | Generate code for all pre-conditions in the specified classes. These may be expensive since they are checked before every relevant method call.
-chk_post <class list> | Generate code for all post-conditions in the specified classes. These may be expensive since they are checked after every relevant method call.
-chk_assert <class list> | Generate code for all assertions in the specified classes. These are not usually very expensive since they are in-line code.
-chk_invariant <class list> | Generate code for all invariants in the specified classes. These may be expensive since they are checked after every non-private method call.

-chk_destroy

The routine SYS::destroy allows programmers to assert that objects should no longer be accessed by the program. With optimization on and destroy checking off, this becomes a direct hint to the garbage collector that the memory may be deallocated. This may therefore be a potential source of dangling pointer errors. With destroy checking 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 destroy should only be necessary in time critical applications. Because it is dangerous, destroy should only be used by experts.

-chk_psather | Generate code to check the so-called sanity of concurrent code; for example, 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 option when enabled also enables deadlock detection.
-chk_return <class list> | 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. These return checks are not usually expensive.
-chk_all <class list> | This turns on all checking for the indicated classes.
-chk | This option is a short-hand for "chk_all all". It is recommended for use to assure the greatest level of safety.
-chk_no_all <class list> | No check code will be generated for the listed classes.
-chk_no | This option is a short-hand for "chk_no_all all". It should be used with caution!

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.

##### 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 | Send optimisation statistics to the standard output channel during compilation.
-O_fast | Turn on optimizations and turn off all checking. This has the same effect as "-O -chk_no_all all". It should be used 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' (see below) is not, many initializations of once arguments are still hoisted, although that option is less aggressive than this.
-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 in-lining. By default, this in-lines routines and iters which are less than 16 statements and expressions. This is also enabled by '-O' and '-O_fast'.
-O_no_inline | Turn off inlining.
-O_inline_routines <threshold> | Set the threshold for inlining routines. The threshold is a positive integer specifying the maximum complexity of a function to be inlined. The optimal threshold seems to be around 16 (the default value) for many machines.
-O_inline_iters <threshold> | Set the threshold for inlining iters. The threshold is a positive integer specifying the maximum complexity of a function to be inlined. The optimal threshold seems to be around 16 (the default value) for many machines.
-O_move_while | Attempt to move while! and until! calls 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 more loop constants and iter initialisations to be moved out of the loop.
-O_no_move_while | Turn off '-O_move_while'.

##### Concurrent Optimization Options

-O_cache | Enables caching in distributed programs; uses the default cache of 1024 cache slots of 8 bytes each.
-O_cache_size <size> | Define the cache size which must be a power of 2.
-O_cache_slot_size <size> | Define the cache slot size which must be a power of 2.
-O_prefetch | Turn pre-fetching on when the compiler can prove that it could be of benefit - the value can be used later.
-O_loop_prefetch | This option takes the actions for '-O_prefetch' (above) and also enables pre-fetching when the value may not be used because a loop terminates early.
-O_specul_prefetch | This option takes the actions for '-O_loop_prefetch' (above) and also enables pre-fetching in cases where the value may not be used because the function terminates early.
-O_prefetch_weight <weight> | Defines how many statements and expressions have to be between the pre-fetch call and the use of the pre-fetched value. The default value is 15.
-O_post_write | Enable post-writing.
-O_parloops | Enable parloop optimisations.
-O_local | Enable optimizations of local attribute accesses.
-O_local_call | This performs the same actions as '-O_local' except that 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 version.
-O_local_call_access <number> | Define the number of of attribute accesses for attributes of function arguments to emit specialized versions for the function. The default value is 1.
-O_local_call_dynamic | This is similar to '-O_local_call', but the checks of which version of a function to call are performed dynamically at run time.
-O_local_call_dynamic_access <number> | Define the number of attribute access to insert dynamic checks before the function call. The default value is 3.
-O_remote_call | Emit optimized code for remote 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 a particular function argument to enable a remote call.
-O_yields_in_locks | Make some optimisations regarding yields inside locks.
-O_no_yields_in_locks | Turn off the effect pof '-O_yields_in_locks'.
-O_locks_on_stack | Check if lock statements can be left through a raise statement. If so, they have to be put on the exception stack. Normally all lock statements are put on the exception stack.
-O_no_locks_on_stack | Turn off the effect of '-O_locks_on_stack'.

##### Other Code Generation Options

-debug_source | Generate Sather source line symbolic debugging information 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 | Add type tables and links with additional functions that allow printing complex data structures. It also provides better error reporting. See the User Guide for more information.
-debug_graphical | Add type tables and links with additional functions that allow displaying complex data structures graphically. This option requires installing Sather GUI. Currently, this option cannot be used to debug code that uses Sather GUI i.e. you cannot use -gui or -dual_gui together with this option.

-debug_deterministic

Cause compilation with deterministic object id's. Programs compiled with this option should always execute identically, even on different platforms (unless there are differences in input, word size or external classes). This is accomplished by an additional field in each object which is given a unique id at the time of creation. Without this flag it is possible that differences in object allocation due to dark, sinister forces can cause non-determinism. By default determinism is off.

-psather_stats | Causes code to be generated to collect and print statistics about locking and remote accesses.
-C_flag " flag" | This option specifies a C compiler flag that will be appended to the C compiler command line.

##### Generation Options for Compiler Debugging

-O_debug | Send to the standard output channel lots and lots of stuff regarding the optimizer, 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 | Send debug information consisting of more or less complete side effects for each and every function to the standard output channel.
-O_cse_debug | Send to the standard output channel during compilation information about 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 environment variable (see below) 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 *quot;(*" and continues until a matching closing "*)".

-external <CLASS file(s)>

Object, archive and C files can be given on the command line, in which case they will be passed to the C compiler 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 executables.

The use of this option 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 directories, for example

-external FOO "-L${LIB_DIR} -lfoo"

-end | This option does nothing except act as a separator of lists of files passed to another option such as '-external'.

#### Environment Variables

SATHER_HOME | Defines the home directory of the Sather installation. This variable must be defined.

LOCALE

This should have a value composed of two two-letter abbreviations separated by a Low Line character - '_'. The first two letters should be the language of the local culture using the abbreviation specified in ISO 639; the second pair defines the territory as given in ISO 3166.

NOTES | 1. During initial beta release the only complete locale available with the distribution is 'en_NZ'!
| See also the documentation on the cultural compiler salccomp in the distribution directory "doc/auxiliary/lcc" for details of creating new cultural descriptions when the full version of salccomp becomes available.

SATHER_ENV | This environment variable must be set to the value <SATHER_HOME>/resources/<LOCALE>/bin/LIBCHARS It enables the culture-dependent Sather run-time system to access low-level parameters found in the file which is created using salccomp.

SATHER_RESOURCES

This environment variable is optional unless a program which provides textual interaction with its execution environment is being run. In that case additional directories and message files (see doc/specification/Resources/index.html) will need to be set up to contain the relevant message formatting strings. This environment variable, therefore, is expected to be a search path (see note above) of directories to be used when setting up the resources for the program at execution time. This search path is normally expected to contain the Resource directory used by the Required Library implementation specifications) -
<SATHER_HOME>/Resources/<LOCALE>

SATHER_LIBRARY | This environment variable is optional. It should provide the absolute path of the Required Library module file (called lib.module). If this is not defined, a default value of <SATHER_HOME>/lib/lib.module is used.
CLUSTERS | This environment variable specifies how many clusters are to be started during the current execution of a distributed program. The default value is 4. If a program is not concurrent and distributed then this variable is unused.

START_GDB

If this environment variable is defined an executing program which encounters a fatal error will attempt to start the debugger gdb.

NOTE | If a concurrent program is being run, the implementation requires that X windows be operating for this to work.

DEBUG_PSATHER | If this environment variable is defined and the program executing is concurrent (providing that X windows is running), it starts an xterm running gdb for each cluster of the program.

#### See Also

See the User Guide for information on how to debug both sequential and concurrent Sather programs and refer also to the Gnu web site.

#### Bugs

See the file doc/bugs in the Sather distribution. Reports of new bugs should be sent to "bug-sather@gnu.org".

| Home Page |  | User Guide

Comments or enquiries should be made to Keith Hopper Page last modified: Friday, 9 February 2001. |