6.21.4 Modules and Extensions

The new primitives that you add to Guile with scm_c_define_gsubr (see Primitive Procedures) or with any of the other mechanisms are placed into the module that is current when the scm_c_define_gsubr is executed. Extensions loaded from the REPL, for example, will be placed into the (guile-user) module, if the REPL module was not changed.

To define C primitives within a specific module, the simplest way is:

(define-module (foo bar))
(load-extension "foobar-c-code" "foo_bar_init")

When loaded with (use-modules (foo bar)), the load-extension call looks for the foobar-c-code.so (etc) object file in Guile’s extensiondir, which is usually a subdirectory of the libdir. For example, if your libdir is /usr/lib, the extensiondir for the Guile 3.0.x series will be /usr/lib/guile/3.0/.

The extension path includes the major and minor version of Guile (the “effective version”), because Guile guarantees compatibility within a given effective version. This allows you to install different versions of the same extension for different versions of Guile.

If the extension is not found in the extensiondir, Guile will also search the standard system locations, such as /usr/lib or /usr/local/lib. It is preferable, however, to keep your extension out of the system library path, to prevent unintended interference with other dynamically-linked C libraries.

If someone installs your module to a non-standard location then the object file won’t be found. You can address this by inserting the install location in the foo/bar.scm file. This is convenient for the user and also guarantees the intended object is read, even if stray older or newer versions are in the loader’s path.

The usual way to specify an install location is with a prefix at the configure stage, for instance ‘./configure prefix=/opt’ results in library files as say /opt/lib/foobar-c-code.so. When using Autoconf (see Introduction in The GNU Autoconf Manual), the library location is in a libdir variable. Its value is intended to be expanded by make, and can by substituted into a source file like foo.scm.in

(define-module (foo bar))
(load-extension "XXextensiondirXX/foobar-c-code" "foo_bar_init")

with the following in a Makefile, using sed (see Introduction in SED, A Stream Editor),

foo.scm: foo.scm.in
        sed 's|XXextensiondirXX|$(libdir)/guile/3.0|' <foo.scm.in >foo.scm

The actual pattern XXextensiondirXX is arbitrary, it’s only something which doesn’t otherwise occur. If several modules need the value, it can be easier to create one foo/config.scm with a define of the extensiondir location, and use that as required.

(define-module (foo config))
(define-public foo-config-extensiondir "XXextensiondirXX"")

Such a file might have other locations too, for instance a data directory for auxiliary files, or localedir if the module has its own gettext message catalogue (see Internationalization).

It will be noted all of the above requires that the Scheme code to be found in %load-path (see Load Paths). Presently it’s left up to the system administrator or each user to augment that path when installing Guile modules in non-default locations. But having reached the Scheme code, that code should take care of hitting any of its own private files etc.