(Compiled Code Installation): New section.

doc/ref/api-modules.texi

@@ -914,6 +914,7 @@ integrates dynamically linked libraries into the module system.
 * Low level dynamic linking::   
 * Compiled Code Modules::       
 * Dynamic Linking and Compiled Code Modules::  
+* Compiled Code Installation::  
 @end menu
 
 @node Low level dynamic linking
@@ -1234,6 +1235,92 @@ well.  For example,
 @end lisp
 @end deffn
 
+
+@node Compiled Code Installation
+@subsubsection Compiled Code Installation
+
+The simplest way to write a module using compiled C code is
+
+@example
+(define-module (foo bar))
+(load-extension "foobar-c-code" "foo_bar_init")
+@end example
+
+When loaded with @code{(use-modules (foo bar))}, the
+@code{load-extension} call looks for the @file{foobar-c-code.so}
+object file in the standard system locations, such as @file{/usr/lib}
+or @file{/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 @file{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 @code{prefix}
+at the configure stage, for instance @samp{./configure prefix=/opt}
+results in library object code like @file{foobar-c-code.so} going
+under @file{/opt/lib/foobar-c-code.so}.  When using Autoconf
+(@pxref{Top, , Introduction, autoconf, The GNU Autoconf Manual}), the
+library location is in a @code{libdir} variable and it can be inserted
+automatically by writing the scheme code as a @file{bar.scm.in},
+
+@example
+(define-module (foo bar))
+(load-extension "@@libdir@@/foobar-c-code" "foo_bar_init")
+@end example
+
+The Autoconf manual describes how this is processed to make the actual
+@file{bar.scm} which is installed (@pxref{Configuration Files, ,
+Creating Configuration Files, autoconf, The GNU Autoconf Manual}).  A
+substitution can also be done explicitly in a @file{Makefile} with a
+simple @code{sed} (@pxref{Top, , Introduction, sed, SED, A Stream
+Editor}).
+
+If several modules need this, it can be easier to create one
+@file{foo/config.scm} with a define of the @code{libdir} location, and
+use that as required.
+
+@example
+(define-module (foo config))
+(define-public foo-config-libdir "@@libdir@@"")
+@end example
+
+Such a file might have other locations too, for instance a configured
+data directory for auxiliary files, or @code{localedir} if the module
+has its own @code{gettext} message catalogue
+(@pxref{Internationalization}).
+
+When installing multiple C code objects, it can be convenient to put
+them in a subdirectory of @code{libdir}, thus giving for example
+@code{/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 @code{%load-path} (@pxref{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.
+
+@subsection Other matters
+
+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 @file{/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 @code{prefix} that there's a single
+version of Guile there, and the @code{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).
+
+
 @node Variables
 @subsection Variables
 @tpindex Variables