home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / utils / gambit_c.lha / Gambit_Comp / compiler.doc < prev    next >
Text File  |  1992-11-21  |  8KB  |  223 lines
  1. FILE:        "compiler.doc"
  2. IMPLEMENTS:    Description of how to use the compiler.
  3. AUTHOR:        Ken Dickey
  4. DATE:        1992 August 1
  5. LAST UPDATED:     1992 August 2
  6.  
  7.  
  8. NOTES:
  9.  
  10. To save space, the compiler has not been built as a stand-alone
  11. program.  Use GSI (the Gambit Scheme Interpreter):
  12.  
  13.  
  14. >> gsi -- -h4000 -c1000
  15.  
  16. Gambit v1.8
  17.  
  18. : (load "SCM:loadcompiler")  ;; assumes you have assigned SCM:
  19.  
  20. : (compile "foo" 'verbose 'pvm 'report)  ;; compiles "foo.scm" to "foo.O"
  21.  
  22.  
  23. Compile files as shown below.  
  24.  
  25. There are 2 major memory areas: the heap and the constant space.  The
  26. constant space is where code is loaded--it is not garbage collected at
  27. this time.  The heap holds all live data.  In this release (1.8), a
  28. stop-and-copy or hemispherical collector is used.  This means that the
  29. live data can fill up to 1/2 of the heap.  To use the compiler, you
  30. must tell gsi to save extra space for the compiled code (see
  31. "gsi.man").  Use as large a heap as you can afford.  I use "gsi --
  32. -h4000 -c1000" which allocates 2 2MB semi-spaces for the heap and 1MB
  33. for the interpreter & compiler code.  If you don't allocate enough
  34. space, the system will tell you when, e.g. you run out of constant
  35. space when trying to load the compiler. 
  36.  
  37.  
  38. USAGE SYNOPSIS: (compile <filename-string> . <optional-options>)
  39.  
  40.  
  41. ; (compile "tak")              -- compile 'tak.scm' for M68000 target
  42. ; (compile "tak" 'VERBOSE)     -- produce compiler trace
  43. ; (compile "tak" 'REPORT)      -- show usage of global variables
  44. ; (compile "tak" 'PVM)         -- write PVM code on 'tak.pvm'
  45. ; (compile "tak" 'DEBUG)       -- generate code with debugging info
  46. ; (compile "tak" 'EXPANSION)   -- show code after source-to-source transform
  47. ; (compile "tak" 'ASM)         -- write asm code to file 'tak.asm'
  48.  
  49.  
  50. SAMPLE USAGE:
  51.  
  52. : (compile "sets" 'asm 'pvm 'report)  
  53.                 ;; report output to stdout as follows
  54. Global variable usage:
  55.  
  56.  STANDARD
  57.   [   C] car
  58.   [   C] cdr
  59.   [   C] cons
  60.   [   C] eq?
  61.   [  R ] for-each
  62.   [   C] list
  63.   [   C] memq
  64.   [   C] null?
  65.  
  66.  OTHERS
  67.   [D   ] list->set
  68.   [D  C] n-ary
  69.   [D   ] set->list
  70.   [D   ] set-adjoin
  71.   [D   ] set-choose
  72.   [D   ] set-difference
  73.   [D   ] set-empty
  74.   [D   ] set-empty?
  75.   [D  C] set-equal?
  76.   [D  C] set-every?
  77.   [D   ] set-foreach
  78.   [D   ] set-intersection
  79.   [D  C] set-keep
  80.   [D  C] set-map
  81.   [D   ] set-member?
  82.   [D  C] set-remove
  83.   [D   ] set-singleton
  84.   [D   ] set-union
  85.  
  86.   [DARC] =>
  87.    Defined
  88.     Assigned to
  89.      Referenced
  90.       Called
  91.  
  92.  
  93. SAMPLE SIZES
  94.  
  95. ; sets.scm                2745  -- source
  96. ; sets.O                  4898  -- loadfile
  97. ; sets.pvm               55119  -- symbolic instructions for PVM
  98. ; sets.asm              118447  -- assembly listing
  99.  
  100.  
  101. COMPILER OPTIONS:
  102.  
  103. There are a number of options you can add to your code to enhance
  104. speed and space performance.  From Marc's man page:
  105.  
  106.  
  107.      NON-STANDARD SPECIAL FORMS
  108.           In addition to the standard Scheme special forms, the
  109.           compiler accepts the following forms which can appear
  110.           anywhere a define special form can appear:
  111.  
  112.           (##declare decl...)
  113.                             See below for the list of accepted
  114.                             declarations.  The scope of the
  115.                             declaration extends to the end of the body
  116.                             it is in or to the end of the program if
  117.                             it is at toplevel.
  118.  
  119.           (##include "prog.scm")
  120.                             Read the expressions contained in the
  121.                             given file and splice them into the
  122.                             program.
  123.  
  124.           (##define-macro (name parm...) body)
  125.                             Define the name as a macro special form
  126.                             which expands into body.  The scope of the
  127.                             declaration extends to the end of the body
  128.                             it is in or to the end of the program if
  129.                             it is at toplevel (unless it is redefined
  130.                             before).
  131.  
  132.      DECLARATIONS
  133.           The following declarations are accepted by the compiler:
  134.  
  135.           (dialect)         Use the given dialect's semantics.
  136.                             Dialect can be: ieee-scheme, r4rs-scheme
  137.                             or multilisp.
  138.  
  139.           ([not] lambda-lift)
  140.                             Lambda-lift (or don't lambda-lift)
  141.                             procedures.
  142.  
  143.           (strategy)        Select block compilation or separate
  144.                             compilation.  In block compilation, the
  145.                             compiler can assume that all references to
  146.                             the global variables defined in the
  147.                             current program are located in the program
  148.                             itself.  Strategy can be: block or
  149.                             separate.
  150.  
  151.           ([not] standard-bindings var...)
  152.                             The given global variables are known (or
  153.                             not known) to be equal to the value
  154.                             defined for them in the dialect (all
  155.                             variables defined in the standard if none
  156.                             specified).
  157.  
  158.           ([not] extended-bindings var...)
  159.                             The given global variables are known (or
  160.                             not known) to be equal to the value
  161.                             defined for them in the runtime system
  162.                             (all variables defined in the runtime if
  163.                             none specified).
  164.  
  165.           ([not] safe)      Generate (or don't generate) code that
  166.                             will prevent fatal runtime errors.  Note
  167.                             that in `safe' mode certain semantic
  168.                             errors will not be checked as long as they
  169.                             can't crash the system.  For example the
  170.                             primitive `char=?' could disregard the
  171.                             type of its arguments in `safe' (as well
  172.                             as `not safe') mode.
  173.  
  174.           ([not] intr-checks)
  175.                             Generate (or don't generate) interrupt
  176.                             checks.  Interrupt checks are used to
  177.                             signal the need for a garbage collection
  178.                             on a multiprocessor system, to catch user
  179.                             interrupts and also to check for stack
  180.                             overflows.  Interrupt checking should not
  181.                             be turned off casually.
  182.  
  183.           (futures method)  Use the given method to implement futures.
  184.                             Method can be: off (future = identity),
  185.                             delay (future = delay), eager (create a
  186.                             task for the body of every future), lazy
  187.                             (create a task for a future's continuation
  188.                             only when it must be moved to another
  189.                             processor), and eager-inline (like eager
  190.                             when there are no tasks waiting on the
  191.                             processor, otherwise like identity).
  192.  
  193.           (number-type prim...)
  194.                             Numeric arguments and result of specified
  195.                             primitives are known to be of the given
  196.                             type (all primitives if none specified).
  197.                             Number-type can be: generic or fixnum.
  198.  
  199.      DEFAULT DECLARATION
  200.           The default declarations used by the compiler are:
  201.  
  202.                (ieee-scheme)
  203.                (lambda-lift)
  204.                (separate)
  205.                (not standard-bindings)
  206.                (not extended-bindings)
  207.                (not safe)
  208.                (intr-checks)
  209.                (futures lazy)
  210.                (generic)
  211.  
  212.           These declarations are compatible with the ieee-scheme
  213.           standard.  Typically used declarations that enhance
  214.           performance (at the cost of violating the ieee-scheme
  215.           standard) are: (standard-bindings) and (fixnum).
  216.  
  217.      DIAGNOSTICS
  218.           The diagnostic messages produced by gsc are printed on the
  219.           standard output file.
  220.  
  221.  
  222. ;;               --- E O F ---
  223.