6.17.5 Compiling Scheme Code

The eval procedure directly interprets the S-expression representation of Scheme. An alternate strategy for evaluation is to determine ahead of time what computations will be necessary to evaluate the expression, and then use that recipe to produce the desired results. This is known as compilation.

While it is possible to compile simple Scheme expressions such as (+ 2 2) or even "Hello world!", compilation is most interesting in the context of procedures. Compiling a lambda expression produces a compiled procedure, which is just like a normal procedure except typically much faster, because it can bypass the generic interpreter.

Functions from system modules in a Guile installation are normally compiled already, so they load and run quickly.

Note that well-written Scheme programs will not typically call the procedures in this section, for the same reason that it is often bad taste to use eval. By default, Guile automatically compiles any files it encounters that have not been compiled yet (see section --auto-compile). The compiler can also be invoked explicitly from the shell as guild compile foo.scm.

(Why are calls to eval and compile usually in bad taste? Because they are limited, in that they can only really make sense for top-level expressions. Also, most needs for “compile-time” computation are fulfilled by macros and closures. Of course one good counterexample is the REPL itself, or any code that reads expressions from a port.)

Automatic compilation generally works transparently, without any need for user intervention. However Guile does not yet do proper dependency tracking, so that if file ‘a.scm’ uses macros from ‘b.scm’, and b.scm changes, a.scm would not be automatically recompiled. To forcibly invalidate the auto-compilation cache, pass the --fresh-auto-compile option to Guile, or set the GUILE_AUTO_COMPILE environment variable to fresh (instead of to 0 or 1).

For more information on the compiler itself, see Compiling to the Virtual Machine. For information on the virtual machine, see A Virtual Machine for Guile.

The command-line interface to Guile’s compiler is the guild compile command:

Command: guild compile [‘option’...] file...

Compile file, a source file, and store bytecode in the compilation cache or in the file specified by the ‘-o’ option. The following options are available:

‘-L dir’

‘--load-path=dir’

Add dir to the front of the module load path.

‘-o ofile’

‘--output=ofile’

Write output bytecode to ofile. By convention, bytecode file names end in .go. When ‘-o’ is omitted, the output file name is as for compile-file (see below).

‘-W warning’

‘--warn=warning’

Emit warnings of type warning; use --warn=help for a list of available warnings and their description. Currently recognized warnings include unused-variable, unused-toplevel, unbound-variable, arity-mismatch, format, duplicate-case-datum, and bad-case-datum.

‘-f lang’

‘--from=lang’

Use lang as the source language of file. If this option is omitted, scheme is assumed.

‘-t lang’

‘--to=lang’

Use lang as the target language of file. If this option is omitted, objcode is assumed.

‘-T target’

‘--target=target’

Produce bytecode for target instead of %host-type (see section %host-type). Target must be a valid GNU triplet, such as armv5tel-unknown-linux-gnueabi (see Specifying Target Triplets in GNU Autoconf Manual).

Each file is assumed to be UTF-8-encoded, unless it contains a coding declaration as recognized by file-encoding (see section Character Encoding of Source Files).

The compiler can also be invoked directly by Scheme code using the procedures below:

Scheme Procedure: compile exp [#:env=#f] [#:from=(current-language)] [#:to=value] [#:opts=()]

Compile the expression exp in the environment env. If exp is a procedure, the result will be a compiled procedure; otherwise compile is mostly equivalent to eval.

For a discussion of languages and compiler options, See section Compiling to the Virtual Machine.

Scheme Procedure: compile-file file [#:output-file=#f] [#:from=(current-language)] [#:to='objcode] [#:env=(default-environment from)] [#:opts='()] [#:canonicalization='relative]

Compile the file named file.

Output will be written to a output-file. If you do not supply an output file name, output is written to a file in the cache directory, as computed by (compiled-file-name file).

from and to specify the source and target languages. See section Compiling to the Virtual Machine, for more information on these options, and on env and opts.

As with guild compile, file is assumed to be UTF-8-encoded unless it contains a coding declaration.

Scheme Procedure: compiled-file-name file

Compute a cached location for a compiled version of a Scheme file named file.

This file will usually be below the ‘$HOME/.cache/guile/ccache’ directory, depending on the value of the XDG_CACHE_HOME environment variable. The intention is that compiled-file-name provides a fallback location for caching auto-compiled files. If you want to place a compile file in the %load-compiled-path, you should pass the output-file option to compile-file, explicitly.

Scheme Variable: %auto-compilation-options

This variable contains the options passed to the compile-file procedure when auto-compiling source files. By default, it enables useful compilation warnings. It can be customized from ‘~/.guile’.

This document was generated on April 20, 2013 using texi2html 5.0.