s48-refman/prescheme/compiler.texi

@node Invoking the Pre-Scheme compiler
@section 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.

@subsection Loading the compiler

There is a script, a Scheme48 @embedref{Command programs, command
program}, that comes with Scheme48 to load the Pre-Scheme compiler,
which is in the file @file{ps-compiler/load-ps-compiler.scm}.  It must
be loaded from the @file{ps-compiler/} directory, from Scheme48's main
distribution, into the @code{exec} package, after having loaded
@file{../scheme/prescheme/interface.scm} &
@file{../scheme/prescheme/package-defs.scm} into the @code{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; @pxref{Image-building
commands}.

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

@lisp
,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)"@end lisp

@subsection Calling the compiler

@stindex prescheme-compiler
After having loaded the Pre-Scheme compiler, the
@code{prescheme-compiler} structure is the front end to the compiler
that exports the @code{prescheme-compiler} procedure.

@deffn procedure prescheme-compiler structure-spec config-filenames init-name c-filename command @dots{}
Invokes the Pre-Scheme compiler.  @var{Config-filenames} contain module
descriptions (@pxref{Module system}) for the components of the program.
@var{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' @code{open} clauses.  Modules that
are not traced in the dependency graph with root vertices of the given
structure[s] are omitted from the output.  @var{C-filename} is a string
naming the file to which the C code generated by the Pre-Scheme
compiler should be emitted.  @var{Init-name} is the name for an
initialization routine, generated automatically by the Pre-Scheme
compiler to initialize some top-level variables.  The @var{command}
arguments are used to control certain aspects of the compilation.  The
following commands are defined:

@table @code
@item (copy (@var{structure} @var{copyable-procedure}) @dots{})
Specifies that each the body of each @var{copyable-procedure} from the
respective @var{structure} (from one of @var{config-filenames}) may be
integrated & duplicated.

@item (no-copy (@var{structure} @var{uncopyable-procedure}) @dots{})
Specifies that the given procedures may not be integrated.

@item (shadow ((@var{proc-structure} @var{procedure}) (@var{var-structure} @var{variable-to-shadow}) @dots{}) @dots{})
Specifies that, in @var{procedure} from @var{proc-structure}, the
global variables @var{variable-to-shadow} from their respective
@var{var-structure}s should be shadowed with local variables, which
are more likely to be kept in registers for faster operation on them.

@item (integrate (@var{client-procedure} @var{integrable-procedure}) @dots{})
Forces @var{integrable-procedure} to be integrated in
@var{client-procedure}.

@strong{Note:} The @code{integrate} command operates on the global
program, not on one particular module; each @var{client-procedure} and
@var{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.

@item (header @var{header-line} @dots{})
Each @var{header-line} is added to the top of the generated C file,
after a cpp inclusion of @code{<stdio.h>} and @code{"prescheme.h"}.
@end table

The command arguments to @code{prescheme-compiler} are optional; they
are used only to optimize the compiled program at the programmer's
request.
@end deffn