31.5 Finding Guile Modules

All Guile modules have a unique module name, which is a list of one or more symbols. Examples are (ice-9 popen) or (srfi srfi-11). This section describes the three methods by which a module name is mapped onto a filename, when they are applicable and how to select between them. Of course, once a module is found, it needs to be loaded (see Loading Guile Modules), and hopefully used by the client (see Using Guile Modules).

We use the module name (g n u) for all examples.

31.5.1 Venerable

The first method (let us call it venerable-find for its historical precedence) is actually a sequence of searches, one for each load type.

• statically linked compiled-code module search

  The module name (g n u) is sought in an internal list.

• dynamically linked compiled-code module search

  Relative filenames g/n/u.so, g/n/libu.la and g/n/libu.so (in that order) are sought under the directories named in %load-path.

• scheme code search

  Relative filenames g/n/u.scm and g/n/u are sought under the directories named in %load-path.

The advantage of venerable-find is that no additional state is necessary to implement the search. The disadvantage is that the hierarchy in the module name may be inconvenient to replicate in the filesystem (e.g., within a package's differently-organized build tree for purposes of testing a module before installation).

Versions of guile for which (feature? 'module-catalogs) evaluates to #f by default use venerable-find; there is no other choice.

31.5.2 Directory-Based Module Catalog

In the second method for finding modules, Guile consults a module catalog named .module-catalog in each of the directories in %load-path, if that file exists. A module catalog is an alist whose keys are module names. The associated data indicates the load type and filename, and possibly some type-specific auxiliary information. The catalog is cached in memory and refreshed only if it changes on the filesystem. If this second method fails, Guile falls back to venerable-find.

The advantage of directory-based module catalog find is that it avoids most of the runtime complexity of venerable-find, speeding up the search for common cases, while maintaining %load-path ordering semantics. Probably more importantly, the actual placement of the file in the filesystem is decoupled from its module name. The disadvantage is that the catalog must be maintained for those directories in %load-path. This can be mitigated somewhat by using proper tools, however (see guile-tools make-module-catalog).

Versions of guile for which (feature? 'module-catalogs) evaluates to #t by default use directory-based module catalog find. See below for instructions on disabling this method.

31.5.3 Merged Module Catalog

The third method for finding modules is a refinement of the second. In this method, only one module catalog file is specified. If this method fails, Guile falls back to venerable-find.

If environment variable GUILE_MERGED_MODULE_CATALOG is set, Guile takes its value to name a merged module catalog file. A value of 0 (zero), however, means to never use this method; use directory-based module catalog instead.

See guile-tools merge-module-catalogs.

31.5.4 Disabling module catalog searching

You can disable directory-based module catalog find (merged or not) with the disable-module-catalogs! procedure (see Module Monkey).