Sozobon C

From Atari Wiki
Jump to navigation Jump to search


      





                           The Sozobon C Compiler

                          a freeware offering from

                              Sozobon, Limited


                                Tony Andrews
                                Johann Ruegg
                                  Joe Treat


                               User Reference

                                  3/1/91







      1. Introduction         

      The  Sozobon  C  Compiler  is  a complete implementation of the C
      language  as  defined  by  Kernighan  &  Ritchie  and  prevailing
      practice.    The   package   includes   a   compiler,  optimizer,
      assembler,  and  linker,  as  well  as  several  other associated
      utilities.   For  runtime  library  support,  version  1.2 of the
      public  domain  dLibs routines are used.  Like the dLibs package,
      source  code  and  executables  for all components of the Sozobon
      compiler may be freely distributed.  

      This  document  describes the various components of the system in
      detail.   Chapter  8  contains a convenient command reference for
      the  various utilities included in the system.  Dale Schumacher's
      documentation for the dLibs package is provided separately.  

      1.1 System Overview        


      1.1.1 History            

      The  Sozobon  compiler  was  originally  written as a replacement
      front-end  for  the  buggy  Alcyon  compiler.   Johann  had  been
      working  on  the  compiler  for quite a while, and eventually got
      the  rest  of  us interested in working on the other parts of the
      system.   I  (Tony)  started  working  on  an  optimizer,  mainly
      because  I hadn't written one before and it sounded like fun.  As


                                    - 1 -
�

      Sozobon C Compiler                                 User Reference


      the  pieces  started  coming  together,  we discovered that there
      weren't    any    public   domain   assemblers   that   generated
      Alcyon-compatible  objects.   Joe  offered  to write one, filling
      the last major hole in the project.  

      1.1.2 Distribution            

      The  Sozobon  C Compiler is distributed in both binary and source
      form.   The  programs and code are copyrighted, but may be freely
      distributed.  The only restrictions are: 

       1.  No  charge  may  be  made  other than reasonable charges for
           reproduction.  

       2.  Modified versions must be clearly marked as such.  

       3.  The   authors   are   not   responsible   for   any  harmful
           consequences  of  using  this  software, even if they result
           from defects in it.  

      You  are  encouraged  to  make  copies  for friends, upload it to
      bulletin  boards,  or  distribute it via networks.  This is not a
      shareware  product.   We  wrote this compiler because it was fun,
      not because we expected to make any money from it.  

      1.1.3 Obtaining the Source Code         

      If  you  received  only  a  binary release of the compiler (or if
      your  binary  release  is  incomplete  or outdated), the complete
      source distribution can be obtained by sending $10 ($12 overseas)
      to:
                   Tony Andrews
		   4704 Berkshire Court
                   Boulder, CO  USA 80301


      Be  sure  to  include  your return address, and specify single or
      double-sided   floppies.   Checks  should  be  payable  to  "Tony
      Andrews".   Feel  free  to  split the cost with as many people as
      you  want.   We're interested in getting the compiler distributed
      and used, not in spending our spare time writing floppies.  

      The  complete  release  comes on two single-sided floppies or one
      double-sided floppy containing: 

         * all executables 

         * source code for the compiler 

         * source code for the utilities 

         * documentation 


                                    - 2 -
�

      Sozobon C Compiler                                 User Reference


         * dLibs, version 1.2 (including source) 

      Most of this will be in lharc format to conserve space. Since the
      compiler  can  compile  itself, you will have everything you need
      to hack on any part of the package.  

      1.1.4 Performance            

      The  compiler  runs faster than Alcyon and generates code that is
      generally  better  than Alcyon's.  The Alcyon compiler is smarter
      about  register  allocation  and usage, but the Sozobon optimizer
      makes  up  most  of  the  difference.  Our assembler is better at
      generating  short forms of the branch instructions, so that helps
      too.  

      The  code  generation  appears  to  be  quite solid.  None of the
      problems  that  we  found  during  beta testing involved the code
      generation of the compiler, optimizer, or assembler.  

      1.2 Acknowledgements         

      We'd  like to thank our beta testers for their help in completing
      this  project.   Ian  Lepore, in Denver, was the first to dive in
      and   start   using   the   compiler,   and   made  many  helpful
      suggestions.   Dale  Schumacher  worked  long  hours to get a new
      release  of  dLibs  ready  and pointed out several problems.  And
      Steve  Yelvington  was  the  first  to  develop a GEM application
      using the Sozobon compiler.  

      1.3 Support         

      We're  interested  in receiving bug reports from people using the
      compiler.   We  use  this software every day, so we have a strong
      interest  in  making  sure  it works right.  Feel free to mail us
      bug  reports at the address listed above.  We can also be reached
      at the following electronic addresses: 

           UUCP:     onecom!raid5!tony
           Citadel:  Tony Andrews @ FWBBS


      Bugs  will  be assigned priorities based roughly on the following
      scale: 

       1.  Bug  reports with a fix included. If you give us the fix, it
           will  almost  certainly show up in the next release.  You've
           got the source; don't be afraid to use it.  

       2.  Bug  reports  with  a  good  description of the problem, the
           environment  in  which it occurred, and a SMALL program that
           reproduces the problem.  



                                    - 3 -
�

      Sozobon C Compiler                                 User Reference


       3.  All others.  

      Please   try  to  at  least  isolate  the  problem  to  a  small,
      repeatable  example program.  If you can find the bug and fix it,
      that's  wonderful,  but  at  least  give  us enough infomation to
      duplicate the bug ourselves.  


      2. Development Environment        

      This  section  describes  in  more  detail  the  operation of the
      compiler  and  the relationship between parts of the compiler and
      the corresponding pieces of the Alcyon compiler.  

      The  compiler  works  best  when  used with a shell like 'gulam'.
      There  is currently little support for GEM, either in the runtime
      libraries,  or  in the commands themselves.  None of the commands
      pause  before  exiting,  yet.  Since none of us use GEM, we don't
      have  a very good perspective on how a GEM user would want things
      to  work.   If  you've  used  the  Alcyon  compiler with GEM, you
      should  have  no trouble creating appropriate batch files for the
      Sozobon compiler.  

      The  compiler should be usable on machines with 512K and a single
      disk.  This  document  doesn't  describe  the  optimal layout for
      various  ST  configurations, but you can probably figure out what
      makes  the  most  sense  for  your  machine.   This will probably
      involve  a  ram  disk,  and  some  arrangement  of  programs  and
      libraries on one or more floppies.  

      2.1 Environment Variables        

      Several  environment variables may be used to alter the operation
      of  the  compiler. The variables are used to specify the location
      of  executables,  header  files,  libraries, and temporary files.
      Each   variable  may  reference  a  list  of  directories  to  be
      searched,  with  elements  of  the  list  separated  by commas or
      semicolons.  The variables are: 

           PATH          executables
           INCLUDE       header files
           LIB           startup code and libraries
           TMP           temporary files


      The  "TMP"  variable  is currently only used by 'cc' to construct
      the  object  file  list given to the loader.  Reasonable defaults
      are   assumed  if  these  variables  aren't  set.   The  specific
      defaults are described later in the command references.  





                                    - 4 -
�

      Sozobon C Compiler                                 User Reference


      2.2 Machine Dependencies        

      The supported data types and their sizes (in bytes) are: 

           char            1
           short           2
           int             2
           long            4
           unsigned char   1
           unsigned short  2
           unsigned int    2
           unsigned long   4
           float           4
           double          4
           POINTER         4


      Floating  point  is  supported  using  the  "Fast Floating Point"
      representation  documented  by  Motorola  and  implemented by the
      Alcyon  compiler.  Both 'float' and 'double' types are supported,
      but  are  actually  identical.   We'd  like  to  support the IEEE
      format eventually, but this will have to do for now.  

      Any  of  the  basic  data  types  may  be  declared  as  register
      variables.   Pointers occupy the A registers, all other types are
      placed  in  D  registers.   Five data registers and three address
      registers are available for use by register variables.  

      2.3 Compiler Limits        

      Some limits imposed by the Sozobon compiler are: 

         * Strings are limited to 256 characters in length 

         * Local  variables  are  limited to a total of 32K in size per
           function.  

         * The size of a single structure or array may not exceed 32K.  

         * Include files may not be nested more than 8 deep.  

         * The  assembler  will  have  problems  with  extremely  large
           source  files  that  produce  more  than  32K of code from a
           single file.  

         * Identifiers internal to a file may be of any length.  

         * Only  the  first  7  characters  of external identifiers are
           significant, and case is significant for all identifiers.  
           (fixed in release 2.0 - hans)




                                    - 5 -
�

      Sozobon C Compiler                                 User Reference


      2.4 Relationship to the Alcyon Compiler     

      The   components  of  the  Sozobon  compiler  were  developed  by
      replacing  pieces  of  the  Alcyon compiler one by one.  For this
      reason,  a  certain level of compatibility with the Alcyon system
      was  inevitable.   While  the Alcyon system provided a convenient
      way  to  bootstrap  a  new  compiler,  our  goal  was  not  to be
      completely  compatible with Alcyon.  Compatibility is more in the
      interfaces  between  pieces of the compiler than in their command
      line options.  

      The  Sozobon  compiler program replaces the pre-processor and the
      two  compiler  passes  of  the  Alcyon  system.  This  speeds  up
      compilation  quite a bit.  The output of the compiler is suitable
      for  input  to  other  compatible  assemblers  such  as  Alcyon's
      assembler or the MadMac assembler.  

      The  optimizer is tuned in many ways to the output of the Sozobon
      compiler  and could not (without some modifications) be used with
      the Alcyon compiler, or with hand-written assembly code.  

      The  Sozobon  assembler  was  developed primarily to accept input
      from  the Sozobon compiler (or optimizer) and doesn't support all
      the  features  of  the  Alcyon  or  MadMac  assemblers.   It does
      generate  compatible  object files, though, and generates smaller
      code   since   it   uses  'short'  branch  instructions  wherever
      possible.  

      The  Sozobon  loader  accepts  Alcyon object files and libraries.
      The  function  of  the  'relmod' program is incorporated into the
      loader, so a separate utility isn't needed.  

      The   other   Sozobon  utilities  all  operate  on  and  generate
      Alcyon-compatible object files and libraries.  


      3. Component Overviews        

      The  following  sections  describe  in  detail  the passes of the
      compiler.  

      3.1 Compiler         

      The  compiler is essentially compatible with the Alcyon compiler,
      but  is  stricter  about  type  checking  and will complain about
      things  that  Alcyon permits.  The compiler implements the full C
      language as described by K&R, with the usual extensions: 

         * bit fields 

         * enumerations 



                                    - 6 -
�

      Sozobon C Compiler                                 User Reference


         * structure assignment 

         * structure parameters 

         * structure return values 

         * assembly escapes 

      Most  of the features listed above are self-explanatory. Assembly
      code can be embedded within C using the following syntax: 

           asm("assembly code");


      The  string  within quotes is passed directly to the output file.
      It  is  preceded  by  a  tab, and followed by a newline, so these
      don't  need to be given in the string.  Extreme caution should be
      used  when running the optimizer on C code that contains assembly
      escapes.  

      The  compiler  has been tested with the "C Compiler Torture Test"
      from   the   Austin   Code   Works.   This  tests  for  full  K&R
      compatibility.   The  compiler has been used to compile itself as
      well  as  many  other  programs  totaling  around 50,000 lines of
      code.  

      The  compiler  uses  the  "normal"  68000  C calling conventions.
      Register  A6  is  used  as  a  frame pointer, and function return
      values  are  placed in D0.  Registers D3-D7 and A3-A5 are used to
      hold register variables.  

      3.2 Optimizer         

      The  Sozobon  optimizer  accepts assembly language input from the
      compiler  and generates optimized assembly output.  The optimizer
      is  tuned  to  the  output of the compiler and should not be used
      with  hand-written assembly code.  The optimizer performs several
      kinds  of  optimizations.   Command  line  options can be used to
      control  which  kinds  of  operations are performed on the source
      file.  

      The   most   important   function  of  the  optimizer  is  branch
      optimization.   The  compiler's code generation can be simplified
      somewhat   if   an  optimizer  is  used  to  clean  up  redundant
      branches.   Because  branch  optimization lays the foundation for
      everything  else  the  optimizer does, this cannot be disabled on
      the command line.  

      The   other   major  part  of  the  optimizer  performs  peephole
      optimization   replacing   specific  instruction  sequences  with
      shorter  or  faster  ones.   From  one  to three instructions are
      re-written.  The  optimizer  is  able to ignore instructions that


                                    - 7 -
�

      Sozobon C Compiler                                 User Reference


      don't   affect   the   validity   of  the  optimization,  so  the
      instructions  aren't necessarily adjacent.  This process is aided
      by   the   use  of  dataflow  analysis,  which  determines  which
      registers are "live" at each point in a function.  

      This  part  of  the  optimizer  is  more  bug-prone,  and  can be
      disabled  without  affecting  branch  optimization.   The current
      optimizer  is  only  a  start;  the  dataflow  analysis  lays the
      groundwork for many more peephole optimizations.  

      The  optimizer  appears  to be quite solid, and its use is highly
      recommended.  The  compiler  depends pretty much on the optimizer
      to  clean up useless branches, and this helps keep the compiler's
      code generation simple.  

      3.3 Assembler         

      The   assembler   was   designed  to  support  the  compiler  and
      optimizer.   It's  small  (about  half  the  size  of  the Alcyon
      assembler)   and   quite   a   bit   faster.    If   you  want  a
      "user-friendly"  assembler,  you're  probably  better off looking
      elsewhere,  or  hacking  the features you want into our assembler
      yourself.    Besides   being  smaller  and  faster,  the  Sozobon
      assembler  does  a  better  job  of optimizing branch instruction
      sizes.  

      3.4 Linker         

      The   linker   accepts   Alcyon-compatible   object   files   and
      libraries.   It  incorporates the function of the Alcyon 'relmod'
      program,  so a separate utility is not needed.  The linker can be
      instructed  to  make  multiple  passes  over  libraries  if their
      contents are not ordered by dependency.  

      3.5 Utilities         

      Besides  the primary programs, there are several useful utilities
      provided.  

         * The  'cc' program is used to run the passes of the compiler,
           avoiding the use of batch files.  

         * The  'nm'  program  dumps  the symbol table of object files,
           libraries, and executables.  

         * The  'size'  utility  prints the size of text, data, and bss
           for objects, libraries, and executables.  

         * The 'ar' program manages libraries of object modules.  

         * The  'globs'  program  isn't very useful unless you have the
           Alcyon  compiler.  It  removes  local  symbols  from  object


                                    - 8 -
�

      Sozobon C Compiler                                 User Reference


           modules  and libraries.  These aren't needed for linking and
           take  up quite a bit of space.  If you have Alcyon libraries
           that  you  use  frequently, 'globs' can reduce their size by
           around 30%.  (No longer include in 2.0 - hans)

         * An  enhanced  version  of  a public-domain 'make' utility is
           provided and documented in a separate file.  

      3.6 Library         

      The  dLibs  routines,  written by Dale Schumacher provide runtime
      support  for  the  Sozobon  compiler.  We started our development
      using  dLibs  version  1.1,  but  worked  closely with Dale as he
      prepared  his  1.2  release to insure full compatibility with our
      programs.    The   new  release  is  fully  compatible  with  our
      compiler.  

      3.6.1 Startup Code           

      The dLibs C startup code is used to link programs.  

      3.6.2 C Runtime Library          

      The  dLibs  documentation is included in our release, since there
      are no changes for use with the Sozobon compiler.  

      3.6.3 Floating Point Library          

      Our  floating  point code is included as a separate library.  One
      traditional  problem  with C compilers and floating point is that
      as  soon  as you call printf(), you wind up linking in a bunch of
      floating  point  code  whether  you need it or not. To avoid this
      problem   the  dLibs  package  and  our  floating  point  library
      actually  contain  (slightly)  different  versions  of printf and
      scanf.  The versions in the normal library contain no support for
      floating  point.   The  versions in the floating point library do
      support floating point.  

      If  the  "-f"  option  is  passed  to  "cc", the printf and scanf
      routines  are  taken  from the floating point library. Otherwise,
      the  versions  in  the  normal  library are used, and no floating
      point  code gets linked at all, unless required by other parts of
      your program.  

      We  make  no  claims  regarding  the  accuracy  or  speed  of the
      floating  point  code.   This  code  was  thrown  together to get
      something  into  this  release,  but  still needs plenty of work.
      Only the basic operations are supported.  

      Those  of  you with the Alcyon compiler can use the fast floating
      point  library  (libf)  in  place  of  our  routines.   Low level
      conversion  routines between ASCII and floating point numbers are


                                    - 9 -
�

      Sozobon C Compiler                                 User Reference


      available  in  libf,  or  printf and scanf can be used by linking
      with the entire Alcyon runtime library.  




















































                                   - 10 -
�

      Sozobon C Compiler                                 User Reference


      4. Known Shortcomings and Bugs      

      The  floating  point  code  needs more work.  Unfortunately, this
      code  isn't  much  fun to work on, and since none of us have much
      use   for   floating   point,  it  probably  won't  receive  much
      attention.   If  anyone  has  access  to a public domain floating
      point  library  (IEEE  preferred),  we'd be happy to look into it
      for a future release.  

      More  optimization  work  is needed and many error cases could be
      handled better.  


      5. Next Release Plans       

      Several items are high on the wish list for the next release.  

         * A  port  of  the  compiler  to Minix-ST is already underway.
           The  Minix  operating  system  comes  with  source  code for
           everything  except  the  C compiler, so the Sozobon compiler
           fills  a void there and already contains some features (e.g.
           bit   fields,   floating   point)  absent  in  the  Minix  C
           compiler.  

         * The  assembly  code produced by the compiler should refer to
           parameters  and  locals  symbolically.  This  will  make  it
           easier to use embedded assembly within C.  

         * Execution  profiling  is already well underway. This will be
           an  option  that  adds instrumentation to the generated code
           to  measure the number of calls made to each routine, and to
           approximate  the  amount  of  time spent in each part of the
           program.  This  can  be  extremely  useful  when  trying  to
           improve the performance of a working program.  


      6. Future Directions        

      The  compiler is quite usable and has already replaced Alcyon and
      Megamax  as  our standard development environment.  Over time, we
      plan  to move toward ANSI conformance. This is a very large task,
      impacting the runtime library as well as the compiler itself.  

      Other possible projects: 

         * Dale  Shumacher has already done some work on a debugger, so
           with  some  more  work,  that  would be a nice addition to a
           future release.  

         * A port to the Amiga.  

         * A version for the 8086.  


                                   - 11 -
�

      Sozobon C Compiler                                 User Reference


      7. Summary         

      We've  had  fun  creating  this compiler.  While we've been using
      this  software  for  a  long  time ourselves, a lot of additional
      work  went  into  making  a  release to the general public.  That
      effort  will  have  been  well-spent if it encourages more people
      like  us  to  continue  developing  software  for the ST or if it
      helps more people learn C who might not have otherwise.  

      May the source be with you...  

                          Tony Andrews 
                          Johann Ruegg 
                          Joe Treat 








































                                   - 12 -
�

      Sozobon C Compiler                                 User Reference


      8. Command References        


      8.1 cc         

      C Compiler driver program 

      8.1.1 Synopsis            


           cc [ options ] file [ file ... ]


      8.1.2 Description            

      The  cc  command  runs  the  passes  of the compiler as needed to
      process  files  given  on the command line. Various options exist
      to control the execution of cc or the compiler passes it runs.  

      Cc recognizes file names with the following suffixes: 

            .c     C source file
            .s     Assembly language input
            .o     Relocatable object module
            .lib   Library module (.a is also recognized)

      Normally,  cc  tries  to form an executable image using the files
      given  on  the  command  line.  C  source  files are compiled and
      assembled;  assembly  language files are passed to the assembler,
      and  the  resulting  object  modules  are  linked  with any other
      object  files  or  libraries given to form an executable program.
      The  name  of the executable is based on the first file name seen
      on  the command line.  If the first file name was "foobar.c", the
      executable would be named "foobar.ttp".  

      The  following options to the cc command may be used to alter the
      default operation just described: 

           -c 
                Supress  the link phase. Leave generated object modules
                around.  

           -O 
                Run  the  assembly  optimizer  between the compiler and
                assembler.  

           -S 
                Compile  C  source  files leaving the assembly language
                output in the corresponding ".s" file.  

           -Ipath 
                Include  'path'  in  the  list  of  directories  to  be


                                   - 13 -
�

      Sozobon C Compiler                                 User Reference


                searched for header files (e.g. "-I\usr\include").  

           -Dname 
           -Dname=value 
                Define  the  pre-processor macro 'name'. If no value is
                given the macro is defined as 1.  

           -Uname 
                Un-define  one  of  the  built-in macros. For a list of
                the built-in macros, see the 'hcc' reference section.  

           -o file 
                Put the generated executable in the named file.  

           -f 
                Include the floating point library when linking.  

           -m 
                Generate a load map during the link phase.  

           -t 
                Put a symbol table in the generated program.  

           -v 
                Show  the  passes  as  they are being executed, and the
                version of 'cc'.  

           -n 
                Like -v, but don't really execute anything.  

           -p 
                This  option  enables  runtime execution profiling. The
                compiler  generates  some  additional code to count the
                number  of  calls  to  each  function.  Also, different
                startup  code  and  runtime  libraries  are  used. This
                option  isn't  fully  supported yet. It's presence here
                will  allow  us to upgrade to support profiling without
                having to replace 'cc' and 'hcc'.  

      8.1.3 Files            

      Cc  assumes  that header files, libraries, and executables can be
      found in the following locations: 

                                   Primary location        Alternate
                   -------------------------------------------------
                   header files    \sozobon\include        \include
                   libraries       \sozobon\lib            \lib
                   executables     \sozobon\bin            \bin





                                   - 14 -
�

      Sozobon C Compiler                                 User Reference



      In  addition  to  the  above  locations,  cc also checks the root
      directory   of   the   current  drive  as  well  as  the  current
      directory.  

      If  you're running a command line interpreter like 'gulam' or the
      Beckemeyer   C  Shell,  environment  variables  can  be  used  to
      override  the  default  locations  listed  above.  The  variables
      "INCLUDE",   "LIB",   and  "PATH"  may  contain  lists  of  paths
      separated  by  commas  or  semicolons.  The  given  paths will be
      searched,  in  order,  instead of the primary and alternate paths
      shown above.  










































                                   - 15 -
�

      Sozobon C Compiler                                 User Reference


      8.2 hcc         

      Hans' C compiler 

      8.2.1 Synopsis            


           hcc [ options ] file [ file ... ]


      8.2.2 Description            

      The  hcc  command  accepts  C source files and generates assembly
      language   output   to   the   corresponding   ".s"   files.  The
      pre-processor  and all phases of the compiler are included within
      this program.  

      The following options are accepted by hcc: 

           -Ipath 
                Include  'path'  in  the  list  of  directories  to  be
                searched for header files (e.g. "-I\usr\include").  

           -Dname 
           -Dname=value 
                Define  the  pre-processor macro 'name'. If no value is
                given the macro is defined as 1.  

           -Uname 
                Un-define one of the built-in macros.  

           -V 
                Display version information.  

           -P 
                Instructs  the  compiler  to generate modified function
                entry  code that will count the number of calls to each
                function.   This  is  not  fully  implemented,  but  is
                provided  for  compatibility  with  a future release of
                the compiler.  

      Directories  listed  in  the  "INCLUDE"  environment variable are
      added  to  the  list  of  standard  locations to check for header
      files.  

      Several  macros  are  normally  pre-defined.  These are: MC68000,
      mc68000, SOZOBON, ATARI_ST, and (as applicable) TOS or MINIX.  







                                   - 16 -
�

      Sozobon C Compiler                                 User Reference


      8.3 top         

      Tony's optimizer.  

      8.3.1 Synopsis            


           top [ -vpbfd ] infile [ outfile ]


      8.3.2 Description            

      Top  is  an assembly-code optimizer designed for use with hcc. It
      accepts  as  input,  the  code  generated by hcc and generates an
      optimized form of the assembly as output.  

      If  'outfile'  is  given,  the  optimized  code is written to the
      named  file.   If  no  output  file is listed, the optimized code
      replaces  the original code in the input file. Using the name "-"
      for  the output file causes the output to be sent directly to the
      screen.  

      The  optimizer is normally run by the cc command, but accepts the
      following options when run manually: 

           -v 
                Display  statistics  about  optimizations  made  on the
                file, and the version information for 'top'.  

           -p 
                Disable peephole optimizations.  

           -b 
                Disable conditional branch reversals.  

           -f 
                Disable    data-flow   analysis   (live-dead   register
                analysis) and any optimizations depending on it.  

           -d 
                Print detailed debugging information to stderr.  

      The  optimizer  performs  branch  optimization  as a minimum. The
      options  above  can  be  used  to  disable  everything  else. The
      optimizer  will  sometimes  reverse  the  sense  of a conditional
      branch  to  produce  shorter  code;  this  is  disabled by the -b
      options.  

      Data-flow  analysis  determines  which  machine registers contain
      useful  data  at  any  point  in  the code. This is used by other
      parts  of  the optimizer, but is also a likely source of bugs. It
      can be disabled with -f.  


                                   - 17 -
�

      Sozobon C Compiler                                 User Reference



      Peephole  optimizations  are  performed by looking at from one to
      three  instructions  at a time to see if a better sequence can be
      used.  Optimizations of this kind are disabled with -p.  

      If  a bug is found in the optimizer, the options -bfp can be used
      together  to eliminate more advanced features while still gaining
      the  benefit  of  the  more  reliable  (and  quite useful) branch
      optimizer.  













































                                   - 18 -
�

      Sozobon C Compiler                                 User Reference


      8.4 jas         

      Joe's assembler.  

      8.4.1 Synopsis            


           jas [ -NVlu ] [ -s dir ] [ -Ln ] [ -o file ] file


      8.4.2 Description            

      The  jas  assembler is designed for compatibility with the Alcyon
      assembler.   It   doesn't  provide  many  features  the  assembly
      language  programmer  might want, but is intended more for use by
      a  compiler  front-end.  Jas generally produces smaller code than
      the  Alcyon  assembler  because  it  is  smarter about generating
      short  branch  instructions.   Also,  jas uses no temporary files
      and runs quite a bit faster than Alcyon.  

      Some  of  the command line options are accepted for compatibility
      with  the  Alcyon  assembler,  but  are  actually  ignored.   The
      following command line options are supported: 

           -N 
                Don't generate 'short' branch instructions.  

           -V 
                Print a version message.  

           -l 
           -u 
           -s dir 
                Ignored.  

           -Ln 
                By  default,  no local symbols are placed in the symbol
                table  of  the output. This option instructs jas to put
                all  symbols  into  the  symbol  table  if  n  is  2 or
                greater.  If  the  option '-L1' is given, symbols whose
                name  doesn't  start with 'L' are written to the symbol
                table.  

           -o file 
                Be  default,  the  assembler  replaces  the  '.s'  file
                extension  of the input file with '.o' to form the name
                of  the  output.   This option can be used to write the
                output to any file.  






                                   - 19 -
�

      Sozobon C Compiler                                 User Reference


      8.5 ld         

      Loader 

      8.5.1 Synopsis            


           ld [ -mvnbp ] [ -f file ] [ -o output ] [ -u symbol ] ... file ...


      8.5.2 Description            

      The  ld  command  links  object  modules and libraries to form an
      executable  program.   Both  object  modules and libraries may be
      passed  to  ld  for linking.  Several options may be specified to
      alter the operation of the loader: 

           -m 
                Generate a load map 

           -t 
                Put a symbol table in the output file.  

           -p 
                Make  multiple  passes  over each library until no more
                references  can  be satisfied. If libraries are ordered
                appropriately,  this  option  is not needed and linking
                will be faster.  

           -b 
                This  option can be used when linking large programs to
                reduce  the  amount  of  memory used by the loader. The
                loader  makes  more  disk  accesses when this option is
                used.  

           -f file 
                This  option  is  useful  when  many  files  are  to be
                linked.  The loader reads the file name specified for a
                list  of  object  modules  and  libraries to be linked.
                Names  in  the  file should be separated by white space
                or newlines.  

           -o file 
                By  default, the name of the executable file created is
                based  on  the  first  file  name  given on the command
                line.  An  initial file name of "foobar.o" would result
                in  a program named "foobar.ttp".  This option allows a
                different name to be specified.  

           -u symbol 
                The  given  symbol  is marked as undefined. This can be
                useful  when  linking  from  libraries.  A symbol (e.g.


                                   - 20 -
�

      Sozobon C Compiler                                 User Reference


                _main)  can  be  marked  as  undefined to force loading
                from the library.  

           -v 
                Tells  the  loader to be verbose about what it's doing,
                and print version information.  
















































                                   - 21 -
�

      Sozobon C Compiler                                 User Reference


      8.6 size         

      Prints program sizes 

      8.6.1 Synopsis            


           size [ -oxV ] file ...


      8.6.2 Description            

      The  size command examines object modules or libraries and prints
      information  about  their  size.  By default, for each module (or
      member  of  a  library),  the  size  of  the  text, data, and bss
      sections  are printed in decimal.  The 'o' and 'x' options can be
      used  to  print  the  sizes in octal or hexadecimal respectively.
      If  the  'V'  option  is  given,  the version number of 'size' is
      printed.  



































                                   - 22 -
�

      Sozobon C Compiler                                 User Reference


      8.7 nm         

      Prints symbol tables 

      8.7.1 Synopsis            


           nm [ -g ] file ...


      8.7.2 Description            

      The  nm  command  dumps  the  symbol  table  of all object files,
      libraries  or  executables given on the command line.  If the 'g'
      option  is  given,  only  information  about  global  symbols  is
      printed.  






































                                   - 23 -
�

      Sozobon C Compiler                                 User Reference


      8.8 ar         

      Archive management program 

      8.8.1 Synopsis            


           ar -{drqtpmx}[vcV] afile [ file ... ]


      8.8.2 Description            

      The  ar  command  is used to maintain object module libraries. It
      can  perform  one  of  seven  basic  operations  as selected by a
      command  character.  The operation of the selected command can be
      modified by other option characters that may follow it.  

      The  name  of  the  archive  to be manipulated follows the option
      characters.  Some  commands  also require (or allow) the names of
      files  in  the  archive to follow the archive name on the command
      line.  The following commands are supported.  

           d 
                Delete the named files from the archive.  

           r 
                Replace  the  named files in the archive. New files are
                placed at the end of the archive.  

           q 
                Quickly  append  the  named  files  to  the  end of the
                archive.  

           t 
                Print  the  contents  of the archive. If file names are
                given, only show those files.  

           p 
                Print the named files to the standard output.  

           m 
                Move the named files to the end of the archive.  

           x 
                Extract  the named files from the archive, or all files
                if none were listed on the command line.  

      The  following  characters  modify  the operation of the commands
      described above.  

           v 
                Generally  show  more  information  about  what  ar  is


                                   - 24 -
�

      Sozobon C Compiler                                 User Reference


                doing.   In a table of contents, show information about
                the size, mode, etc.  

           c 
                Suppress  the  message  normally  printed  when  a  new
                archive is created.  

           V 
                Prints version information.  













































                                   - 25 -
�

      Sozobon C Compiler                                 User Reference


      8.9 globs         

      Remove non-global symbols 

      8.9.1 Synopsis            


           globs file ...


      8.9.2 Description            

      The  named  files (object modules or libraries) are compressed by
      removing  non-essential  symbols  from their symbol table.  Since
      the  Sozobon  assembler  does  this  by  default, this program it
      mostly useful to users with old Alcyon libraries.  

      This is no longer included with release 2.0.




































                                   - 26 -
�

      


                              Table of Contents


         1. Introduction        .................................    1

            1.1 System Overview       ...........................    1
               1.1.1 History        .............................    1
               1.1.2 Distribution        ........................    2
               1.1.3 Obtaining the Source Code     ..............    2
               1.1.4 Performance        .........................    3

            1.2 Acknowledgements        .........................    3

            1.3 Support        ..................................    3

         2. Development Environment       .......................    4

            2.1 Environment Variables       .....................    4

            2.2 Machine Dependencies       ......................    5

            2.3 Compiler Limits       ...........................    5

            2.4 Relationship to the Alcyon Compiler    ..........    6

         3. Component Overviews       ...........................    6

            3.1 Compiler        .................................    6

            3.2 Optimizer        ................................    7

            3.3 Assembler        ................................    8

            3.4 Linker        ...................................    8

            3.5 Utilities        ................................    8

            3.6 Library        ..................................    9
               3.6.1 Startup Code       .........................    9
               3.6.2 C Runtime Library      .....................    9
               3.6.3 Floating Point Library      ................    9

         4. Known Shortcomings and Bugs     .....................   11

         5. Next Release Plans      .............................   11

         6. Future Directions       .............................   11

         7. Summary        ......................................   12

         8. Command References       ............................   13



                                    - I -
�

      


            8.1 cc        .......................................   13
               8.1.1 Synopsis        ............................   13
               8.1.2 Description        .........................   13
               8.1.3 Files        ...............................   14

            8.2 hcc        ......................................   16
               8.2.1 Synopsis        ............................   16
               8.2.2 Description        .........................   16

            8.3 top        ......................................   17
               8.3.1 Synopsis        ............................   17
               8.3.2 Description        .........................   17

            8.4 jas        ......................................   19
               8.4.1 Synopsis        ............................   19
               8.4.2 Description        .........................   19

            8.5 ld        .......................................   20
               8.5.1 Synopsis        ............................   20
               8.5.2 Description        .........................   20

            8.6 size        .....................................   22
               8.6.1 Synopsis        ............................   22
               8.6.2 Description        .........................   22

            8.7 nm        .......................................   23
               8.7.1 Synopsis        ............................   23
               8.7.2 Description        .........................   23

            8.8 ar        .......................................   24
               8.8.1 Synopsis        ............................   24
               8.8.2 Description        .........................   24

            8.9 globs        ....................................   26
               8.9.1 Synopsis        ............................   26
               8.9.2 Description        .........................   26


















                                   - II -





Back to C