home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1994 November / macformat-018.iso / Utility Spectacular / Developer / macgambit-20-compiler-src-p1 / README < prev    next >
Encoding:
Text File  |  1994-07-26  |  12.7 KB  |  341 lines  |  [TEXT/KAHL]
  1. MacGambit v2.0 documentation
  2. ----------------------------
  3.  
  4. MacGambit is distributed "AS IS" with NO warranties, either
  5. expressed or implied.
  6.  
  7. Bug reports should be sent to: gambit@trex.iro.umontreal.ca
  8.  
  9.  
  10. Building the MacGambit System
  11. -----------------------------
  12.  
  13. The system is distributed in two compressed auto-extracting files:
  14.  
  15.   macgambit-2.0-sources1.sea
  16.   macgambit-2.0-sources2.sea
  17.  
  18. The first file contains all you need to build the MacGambit interpreter
  19. and compiler with THINK C 5.0.  The second file contains the Scheme source
  20. files to the runtime and compiler and also the files needed to build
  21. DEC's Thomas system (a Dylan lookalike).
  22.  
  23. The first thing you should do is extract the files to your hard disk.
  24. You need about 5 megs of free disk space.  Create a folder, say "MacGambit",
  25. and put the two compressed files in it.  Then, uncompress these
  26. files by double-clicking them.
  27.  
  28. To build the MacGambit interpreter and/or compiler, you should follow the
  29. instructions in sections A and B below.  Instructions on how to add access
  30. to Toolbox (or C) procedures are given in section C below.  The compiler and
  31. linker are explained in section D and E.  Open the file "OPEN ME FIRST!" in
  32. the "Examples" folder to get more information on using the MacGambit
  33. interpreter.
  34.  
  35. Read the file "Thomas.README" in the folder "Thomas" for details on
  36. building the Thomas interpreter.
  37.  
  38.  
  39. A. Overview
  40. -----------
  41.  
  42. MacGambit is built in three steps:
  43.  
  44. 1) The file "Runtime.π.rsrc" must be created.  This file contains some
  45.    resources and the parts of the runtime written in Scheme.
  46.  
  47. 2) The file "Runtime" must be created.  This file contains all of
  48.    "Runtime.π.rsrc" plus the parts of the runtime written in C.
  49.  
  50. 3) The interpreter and compiler (or any other Scheme program) is linked
  51.    with the "Runtime" file to produce a standalone application.
  52.  
  53. Note: the first two steps can be skipped by using the prebuilt "Runtime"
  54. file that comes with the system.
  55.  
  56.  
  57. B. Building MacGambit
  58. ---------------------
  59.  
  60. STEP 1: Creating "Runtime.π.rsrc"
  61.  
  62.    Make sure you have all of the following files and folders, and that
  63.    they are all in the same folder:
  64.    - The application "MacGambit Linker"
  65.    - The folder "Runtime (.O)"
  66.    - The file "Empty Runtime.π.rsrc"
  67.    - The file "Link 'Runtime.π.rsrc'"
  68.  
  69.    Simply double click the file "Link 'Runtime.π.rsrc'".
  70.  
  71.    Note: The Scheme source files to the runtime are in the folder
  72.          "Runtime (.scm & .s)".
  73.  
  74. STEP 2: Creating "Runtime"
  75.  
  76.    Make sure you have all of the following files and folders, and that
  77.    they are all in the same folder:
  78.    - The file "Runtime.π.rsrc" created in the first step
  79.    - The THINK C 5.0 project file "Runtime.π"
  80.    - The folder "Runtime (.c & .h)"
  81.  
  82.      i) Open the project "Runtime.π" with THINK C (just double click on
  83.         "Runtime.π").
  84.  
  85.     ii) Compile the project by selecting "Make..." in the "Source" menu.
  86.  
  87.    iii) Select "Build application..." from the "Project" menu.  Use the name
  88.         "Runtime" as the application name.  The resources from the file
  89.         "Runtime.π.rsrc" will automatically be transferred to "Runtime" at
  90.         this point.
  91.  
  92. STEP 3: Building "MacGambit Interpreter" and/or "MacGambit Compiler"
  93.  
  94.    Make sure you have all of the following files and folders, and that
  95.    they are all in the same folder:
  96.    - The application "MacGambit Linker"
  97.    - The file "Runtime" created in the second step
  98.    - The file "Online Help"
  99.    - The folder "Interpreter (.O)"
  100.    - The folder "Compiler (.O)"
  101.    - The file "Link 'MacGambit Interpreter'" or "Link 'MacGambit Compiler'".
  102.  
  103.      i) If you want the online help system, duplicate the file "Online Help"
  104.         and rename it to "MacGambit Interpreter" (or "MacGambit Compiler" if
  105.         you are building the compiler).  Otherwise, make sure that there
  106.         is no file with that name in the folder.
  107.  
  108.     ii) Double click the file "Link 'MacGambit Interpreter'" (or "Link
  109.         'MacGambit Compiler'").
  110.  
  111.    iii) Note that the system is distributed with a prebuilt version of the
  112.         interpreter.  If you want the icon to appear and would like to be
  113.         able to automatically open the interpreter when you double click
  114.         ".scm" and ".O" files, you should do following:
  115.  
  116.         Using ResEdit (or similar program), you should change the creator
  117.         of "MacGambit Interpreter" to "gamI" and set the bundle bit.  Also,
  118.         you should copy the following resources from the prebuilt "MacGambit
  119.         Interpreter" into the newly created one:
  120.  
  121.             ICN#   BNDL   FREF   gamI
  122.  
  123.         Alternatively, you can put these resources once and for all
  124.         in the file "Empty Runtime.π.rsrc" before doing step 1.
  125.  
  126.  
  127. C. Adding Toolbox access to the MacGambit Interpreter
  128. -----------------------------------------------------
  129.  
  130. Access to the Toolbox (or other C procedures) can be added to the
  131. interpreter by modifying the file "ext_mac.c" in the folder "Runtime
  132. (.c & .h)".  A major problem in interfacing C and Scheme is that they do
  133. not use the same representation for data.  Also, C created data
  134. structures can not be garbage collected.  Similarly, the address of
  135. Scheme objects can change after any garbage collection (so it is not safe
  136. for C code to keep pointers to memory allocated objects and expect them
  137. to always be valid).  An example of an interface that implements some
  138. Quickdraw primitives is given in "ext_mac.c".  The Scheme file
  139. "ext_mac.scm" in the folder "Runtime (.scm & .s)" provides procedures
  140. to access these extensions, it is linked in the normal runtime.
  141.  
  142.  
  143. D. Using the MacGambit Compiler
  144. -------------------------------
  145.  
  146. The MacGambit Compiler (GSC for short) is used to compile a Scheme source
  147. program into a binary `object file' that can either be loaded by the
  148. MacGambit Interpreter or turned into a full fledged Macintosh application
  149. with the MacGambit Linker.
  150.  
  151. GSC needs at least 2.5 Megs of RAM to run.  A larger memory size is
  152. recommended to compile large Scheme programs.  If you do not have enough
  153. memory to compile a given program, split it into smaller files.  Under
  154. Multifinder, you can adjust the amount of RAM used by GSC by setting
  155. the "application suggested memory size" using the finder's "Get info..."
  156. menu.  The default is to use 2 Megs under Multifinder or the entire
  157. memory if you are using the Finder (with a system older than system7).
  158.  
  159. GSC is almost identical to the interpreter except that it has the
  160. additional procedure `compile-file' (which can also be accessed through the
  161. "Compile..." item in the Special menu).  The `compile-file' procedure takes
  162. one or more arguments.  The first argument is the name of the file to
  163. compile.  The other arguments are compilation options.  For example,
  164. the call
  165.  
  166.     (compile-file "foo" 'asm)
  167.  
  168. compiles the file "foo.scm" and produces the assembly file "foo.asm".
  169. These options are accepted by GSC:
  170.  
  171. verbose   Generate a trace of the compiler's actions on
  172.           the interaction window.
  173.  
  174. report    Produce global variable usage report on the
  175.           interaction window.  Each global variable used in
  176.           the program is listed with 4 flags that indicate if
  177.           the global variable is defined, referenced, mutated
  178.           and called.
  179.  
  180. asm       Produce the assembly language file on <source>.asm .
  181.  
  182. pvm       Produce a listing of the PVM code for the program
  183.           on <source>.pvm .
  184.  
  185. debug     Generate code that contains debugging information to aid
  186.           debugging with the interpreter.
  187.  
  188.  
  189. In addition to the standard Scheme special forms, the compiler accepts
  190. the following forms which can appear anywhere a `define' special form
  191. can appear:
  192.  
  193. (##declare <decl>...)
  194.  
  195.   See below for the list of accepted declarations.
  196.   The scope of the declaration extends to the end of the body it is in
  197.   or to the end of the program if it is at toplevel.
  198.  
  199. (##include "prog.scm")
  200.  
  201.   Read the expressions contained in the given file and splice them
  202.   into the program.
  203.  
  204. (##define-macro (name parm...) <body>)
  205.  
  206.   Define the name as a macro special form which expands into `body'.
  207.   The scope of the declaration extends to the end of the body it is in
  208.   or to the end of the program if it is at toplevel.
  209.  
  210.  
  211. The following declarations are accepted by the compiler:
  212.  
  213. (<dialect>)
  214.  
  215.   Use the given dialect's semantics.  <dialect> can be:
  216.   ieee-scheme, r4rs-scheme or multilisp.  Note that MacGambit does not
  217.   yet implement the high-level macro facility defined in R4RS Scheme.
  218.  
  219. ([not] lambda-lift)
  220.  
  221.   Lambda-lift (or don't lambda-lift) procedures.
  222.  
  223. (<strategy>)
  224.  
  225.   Select block compilation or separate compilation.  In block
  226.   compilation, the compiler can assume that all references to the
  227.   global variables defined in the current program are located in the
  228.   program itself.  <strategy> can be: block or separate.
  229.  
  230. ([not] standard-bindings <var>...)
  231.  
  232.   The given global variables are known (or not known) to be equal
  233.   to the value defined for them in the dialect (all variables defined
  234.   in the standard if none specified).
  235.  
  236. ([not] extended-bindings <var>...)
  237.  
  238.   The given global variables are known (or not known) to be equal
  239.   to the value defined for them in the runtime system (all variables
  240.   defined in the runtime if none specified).
  241.  
  242. ([not] safe)
  243.  
  244.   Generate (or don't generate) code that will prevent fatal runtime
  245.   errors.  Note that in `safe' mode certain semantic errors will not be
  246.   checked as long as they can't crash the system.  For example
  247.   the primitive `char=?' could disregard the type of its arguments in
  248.   `safe' (as well as `not safe') mode.
  249.  
  250. ([not] intr-checks)
  251.  
  252.   Generate (or don't generate) interrupt checks.  Interrupt checks are
  253.   used to signal the need for a garbage collection, to catch user
  254.   interrupts and also to check for stack overflows.  Interrupt checking
  255.   should not be turned off casually.
  256.  
  257. (<number-type> <prim>...)
  258.  
  259.   Numeric arguments and result of specified primitives are known to be
  260.   of the given type (all primitives if none specified).
  261.   <number-type> can be: generic or fixnum.
  262.  
  263.  
  264. The default declarations used by the compiler are:
  265.  
  266.   (ieee-scheme)
  267.   (lambda-lift)
  268.   (separate)
  269.   (not standard-bindings)
  270.   (not extended-bindings)
  271.   (not safe)
  272.   (intr-checks)
  273.   (generic)
  274.  
  275. These declarations are compatible with the IEEE-Scheme standard.
  276. Typically used declarations that enhance performance (at the cost of
  277. violating the IEEE-Scheme standard) are: (standard-bindings) and
  278. (fixnum).
  279.  
  280. The diagnostic messages produced by GSC are printed on the interaction
  281. window.  When the compiler detects an error, it pops up a window with
  282. the erroneous source file and highlights the location of the error.
  283.  
  284. The code generated by GSC is very efficient.  Speedups of a factor of 100
  285. over interpreted code are not uncommon.
  286.  
  287.  
  288. A useful feature of object files is that they can be run by
  289. double-clicking them.  This is essentially equivalent to starting the
  290. interpreter and loading the given object file (except that the
  291. "init.scm" file is not loaded and a read-eval-print loop is not entered).
  292.  
  293. As an example, compile the file "pi.scm" producing the object file
  294. "pi.O".  Now, quit the compiler and double-click the file "pi.O".  This
  295. will run the program.  Note that when "pi.scm" logically terminates
  296. execution, the interpreter also exits.
  297.  
  298.  
  299. E. Using the MacGambit Linker
  300. -----------------------------
  301.  
  302. The MacGambit linker is used to build a Macintosh application program
  303. from a runtime library and a certain number of object files produced by
  304. the MacGambit compiler (there is an upper limit of 64 object files).  The
  305. files to be linked can either be entered interactively or with a
  306. "link script".
  307.  
  308. Interactive use:
  309.   The MacGambit linker first prompts for the runtime library file (you
  310.   should normally use `Runtime') and then for a set of object files.  The
  311.   name of the application is the same as the name of the last object file
  312.   to be linked with its `.O' file extension stripped off.
  313.  
  314. With a "link script":
  315.   A link script is a file containing the names of the files to link (one name
  316.   per line).  The first line contains the name of the runtime library file.
  317.   The following lines name the object files.  In addition, the name of the
  318.   application can be specified by putting it at the end of the script, after
  319.   a blank line.
  320.  
  321. When the linked program is launched, the effect is similar to loading
  322. each of the object files, in sequence, in the interpreter (except that
  323. the "init.scm" file is not loaded and a read-eval-print loop is not entered
  324. (unless of course you link in the object file "mac_toplevel.O" in the folder
  325. "Interpreter (.O)"))).
  326.  
  327. Linking examples:
  328.  
  329. 1) link the library "Runtime" with the object file "pi.O" to get the
  330.    application "pi".  Note that when "pi.scm" logically terminates,
  331.    the program exits to the finder.
  332.  
  333. 2) link the library "Runtime" with the object files "queens.O" and
  334.    "mac_toplevel.O" to add the procedure "queens" to the interpreter.
  335.  
  336.  
  337. Distribution restrictions
  338. -------------------------
  339.  
  340. Read the "About MacGambit" dialog box.
  341.