6.18.7 Load Paths

The procedure in the previous section look for Scheme code in the file
system at specific location. Guile also has some procedures to search
the load path for code.

Variable: %load-path

List of directories which should be searched for Scheme modules and
libraries. When Guile starts up, %load-path is initialized to
the default load path (list (%library-dir) (%site-dir)
(%global-site-dir) (%package-data-dir)). The GUILE_LOAD_PATH
environment variable can be used to prepend or append additional
directories (see Environment Variables).

Search %load-path for the file named filename and
load it into the top-level environment. If filename is a
relative pathname and is not found in the list of search paths,
an error is signalled. Preferentially loads a compiled version of the
file, if it is available and up-to-date.

If filename is a relative pathname and is not found in the list of
search paths, one of three things may happen, depending on the optional
second argument, exception-on-not-found. If it is #f,
#f will be returned. If it is a procedure, it will be called
with no arguments. (This allows a distinction to be made between
exceptions raised by loading a file, and exceptions related to the
loader itself.) Otherwise an error is signalled.

For compatibility with Guile 1.8 and earlier, the C function takes only
one argument, which can be either a string (the file name) or an
argument list.

Scheme Procedure: %search-load-pathfilename

C Function: scm_sys_search_load_path(filename)

Search %load-path for the file named filename, which must
be readable by the current user. If filename is found in the list
of paths to search or is an absolute pathname, return its full pathname.
Otherwise, return #f. Filenames may have any of the optional
extensions in the %load-extensions list; %search-load-path
will try each extension automatically.

Variable: %load-extensions

A list of default file extensions for files containing Scheme code.
%search-load-path tries each of these extensions when looking for
a file to load. By default, %load-extensions is bound to the
list ("" ".scm").

As mentioned above, when Guile searches the %load-path for a
source file, it will also search the %load-compiled-path for a
corresponding compiled file. If the compiled file is as new or newer
than the source file, it will be loaded instead of the source file,
using load-compiled.

Variable: %load-compiled-path

Like %load-path, but for compiled files. By default, this path
has two entries: one for compiled files from Guile itself, and one for
site packages. The GUILE_LOAD_COMPILED_PATH environment variable
can be used to prepend or append additional directories
(see Environment Variables).

When primitive-load-path searches the %load-compiled-path
for a corresponding compiled file for a relative path it does so by
appending .go to the relative path. For example, searching for
ice-9/popen could find
/usr/lib/guile/3.0/ccache/ice-9/popen.go, and use it instead of
/usr/share/guile/3.0/ice-9/popen.scm.

If primitive-load-path does not find a corresponding .go
file in the %load-compiled-path, or the .go file is out of
date, it will search for a corresponding auto-compiled file in the
fallback path, possibly creating one if one does not exist.

Finally, there are a couple of helper procedures for general path
manipulation.

Scheme Procedure: parse-pathpath [tail]

C Function: scm_parse_path(path, tail)

Parse path, which is expected to be a colon-separated string, into
a list and return the resulting list with tail appended. If
path is #f, tail is returned.

Scheme Procedure: parse-path-with-ellipsispath base

C Function: scm_parse_path_with_ellipsis(path, base)

Parse path, which is expected to be a colon-separated string, into
a list and return the resulting list with base (a list) spliced in
place of the ... path component, if present, or else base
is added to the end. If path is #f, base is
returned.

Search path for a directory containing a file named
filename. The file must be readable, and not a directory. If we
find one, return its full filename; otherwise, return #f. If
filename is absolute, return it unchanged. If given,
extensions is a list of strings; for each directory in path,
we search for filename concatenated with each extension. If
require-exts? is true, require that the returned file name have
one of the given extensions; if require-exts? is not given, it
defaults to #f.

For compatibility with Guile 1.8 and earlier, the C function takes only
three arguments.