6.18.11 Local Inclusion

This section has discussed various means of linking Scheme code together: fundamentally, loading up files at run-time using load and load-compiled. Guile provides another option to compose parts of programs together at expansion-time instead of at run-time.

Scheme Syntax: include file-name

Open file-name, at expansion-time, and read the Scheme forms that it contains, splicing them into the location of the include, within a begin.

If file-name is a relative path, it is searched for relative to the path that contains the file that the include form appears in.

If you are a C programmer, if load in Scheme is like dlopen in C, consider include to be like the C preprocessor’s #include. When you use include, it is as if the contents of the included file were typed in instead of the include form.

Because the code is included at compile-time, it is available to the macroexpander. Syntax definitions in the included file are available to later code in the form in which the include appears, without the need for eval-when. (See Eval When.)

For the same reason, compiling a form that uses include results in one compilation unit, composed of multiple files. Loading the compiled file is one stat operation for the compilation unit, instead of 2*n in the case of load (once for each loaded source file, and once each corresponding compiled file, in the best case).

Unlike load, include also works within nested lexical contexts. It so happens that the optimizer works best within a lexical context, because all of the uses of bindings in a lexical context are visible, so composing files by including them within a (let () ...) can sometimes lead to important speed improvements.

On the other hand, include does have all the disadvantages of early binding: once the code with the include is compiled, no change to the included file is reflected in the future behavior of the including form.

Also, the particular form of include, which requires an absolute path, or a path relative to the current directory at compile-time, is not very amenable to compiling the source in one place, but then installing the source to another place. For this reason, Guile provides another form, include-from-path, which looks for the source file to include within a load path.

Scheme Syntax: include-from-path file-name

Like include, but instead of expecting file-name to be an absolute file name, it is expected to be a relative path to search in the %load-path.

include-from-path is more useful when you want to install all of the source files for a package (as you should!). It makes it possible to evaluate an installed file from source, instead of relying on the .go file being up to date.