home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sa104os2.zip / SATHR104.ZIP / SATHER / DOC / MAN / CAT1 / CS.1 next >
Text File  |  1994-11-18  |  11KB  |  331 lines
  1.  
  2.  
  3.  
  4. CS(1)                     User Commands                     CS(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      cs - Sather 1.0 compiler
  10.  
  11. SYNOPSIS
  12.      cs [ files and options ]
  13.  
  14. DESCRIPTION
  15.      cs is the Sather  1.0  compiler.   A  specification  of  the
  16.      Sather  language  and  more  information  can be obtained by
  17.      anonymous ftp from "icsi.berkeley.edu:/pub/sather" or in the
  18.      WWW  at  "http://http.icsi.berkeley.edu/Sather".  Postscript
  19.      should also be in the "Doc" directory of  the  distribution.
  20.      There is also a newsgroup "comp.lang.sather".
  21.  
  22. FILES
  23.      File names must be in one of the following forms:
  24.  
  25.      _f_i_l_e.sa -  A Sather source file.
  26.  
  27.      _f_i_l_e.c -  A C source file.
  28.  
  29.      _f_i_l_e.o -  An object file.
  30.  
  31.      _f_i_l_e.a -  An archive file.
  32.  
  33.  
  34. GENERAL OPTIONS
  35.      -main _c_l_a_s_s
  36.           Specifies the class whose _m_a_i_n routine will become  the
  37.           first  executed  function.   If this option is not pro-
  38.           vided there must be a class MAIN containing  a  routine
  39.           _m_a_i_n which will be used.
  40.  
  41.      -o _f_i_l_e
  42.           Produce the executable _f_i_l_e. If this  is  not  provided
  43.           the default file name is `a.out'.
  44.  
  45.      -output_C
  46.           Do not delete the directory containing  C  files  after
  47.           compilation.  The directory is the executable name fol-
  48.           lowed by `.code'.
  49.  
  50.      -pretty
  51.           Generate C files that  are  as  readable  as  possible,
  52.           doing  proper indentation and adding comments when pos-
  53.           sible.
  54.  
  55.      -verbose
  56.           Give information about what the compiler is doing.
  57.  
  58.      -psather
  59.           Accept  pSather  code.   This  option  is  useful   for
  60.  
  61.  
  62.  
  63. Sun Microsystems          Last change:                          1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CS(1)                     User Commands                     CS(1)
  71.  
  72.  
  73.  
  74.           verifying  that  Serial  Sather  code  does not use any
  75.           pSather keywords that could cause problems if the  code
  76.           is to be used on pSather systems.
  77.  
  78.      -only_parse
  79.           Stop compilation  after  all  Sather  files  have  been
  80.           parsed.
  81.  
  82.      -has _f_i_l_e _c_l_a_s_s(_e_s)
  83.           Inform the compiler what classes are in a file.   Files
  84.           for which this is provided will only be parsed if there
  85.           is a reference to a listed class.  This option is  used
  86.           to  avoid  parsing  library  code which is not reached.
  87.           Classes with different numbers of  parameters  are  not
  88.           distinguished.
  89.  
  90.      -only_check
  91.           Perform typechecking but do  not  generate  C  for  any
  92.           code.
  93.  
  94.      -only_C
  95.           Stop the compile after the C code  has  been  generated
  96.           and  do  not  invoke  the C compiler.  Also generates C
  97.           files in the current directory as  if  "-output_C"  had
  98.           been given.
  99.  
  100.      -only_reachable
  101.           Inhibit type checking of unreachable code;  by  default
  102.           all code is checked.
  103.  
  104. CODE GENERATION OPTIONS
  105.      These options may affect compile time, execution  time,  and
  106.      executable size.
  107.  
  108.   Checking options
  109.      There are a number of checks that may  be  enabled.   Checks
  110.      have  the  useful property that if a program runs to comple-
  111.      tion with checks on, it will run  to  completion  with  them
  112.      off,  given  the  same  input and computational environment.
  113.      All checking options are of the form -_c_h_k and  may  be  dis-
  114.      abled  by using an option of the form -no__c_h_k.  All checking
  115.      options accept a class list.  Giving the  class  name  "all"
  116.      (illegal  as  a  class  name  because it is lower case) is a
  117.      shortcut for listing all classes.
  118.  
  119.      -when _c_l_a_s_s(_e_s)
  120.           It is not legal for a _c_a_s_e or _t_y_p_e_c_a_s_e statement to not
  121.           provide  a  suitable  _w_h_e_n or _e_l_s_e clause for its argu-
  122.           ment.  If when clause checks are enabled, this  results
  123.           in a fatal error.  When clause checks are usually inex-
  124.           pensive.
  125.  
  126.  
  127.  
  128.  
  129. Sun Microsystems          Last change:                          2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CS(1)                     User Commands                     CS(1)
  137.  
  138.  
  139.  
  140.      -void _c_l_a_s_s(_e_s)
  141.           It is illegal access an attribute, access an array ele-
  142.           ment,  or dispatch on the type of _v_o_i_d. Void checks are
  143.           usually inexpensive.
  144.  
  145.      -arith _c_l_a_s_s(_e_s)
  146.           It is possible for certain routines  in  _I_N_T  to  cause
  147.           fatal  errors.  Examples are overflowing or division by
  148.           zero.  Some arithmetic checks are inexpensive and  some
  149.           may  be quite expensive, depending on the processor and
  150.           compiler.  Because arithmetic  operations  account  for
  151.           the  bulk  of  the processing time of many programs, by
  152.           default only those operations which are  very  inexpen-
  153.           sive have checking turned on (such as those that can be
  154.           performed without additional code in-line, often  divi-
  155.           sion by zero.)
  156.  
  157.      -bounds _c_l_a_s_s(_e_s)
  158.           It is not legal to access _A_R_E_F  elements  with  indices
  159.           below  zero  or  above  _a_s_i_z_e -1.  Out-of-bounds checks
  160.           ensure that attempting such  an  access  results  in  a
  161.           fatal error.
  162.  
  163.      -pre _c_l_a_s_s(_e_s)
  164.  
  165.      -post _c_l_a_s_s(_e_s)
  166.  
  167.      -assert _c_l_a_s_s(_e_s)
  168.  
  169.      -invariant _c_l_a_s_s(_e_s)
  170.           _p_r_e, _p_o_s_t, _a_s_s_e_r_t and  _i_n_v_a_r_i_a_n_t  are  Sather  language
  171.           constructs which allow programmers to provide checks of
  172.           their own.  These may be expensive, especially  invari-
  173.           ants, which are checked after every routine call.
  174.  
  175.      -destroy _c_l_a_s_s(_e_s)
  176.           The routine  _S_Y_S::_d_e_s_t_r_o_y($_O_B)  allows  programmers  to
  177.           assert that objects should no longer be accessed by the
  178.           program.  With optimization  on  and  destroy  checking
  179.           off,  this  becomes a memory deallocation and potential
  180.           source of dangling pointer errors.  With destroy check-
  181.           ing  on, the compiler tests every object access to make
  182.           sure it is not to an object which has  been  destroyed.
  183.           Because  of  garbage collection, explicit calls to des-
  184.           troy are not necessary except in time critical applica-
  185.           tions.  Because it is dangerous, destroy should only be
  186.           used by experts.
  187.  
  188.      -return _c_l_a_s_s(_e_s)
  189.           It is a fatal error for the last statement executed  by
  190.           a routine to be something other than a raise or return.
  191.           When return checks are on, a test occurs which enforces
  192.  
  193.  
  194.  
  195. Sun Microsystems          Last change:                          3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CS(1)                     User Commands                     CS(1)
  203.  
  204.  
  205.  
  206.           this.  Return checks are usually inexpensive.
  207.  
  208.  
  209.      By default only void, when clause, return, and bounds checks
  210.      are  performed.  It should not be possible to crash a Sather
  211.      program with the default checks enabled except  by  improper
  212.      external  calls or destroys.  It is also possible to turn on
  213.      or off all checking:
  214.  
  215.      -check _c_l_a_s_s(_e_s)
  216.           Specify that all checks within the classes  occur.  " -
  217.           check  all" is recommended to assure the greatest level
  218.           of safety.
  219.  
  220.      -no_check _c_l_a_s_s(_e_s)
  221.           Generated code will  not  perform  any  checks,  except
  222.           those that will not result in less efficient code.  Use
  223.           this with caution.
  224.  
  225.   Other generation options
  226.      -optimize or -O
  227.           Attempt optimizations; this may  lengthen  the  compile
  228.           time in an attempt to improve code quality.  By default
  229.           only  very  fast  optimizations  are  performed.   This
  230.           option is turned on by -fast.
  231.  
  232.      -fast
  233.           Turn on optimizations and turn off all checking.   Same
  234.           as "-optimize -no_check all".  Use with caution.
  235.  
  236.      -debug or -g
  237.           Generate symbolic debugging information.
  238.  
  239.      -deterministic
  240.           Causes  compilation  with  deterministic  object  id's.
  241.           Programs  compiled  with "-deterministic" should always
  242.           execute  identically,  even  on   different   platforms
  243.           (unless  there  are  differences in input, word size or
  244.           external classes).  This is accomplished  by  an  addi-
  245.           tional  field in each object which is given a unique id
  246.           at the time of creation.  Without this flag it is  pos-
  247.           sible  that  differences  in  object  allocation due to
  248.           dark, sinister forces  can  cause  nondeterminism.   By
  249.           default determinism is off.
  250.  
  251.      -C_flag _f_l_a_g
  252.           Specifies an additional flag that will be  appended  to
  253.           the C compiler command line.
  254.  
  255. FILE OPTIONS
  256.      -home _d_i_r_e_c_t_o_r_y
  257.           Specifies the directory to use for  obtaining  compiler
  258.  
  259.  
  260.  
  261. Sun Microsystems          Last change:                          4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CS(1)                     User Commands                     CS(1)
  269.  
  270.  
  271.  
  272.           system files.  This must be provided.
  273.  
  274.      -com _f_i_l_e
  275.           The text of a command file is interpreted as additional
  276.           options  in  the command line at the point where `-com'
  277.           was   encountered.    If   the   environment   variable
  278.           SATHER_COMMANDS  is  defined,  its  contents are inter-
  279.           preted as further commands following the  initial  file
  280.           list in the command line.
  281.  
  282.           Filename expansion is performed as  in  csh.   Relative
  283.           file   names   on   the   command   line   or   in  the
  284.           SATHER_COMMANDS variable are relative  to  the  current
  285.           directory;  those  in command files are relative to the
  286.           file in which they occur.
  287.  
  288.           Comments in command files start with `--' and  continue
  289.           to the end of the line.
  290.  
  291. EXAMPLE
  292.      Here at ICSI, users should set  their  environment  variable
  293.      SATHER_COMMANDS   to   "-home   /usr/local/lang/sather  -com
  294.      /usr/local/lang/sather/Library/base.commands".  Then a  file
  295.      "foo.sa"  with the FOO class containing main can be compiled
  296.      with the command "cs foo.sa -main FOO".
  297.  
  298.  
  299. BUGS
  300.      See the file "Doc/Bugs" in the  Sather  distribution.   Send
  301.      bug reports to "sather-bugs@icsi.berkeley.edu".
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Sun Microsystems          Last change:                          5
  328.  
  329.  
  330.  
  331.