diff options
-rw-r--r-- | doc/ref/api-modules.texi | 93 |
1 files changed, 90 insertions, 3 deletions
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 91e70f39f..3c8d0377e 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -911,9 +911,10 @@ dynamic linking apparatus, and a more high-level interface that integrates dynamically linked libraries into the module system. @menu -* Low level dynamic linking:: -* Compiled Code Modules:: -* Dynamic Linking and Compiled Code Modules:: +* 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 |