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".