7. Compiling files and libraries

This chapter explains how you can use Larceny to compile Scheme source code to native machine code.

The native varieties of Larceny have a just-in-time compiler that compiles to native code automatically whenever you evaluate an expression, load a source file, or import a source library. Even so, files will load faster if they are compiled ahead of time.

Petit Larceny does not have a just-in-time compiler, so compiling ahead of time is the only way to enjoy the speed of native machine code in Petit Larceny.

The main disadvantage of compiling files and libraries is that compiled code goes stale when its original source code is changed or when a library on which the compiled code depends is changed or recompiled. Stale compiled code can be dangerously inconsistent with libraries on which it depends, so Larceny checks for staleness and refuses to execute a stale library or program.

7.1. Compiling R7RS/R6RS libraries

On Unix machines, the most convenient way to compile a group of R7RS/R6RS libraries and top-level programs is to use the compile-stale script in Larceny's root directory. If Larceny's root directory is in your execution path, then there are just two steps:

  1. Use cd to change to the directory that contains the R7RS/R6RS files you want to compile. (Files that lie within subdirectories of that directory will be compiled also.)
  2. Run the compile-stale script.

For example:

    % cd lib/R7RS
    % compile-stale

On non-Unix machines, you can accomplish the same thing using Larceny's R7RS mode and the (larceny compiler) library:

    % pushd lib\R7RS
    % ..\..\larceny -r7rs
    Larceny v0.98 "General Ripper"

    > (import (larceny compiler))

    > (compile-stale-libraries)

To compile individual files, use the compile-file or compile-library procedures that are exported by (larceny compiler).

7.2. Compiling R5RS source files

Procedure compile-file

(compile-file sourcefile)

Compiles sourcefile, which must be a string naming a file that contains R5RS source code. If faslfile is supplied as a second argument, then it must be a string naming the file that will contain the compiled code; otherwise the name of the compiled file is obtained from sourcefile by replacing the ".sch" or ".scm" suffix with ".fasl".

For R7RS/R6RS libraries and top-level programs, see above.

7.3. Loading compiled R5RS files into an R7RS session

When a file is compiled, the compiler must make assumptions about the meanings of its free identifiers.

When R5RS code is compiled, Larceny's compiler assumes all free identifiers refer to the flat global naming environment prescribed by the R5RS standard.

When an R7RS/R6RS library or top-level program is compiled, Larceny's compiler assumes all free identifiers refer to identifiers imported from other libraries. That assumption is checked at both compile time and at run time. At compile time, the compiler refuses to compile a library if one or more of its free identifiers is not imported. The compiler also records the current versions of all imported libraries, so Larceny's import mechanism can check at run time to make sure all of the imported libraries are still consistent with the libraries imported at compile time.

The facts stated above imply compiled R5RS code can only be loaded into the flat global environment provided by Larceny's underlying R5RS layer, and compiled R7RS/R6RS code can only be imported by or loaded into an R7RS/R6RS program or interactive session.

R5RS source code can be loaded into an interactive R7RS session, but it will be loaded as though it were R7RS code rather than R5RS code. That means loading R5RS source code into an interactive R7RS session behaves differently from loading compiled R5RS code into an interactive R7RS session.

When compiled R5RS code is loaded into an interactive R7RS session, it is loaded into Larceny's underlying R5RS layer. The procedures it defines can then be imported into the R7RS session using Larceny's primitives extension to import syntax.

When R5RS source code is loaded into an interactive R7RS session, however, it will behave as though the source code had been typed interactively.