[[LarcenyCompilerSection]] Compiler ~~~~~~~~ The `(larceny compiler)` library exports the `load` and `r5rs:require` procedures of `(larceny load)`, the <> procedure, the <>, <>, and <> procedures described below, and the <> procedure. These procedures can be used to compile ERR5RS/R6RS libraries and top-level programs before they are imported or executed. This is especially important for Petit Larceny, which would otherwise use an interpreter. For native Larceny, whose just-in-time compiler generates native machine code as source libraries and programs are loaded, imported, or executed, the main advantage of separate compilation is that compiled libraries and programs will load much faster than source libraries and programs. The main disadvantage of separate compilation is that compiled libraries and programs go _stale_ when their source code is changed or when a library on which they depend is changed or recompiled. Stale libraries and programs can be dangerously inconsistent with libraries on which they depend, so Larceny checks for staleness and refuses to execute a stale library or program. The <> procedure provides a convenient way to recompile stale libraries and programs. proctempl:compile-file[args="sourcefile",optarg="slfaslfile"] Compiles _sourcefile_, which must be a string naming a file that contains source code for one or more ERR5RS/R6RS libraries or a top-level program. If _slfaslfile_ 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 "`.sls`" suffix with "`.slfasl`". proc:compile-library[args="sourcefile",optarg="slfaslfile"] Compiles _sourcefile_, which must be a string naming a file that contains source code for one or more ERR5RS/R6RS libraries. Apart from its unwillingness to compile top-level programs, `compile-library` behaves the same as `compile-file` above. proc:compile-stale-libraries[args=""] proctempl:compile-stale-libraries[args="changedfile"] If no argument is supplied, then all "`.sls`" files that lie within the current directory or a subdirectory are recompiled. If _changedfile_ is supplied, then it must be a string giving the absolute pathname of a file. (In typical usage, _changedfile_ is a source file that has been modified, making it necessary to recompile all files that depend upon it.) Compiles all ERR5RS/R6RS library files that lie within the same directory as _changedfile_ or a subdirectory, and have not yet been compiled or whose compiled files are older than _changedfile_. [NOTE] ================================================================ In future versions of Larceny, `compile-stale-libraries` might compile only the source files that depend upon _changedfile_. ================================================================ proc:compiler-switches[args=""] proctempl:compiler-switches[args="mode"] If no argument is supplied, then the current settings of all compiler switches are displayed. Each of those switches is itself a parameter that is exported by the `(larceny compiler)` library. Calling any individual compiler switch with no arguments will return its current setting. Calling any individual compiler switch with an argument (usually a boolean) will change its setting to that argument. The `compiler-switches` procedure may also be called with one of the following symbols as its argument: `default` sets most compiler switches to their default settings. `fast-safe` enables all optimizations but continues to generate code to perform all run-time type and range checks that are needed for safety (in the traditional sense, not the R6RS sense). `fast-unsafe` enables all optimizations and also disables type and range checking. This setting is deprecated because it compromises safety (in the traditional sense). `slow` turns off all optimizations. `standard` sets compiler switches for maximal conformance to the R5RS and R6RS standards. [WARNING] ================================================================ The `standard` setting is deprecated because it generates very slow code (because the R5RS makes it difficult to inline standard procedures), disables most compile-time checking (because the R6RS forbids rejection of programs with obvious errors unless the R6RS classifies the errors as syntactic), and may also compromise the portability or interoperability of ERR5RS/R6RS libraries and programs (because the R6RS outlaws several extensions that Larceny uses to improve its compatibility with other implementations of the R5RS and R6RS as well as interoperability between Larceny's own R5RS and ERR5RS/R6RS modes). ================================================================ [TIP] ================================================================ Selective toggling of compiler switches is almost always better than using the `standard` setting. To improve R5RS conformance without sacrificing too much performance, set the `benchmark-mode` switch to false and set the `integrate-procedures` switch to false only when compiling files that need to be sensitive to redefinitions of standard procedures. For R6RS libraries and programs, setting the `benchmark-mode` and `global-optimization` switches to false will eliminate a couple of minor conformance issues with only a small loss of performance and without sacrificing compile-time checking or portability. ================================================================