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.
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.
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.