SACOMP(1)

NAME
sacomp - Sather 1.1 compiler

SYNOPSIS
sacomp [ files and options ]

DESCRIPTION
sacomp is the Sather/pSather 1.1 compiler. A specification of the Sather language and more information can be obtained by anonymous ftp from "ftp://ftp.gnu.org/gnu/sather" or in the WWW at "http://www.gnu.org/software/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 installation directory of the compiler at your site. Then 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/local/lib/sather" and add "/usr/lib/sather/Bin" to their path. To compile pre Sather 1.1 sources, please either use a compiler 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 compiler 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 provided 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 followed by `.code'. Not deleting this directory allows the compiler to re-use object files from previous compiles, which sometimes results in a dramatic speedup.

-pretty
    Generate C files that are as readable as possible, doing proper indentation and adding comments when possible.

-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 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 nondeterministic code such as pSather programs.) All checking options of the form -chk_chk 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_no_line_numbers
    Do not print out line numbers when a check is violated. Omitting line numbers improves incrementality.

-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 argument. If when clause checks are enabled, this results in a fatal error. When clause checks are usually inexpensive.

-chk_void class(es)
    It is illegal access an attribute, access an array element, 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 inexpensive have checking turned on (such as those that can be performed without additional code in-line, often division 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 invariants, 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 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 are not necessary except in time critical applications. 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 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 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 recommended 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 expressions. 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 initializations 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 terminates earlier (pSather only)

-O_specul_prefetch
    The same as -O_loop_prefetch, but also enables prefetching 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 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 (default is 1)

-O_local_call_dynamic
    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
    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. Normally 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 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
    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 graphically. This option requires installing Sather GUI (by executing "make optional"). Currenly, 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 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 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 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 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
    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 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. -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 directories:
        -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/pLibrary.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.gnu.org/software/sather.

BUGS
See the file "Doc/Bugs" in the Sather distribution. Send bug reports to "bug-sather@gnu.org".