doc libdir and C code modules

[Kevin Ryde]

I added the words below to the manual as the last subsection in
"Dynamic Libraries", to encourage packages to use libdir.  I don't
want to re-open the can of worms about versioning and stuff, this is
intended just to describe the present situation.




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' 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 file 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 object code like `foobar-c-code.so' going under
`/opt/lib/foobar-c-code.so'.  When using Autoconf (*note Introduction:
(autoconf)Top.), the library location is in a `libdir' variable and it
can be inserted automatically by writing the scheme code as a
`bar.scm.in',

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

   The Autoconf manual describes how this is processed to make the
actual `bar.scm' which is installed (*note Creating Configuration
Files: (autoconf)Configuration Files.).  A substitution can also be
done explicitly in a `Makefile' with a simple `sed' (*note
Introduction: (sed)Top. A Stream Editor).

   If several modules need this, 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 "@libdir@"")

   Such a file might have other locations too, for instance a configured
data directory for auxiliary files, or `localedir' if the module has
its own `gettext' message catalogue (*note 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
modules can be found in `%load-path' (*note 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).