
The Compiler
============

To use the compiler within a Scheme program, require _compile.ss_:
  (require-library "compile.ss" "compiler")
The compile.ss library defines the following functions (plus a few
signatures).  Options that control the compiler are documented in the
next section.

 Single-file extension compilation
 ---------------------------------

>  ((compile-extensions expr) scheme-file-list dest-dir)

      `(compile-extension expr)' returns a compiler that is initialized with
      the elaboration-time expression `expr'.  The compiler takes a list
      of Scheme files and compiles each of them to an extension, placing
      the resulting extensions in the directory specified by `dest-dir'.
      If `dest-dir' is #f, each extension is placed in the same directory
      as its source file.

>  ((compile-extensions-to-c expr) scheme-file-list dest-dir)

     Like `compile-extensions', but only .c files are produced, not
     extensions.

>  (compile-c-extensions c-file-list dest-dir)

     Compiles each .c file (usually produced with `compile-extensions-to-c') 
     in c-file-list to an extension.  `dest-dir' is handled as in
     `compile-extensions'.

 Multi-file extension compilation
 ---------------------------------

>  ((compile-extension-parts expr) scheme-file-list dest-dir)

      `(compile-extension expr)' returns a compiler that is initialized with
      the elaboration-time expression `expr'.  The compiler takes a list
      of Scheme files and compiles each of them to a linkable object and
      a .kp (constant pool) file, placing the resulting objects and .kp files
      in the directory specified by `dest-dir'.  If `dest-dir' is #f, each object 
      and .kp file is placed in the same directory as its source file.
 
>  ((compile-extension-parts-to-c expr)  scheme-file-list dest-dir)

     Like `compile-extension-parts', but only .c and .kp files are produced, 
     not compiled objects.

>  (compile-c-extension-parts c-file-list dest-dir)

     Compiles each .c file (produced with `compile-extension-parts-to-c')
     in c-file-list to an extension.  `dest-dir' is handled as in
     `compile-extension-parts'.

>  (link-extension-parts obj-and-kp-file-list dest-dir)

     Links objects for a multi-object extension together, using .kp
     files to generate and link pooled constants.  The objects and
     .kp files in `obj-and-kp-file' can be in any order.  The resulting
     extension "_loader" is placed in the directory specified by `dest-dir'.

>  (glue-extension-parts obj-and-kp-file-list dest-dir)

     Like `link-extension-parts', but only a "_loader" object file
     is generated; this object file is linked with all the other
     object files to produce the "_loader" extension.

 zo compilation
 --------------

>  ((compile-zos expr) scheme-file-list dest-dir)

      `(compile-zos expr)' returns a compiler that is initialized with
      the elaboration-time expression `expr'.  The compiler takes a list
      of Scheme files and compiles each of them to a .zo file, placing
      the resulting .zo files in the directory specified by `dest-dir'.
      If `dest-dir' is #f, each .zo file is placed in the same directory
      as its source file.
 
 Collection compilation
 ----------------------

>  (compile-collection-extension collection sub-collection ...)

      Compiles the specified (sub-)collection to an extension
      "_loader", putting intermediate .c and .kp files in the
      collection's "compiled/native" directory, and object files and
      the resulting "_loader" extension in the collection's
      "compiled/native/PLATFORM" directory (where `PLATFORM' is the
      system name for the current platform).

      The collection compiler reads the collection's _info.ss_ file
      (see the mzc manual for information about info.ss) to obtain
      information about compiling the collection.  The following
      fields are used:

>      'name - the name of the collection as a string.

>      'compile-prefix - an S-expression to use as the elaboration-time
         prefix expression for compiling all files in the collection.

>      'compile-omit-files - a list of filenames (without paths); all
         Scheme files in the collection are compiled except for the
         files in this list.  If a file contains elaboration time
         expressions (e.g., macros, signatures) that are not intended
         to be local to the file, then the file should be included in
         this list.

>      'compile-extension-omit-files - a list of filenames to extend
         the list returned for `compile-omit-files'. Unlike the list
         returned for `compile-omit-files', this extension is not used
         when compiling .zo files.

>      'compile-subcollections - a list of collection paths, where each
         path is a list of strings. `compile-collection-extension' is 
         applied to each of the collections.

      Only the 'name field is required from info.ss, but the 
      'compile-prefix field should also be provided, because the
      Setup PLT uses this field as an indication that the collection 
      should be compiled (see "Setup PLT" below).

      The compilation process is driven by the 'make-collection
      function in the collection.ss library of the `make' collection.

>  (compile-collection-zos collection sub-collection ...)

      Compiles the specified (sub-)collection files to .zo files.
      The .zo files are placed into the collection's "compiled"
      directory.

      The _info.ss_ file is used as in `compile-collection-extension',
      except for `compile-extension-omit-files'. In addition, the
      following two fields are used:

>      'compile-zo-omit-files - a list of filenames to extend the
         list returned for 'compile-omit-files.

>      'compile-elaboration-zos - a list of filenames (without paths);
         the Scheme files in this list are compiled with elaborations 
         preserved (see MzLib's compile-file for information about 
         preserving elaborations). The files are compiled from left to
         right in the list, all in the same namespace. If a file does 
         not need to be compiled, it is nevertheless loaded before 
         subsequent files in the list are compiled.

>      'compile-elaboration-zos-prefix - an S-expression to use
         as an elaboration-time prefix expression for compiling
         the files returned for 'compile-elaboration-zos.

      The main compilation process is driven by the `make-collection'
      function in the collection.ss library of the `make'
      collection. The elaboration-preserving compilation does not
      use make, but it only recompiles a file when the source file
      is newer.

---------------------------------------------------------------------------

Options for the Compiler
========================

To set options for the compile.ss extension compiler, load the
libray _option.ss_.  (This library is automatically loaded by
compile.ss, but it can also be loaded earlier.) Options are set by
the following parameters:

> compiler:option:verbose - #t causes the compiler to print
     verbose messages about its operations.  Default = #f.

> compiler:option:setup-prefix - a string to embed in public names.
     This is used mainly for compiling extensions with the collection
     name so that cross-extension conflicts are less likely in
     architectures that expose the public names of loaded extensions.
     Note that `compile-collection' handles prefixing automatically
     (by setting this option).  Default = "".

> compiler:option:clean-intermediate-files - #t keeps intermediate
     .c/.o files.  Default = #f.

> compiler:option:compile-subcollections - #t uses info.ss's
     'compile-subcollections for compiling collections. Default = #t.

> compiler:option:compile-for-embedded - #t creates .c files and
     object files to be linked directly with an embedded MzScheme
     run-time system, instead of .c files and object files to
     be dynamically loaded into MzScheme as an extension.
     Default = #f.

> compiler:option:propagate-constants - #t improves the code by
     propogating constants.  Default = #t.

> compiler:option:assume-primitives - #t equates X with #%X when
     #%X exists.  This is useful only with non-unitized code.
     Default = #f.

> compiler:option:stupid - Allow obvious non-syntactic errors; e.g.:
    ((lambda () 0) 1 2 3).  Default = #f.

> compiler:option:vehicles - Controls how closures are compiled.  The
    possible values are: 'vehicles:automatic - auto-groups
                         'vehicles:functions - groups by procedue
                         'vechicles:units - groups by unit
                         'vehicles:monolithic - groups randomly
    Default = 'vehicles:automatic.

> compiler:option:vehicles:monoliths - Sets the number of random
    groups for 'vehicles:monolithic.

> compiler:option:seed - Sets the randomizer seed for
    'vehicles:monolithic.

> compiler:option:max-exprs-per-top-level-set - Sets the number of
    top-level Scheme expressions crammed into one C function.  Default
    = 25.

> compiler:option:unpack-environments - #f might help for
    register-poor architectures.  Default = #t.

> compiler:option:debug - #t creates debug.txt debugging file.  Default
    = #f.

> compiler:option:test - #t ignores top-level expressions with syntax
   errors.  Default = #f.

> compiler:option:zo-compiler-flags - a list of symbol flags for compiling
   .zo files. Default = '(strip-macro-definitions ignore-require-library).

More options are defined by the compile.ss and link.ss libraries in
the `dynext' collection . Those options control the actual C compiler
and linker that are used. See doc.txt in the `dynext' collection for
more information about those options.

The _optionr.ss_ library is a unit/sig matching the signature
>    compiler:option^
which contains these options.  (The unitized option names do not have
the `compiler:option:' prefix.) The _sig.ss_ library defines the
`compiler:option^' signature.

---------------------------------------------------------------------------

The Compiler as a Unit
======================

The _compiler.ss_ library is a unit/sig matching the signature
>      compiler^ 
which provides the compile.ss functions.  This signature and all
auxilliary signatures needed by compiler.ss are defined by the
_sig.ss_ library.

The compiler.ss signed unit requires the following imports:

   compiler:option^ - from optionr.ss or option.ss (the latter
                      uses a `compiler:option:' prefix)
   mzlib:function^
   mzlib:pretty-print^
   mzlib:file^
   mzlib:compile^
   dynext:compile^ - From the `dynext' collection
   dynext:link^
   dynext:file^

---------------------------------------------------------------------------

Low-level Extension Compiler and Linker
=======================================

The high-level compile.ss interface relies on low-level
implementations of the extension compiler and linker.  (Of course, .zo
compilation is handled by MzLib's compile.ss library.)

The _loadr.ss_ and _ldr.ss_ libraries define unit/sigs for the
low-level extension compiler and multi-file linker.  The _load.ss_
library opens these units into the current namespace with the prefix
`mzc:'.

The low-level functions are:

> (mzc:eval-compile-prefix expr) - Evaluates an elaboration-time
    S-expression `expr'.  Future calls to mzc:compile-XXX will see the
    effects of the elaboration expression.

> (mzc:compile-extension scheme-source dest-dir) - Compiles a
    single Scheme file to an extension.

> (mzc:compile-extension-to-c scheme-source dest-dir) - Compiles
    a single Scheme file to a .c file.

> (mzc:compile-c-extension c-source dest-dir) - Compiles a single .c
    file to an extension.

> (mzc:compile-extension-part scheme-source dest-dir) - Compiles a
    single Scheme file to a compiled object and .kp file toward a
    multi-file extension.

> (mzc:compile-extension-part-to-c scheme-source dest-dir) - Compiles
    a single Scheme file to .c and .kp files towards a multi-file
    extension.

> (mzc:compile-c-extension-part c-source dest-dir) - Compiles a single
    .c file to a compiled object towards a multi-file extension.

> (mzc:link-extension object-and-kp-file-list dest-dir) - Links
    compiled object and .kp files into a multi-file extension.

All but the last function are from the loadr.ss unit, and the
last one is from ldr.ss.  The loadr.ss unit/sig requires the
following imports:
   mzlib:function^
   mzlib:pretty-print^
   mzlib:file^
   dynext:compile^ - From the `dynext' collection
   dynext:link^
   dynext:file^
   compiler:option^ - from optionr.ss or option.ss (the latter
                      uses a `compiler:option:' prefix)
and the ldr.ss unit/sig requires the following imports:
   dynext:compile^ - From the `dynext' collection
   dynext:link^
   dynext:file^
   mzlib:function^
   compiler:option^ - from optionr.ss or option.ss (the latter
                      uses a `compiler:option:' prefix)

---------------------------------------------------------------------------

Embedding Scheme Code to Create a Stand-alone Executable
========================================================

The _embed.ss_ library provides a function to embed Scheme code into a
copy of MzScheme or MrEd, thus creating a (large) _stand-alone_ Scheme
executable.

> (make-embedding-executable dest-file mred? verbose? src-file-list collect-list cmdline-list)
  - Copies the MzScheme (if `mred?' is #f) or MrEd (otherwise) binary
  to `dest-file', appends the content of the files in `src-file-list',
  appends the libraries of each colelction in `collect-list', and sets the
  internal command line to read the appended code when the binary is
  executed. The `cmdline-list' contains additional command-line
  strings; '("-mvq-") should be a popular choice.

The _embedr.ss_ library provides a unit that imports nothing and
exports `make-embedding-executable'.
