5.16.4.4 Compiled Code Installation

The simplest way to write a module using compiled C code 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 the standard system locations, such as /usr/lib or /usr/local/lib.

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), 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 "XXlibdirXX/foobar-c-code" "foo_bar_init")

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

     foo.scm: foo.scm.in
             sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm

The actual pattern XXlibdirXX 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 libdir location, and use that as required.

     (define-module (foo config))
     (define-public foo-config-libdir "XXlibdirXX"")

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

When installing multiple C code objects, it can be convenient to put them in a subdirectory of libdir, thus giving for example /usr/lib/foo/some-obj.so. If the objects are only meant to be used through the module, then a subdirectory keeps them out of sight.

It will be noted all of the above requires that the Scheme code to be found in %load-path (see Build Config). 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.

Presently there's no convention for having a Guile version number in module C code filenames or directories. This is primarily because there's no established principles for two versions of Guile to be installed under the same prefix (eg. two both under /usr). Assuming upward compatibility is maintained then this should be unnecessary, and if compatibility is not maintained then it's highly likely a package will need to be revisited anyway.

The present suggestion is that modules should assume when they're installed under a particular prefix that there's a single version of Guile there, and the guile-config at build time has the necessary information about it. C code or Scheme code might adapt itself accordingly (allowing for features not available in an older version for instance).