MAN page from Other ICSI-Sather-1.2-0.i386.rpm

CS

Section: User Commands (1)
Index

NAME

cs - Sather 1.1 compiler

SYNOPSIS

cs[filesandoptions]

DESCRIPTION

csis the Sather/pSather 1.1 compiler. A specification of the Sather language andmore information can be obtained by anonymous ftp from "icsi.berkeley.edu:/pub/sather"or in the WWW at "http://www.icsi.berkeley.edu/Sather". Postscript shouldalso 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 installationdirectory of the compiler at your site.Then a file "foo.sa" with the FOO class containing main can becompiled 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 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 thestandard libraries will be loaded from the installation automatically.If SATHER_LIBRARY is set, it is interpreted as additional commandline arguments before other arguments are processed. If you compilea 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 fileand-convert_allcan be used for automatic conversion of Sather 1.0 source files toSather 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 thisoption together with -only_parse
It is safe to attempt more than one conversion of the same file.Also, see convert_alland-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 conversionof already converted files. It is advantageous to use this option together with -only_parse.Also, seeconvert and-V1.0
-main class: Specifies the class whosemainroutine will become the firstexecuted function. If this option is not provided there mustbe a class MAIN containing a routinemainwhich 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 filesfrom previous compiles, which sometimes results in a dramatic speedup.
-pretty: Generate C files that are as readable as possible, doing properindentation 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 whichthis is provided will only be parsed if there is a reference toa listed class. This option is used to avoid parsing librarycode which is not reached. Classes with different numbers of parametersare 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 notinvoke the C compiler. Also generates C files in the current directory asif "-output_C" had been given.
-only_reachable: Inhibit type checking of unreachable code; by default all codeis 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 executablesize.

Checking options

There are a number of checks that may be enabled. Checks havethe useful property that if a program runs to completion with checkson, it will run to completion with them off, given the same input andcomputational environment. (This may not be true for nondeterministiccode such as pSather programs.)All checking options ofthe form -chk_chk may be disabledby 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 shortcutfor 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 caseor typecasestatement to not provide a suitablewhenorelseclause for its argument. If when clause checks areenabled, this results in a fatal error. When clause checks areusually inexpensive.
-chk_void class(es): It is illegal access an attribute, access an array element, or dispatchon the type ofvoid.Void checks are usually inexpensive.
-chk_arith class(es): It is possible for certain routines inINTto cause fatal errors. Examples are overflowing or division byzero. Some arithmetic checks are inexpensive and some may be quiteexpensive, depending on the processor and compiler. Because arithmetic operations account for the bulk of the processing time of many programs, by default only those operationswhich are very inexpensive have checking turned on (such as those that can beperformed without additional code in-line, often division by zero.)
-chk_bounds class(es): It is not legal to accessAREFelements with indices below zero or aboveasize-1.Out-of-bounds checks ensure that attempting such an access results ina fatal error.
-chk_pre class(es)
-chk_post class(es)
-chk_assert class(es)
-chk_invariant class(es): pre, post, assertandinvariantare Sather language constructs which allow programmers to provide checksof their own. These may be expensive, especially invariants, which are checkedafter every routine call.
-chk_destroy: The routineSYS::destroy($OB)allows programmers to assert that objects should no longer be accessed bythe program. With optimization on and destroy checking off,this becomes a memory deallocation andpotential source of dangling pointer errors. With destroy checking on,the compiler tests every object access to make sure it is not to an objectwhich has been destroyed. Because of garbage collection,explicit calls to destroy are not necessary except in time criticalapplications. 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 illegalto unlock a lock more times than it has been locked, or to unlock alock 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 besomething other than a raise or return. When return checks are on, a testoccurs 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 enabledexcept 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 anattempt 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 iterswhich are less than 16 statements and expressions. This is alsoenabled 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 itersrespectively. The threshold is a positive integer specifying themaximum complexity of a function to be inlined. The optimal thresholdseems to be around 16 for many machines (default)
-O_move_while: Attempt to move while! and until! to the end of loop in orderto 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 ifstatement. This allows us to move more loop constants and iterinitializations 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 notbe used because a loop terminates earlier (pSather only)
-O_specul_prefetch: The same as -O_loop_prefetch, but also enables prefetching in cases wherethe 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 prefetchcall 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 forspecial cases when some arguments are local. If it is statically possibleto 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 argumentsto 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 functionto call are performed dynamically at run time.
-O_local_call_dynamic_access number: Defines the number of attribute access to insert dynamic checks before thefunction 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 lockstatements 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 linesymbolic debugging information suitable for use with a debugger.This option is mutually exclusive with "-debug_C".
-debug_C: Generate C source linesymbolic debugging information suitable for use with a debugger.Other debugging options that would normally point to the Sather sourcewill point to the generated C source instead.This option is mutually exclusive with "-debug_source". When used withoutother 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 GUIi.e. you cannot use -gui or -dual_gui together with this option.
-debug_deterministic: Causes compilation with deterministic object id's. Programs compiledwith "-debug_deterministic" should always execute identically, even ondifferent platforms (unless there are differencesin input, word size or external classes).This is accomplished by an additional fieldin each object which is given a unique id at the time of creation.Without this flag it is possible that differences in object allocationdue to dark, sinister forces can cause nondeterminism. By defaultdeterminism is off.
-psather_stats: Causes pSather code to be emitted to collect and print statisticsabout locking and remote accesses.
-C_flag flag: Specifies an additional flag that will be appended to the Ccompiler 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 thatthey 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 optionsin the command line at the point where `-com' was encountered.If the environment variable SATHER_LIBRARY is defined, itscontents are interpreted as further commands following the initial file list inthe command line. Files with the suffix ".module" are treatedas command files automatically.

Relative file names on the command line or in the SATHER_LIBRARYvariable are relative to the current directory; those in command filesare relative to the file in which they occur. Environment variables ofthe form "$(VAR)" or "${VAR}" are expanded in-line.

Comments in command files start with `--' and continue to the end ofthe line. An alternate form begins with "(*" and continues untila closing "*)".

-external CLASS file(s)

C, object and archive files can be given on the command line, in whichcase they will be passed to the C compiler at link time. However, itis also possible to associate files with a particular external class;these files will not be passed to the C compiler unless the externalclass is reachable from the Sather code. This can result in fastercompilation and smaller executables.

-external allows literal string arguments. Environment variablesof the form "$(VAR)" and "${VAR}" are expanded in-line. "-l" and "-L"could be used inside a string literal to indicate libraries andlibrary directories: -external FOO "-L${LIB_DIR} -lfoo"

-end

This option does nothing, and is useful for separating lists offiles passed to another option such as "-external".

ENVIRONMENT

SATHER_HOME: Defines the home directory of the sather installation. This variablemust 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 atthe end use SATHER_HOME/Library/pLibray.module
START_GDB: If this variable is defined, the sather program will start gdb if itencounters a fatal error. If you run a psather program you need X windowsfor this option.
CLUSTERS: Only used while running a pSather program. It defines how many clustersshould 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.

BUGS

See the file "Doc/Bugs" in the Sather distribution. Send bug reportsto "sather-bugsAATTicsi.berkeley.edu".

Index

CODE GENERATION OPTIONS

Checking options
By default only void, when clause, return, and bounds checks are performed.
Optimization Options
pSather Optimizations Options
Other generation options
Generation Options you will not want

This document was created byman2html,using the manual pages.