Invoking the Pre-Scheme compiler
================================

Richard Kelsey's Pre-Scheme compiler is a whole-program compiler based on techniques from his research in transformational compilation [Kelsey 89].  It compiles the restricted dialect of Scheme to efficient C, and provides facilities for programmer direction in several optimizations.

Loading the compiler
--------------------

There is a script, a Scheme48 Command programs, command program, that comes with Scheme48 to load the Pre-Scheme compiler, which is in the file ps-compiler/load-ps-compiler.scm.  It must be loaded from the ps-compiler/ directory, from Scheme48's main distribution, into the exec package, after having loaded ../scheme/prescheme/interface.scm & ../scheme/prescheme/package-defs.scm into the config package.  The Pre-Scheme compiler takes some time to load, so it may be easier to load it once and dump a heap image of the suspended command processor after having loaded everything; see Image-building commands.

To load the Pre-Scheme compiler and dump an image to the file ps-compiler.image that contains prescheme-compiler in the user package, send this sequence of commands to the command processor while in the ps-compiler/ directory of Scheme48's distribution:

     ,config ,load ../scheme/prescheme/interface.scm
     ,config ,load ../scheme/prescheme/package-defs.scm
     ,exec ,load load-ps-compiler.scm
     ,in prescheme-compiler prescheme-compiler
     ,user (define prescheme-compiler ##)
     ,dump ps-compiler.image "(Pre-Scheme)" lisp

Calling the compiler
--------------------

After having loaded the Pre-Scheme compiler, the prescheme-compiler structure is the front end to the compiler that exports the prescheme-compiler procedure.

 -- procedure: prescheme-compiler structure-spec config-filenames init-name c-filename command ...
     Invokes the Pre-Scheme compiler.  CONFIG-FILENAMES contain module descriptions (see Module system) for the components of the program. STRUCTURE-SPEC may be a symbol or a list of symbols, naming the important structure or structures.  All structures that it relies/they rely on are traced in the packages' open clauses.  Modules that are not traced in the dependency graph with root vertices of the given structure[s] are omitted from the output.  C-FILENAME is a string naming the file to which the C code generated by the Pre-Scheme compiler should be emitted.  INIT-NAME is the name for an initialization routine, generated automatically by the Pre-Scheme compiler to initialize some top-level variables.  The COMMAND arguments are used to control certain aspects of the compilation.  The following commands are defined:

     (copy (STRUCTURE COPYABLE-PROCEDURE) ...)
          Specifies that each the body of each COPYABLE-PROCEDURE from the respective STRUCTURE (from one of CONFIG-FILENAMES) may be integrated & duplicated.

     (no-copy (STRUCTURE UNCOPYABLE-PROCEDURE) ...)
          Specifies that the given procedures may not be integrated.

     (shadow ((PROC-STRUCTURE PROCEDURE) (VAR-STRUCTURE VARIABLE-TO-SHADOW) ...) ...)
          Specifies that, in PROCEDURE from PROC-STRUCTURE, the global variables VARIABLE-TO-SHADOW from their respective VAR-STRUCTUREs should be shadowed with local variables, which are more likely to be kept in registers for faster operation on them.

     (integrate (CLIENT-PROCEDURE INTEGRABLE-PROCEDURE) ...)
          Forces INTEGRABLE-PROCEDURE to be integrated in CLIENT-PROCEDURE.

          Note: The integrate command operates on the global program, not on one particular module; each CLIENT-PROCEDURE and INTEGRABLE-PROCEDURE is chosen from all variables defined in the entirety of the program, across all modules.  It is advised that there be only one of each.

     (header HEADER-LINE ...)
          Each HEADER-LINE is added to the top of the generated C file, after a cpp inclusion of <stdio.h> and "prescheme.h".

     The command arguments to prescheme-compiler are optional; they are used only to optimize the compiled program at the programmer's request.