diff options
Diffstat (limited to 'doc/ref/api-modules.texi')
-rw-r--r-- | doc/ref/api-modules.texi | 59 |
1 files changed, 31 insertions, 28 deletions
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 89bb87e80..54e5f4b8f 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -1247,48 +1247,51 @@ The simplest way to write a module using compiled C code is @end example When loaded with @code{(use-modules (foo bar))}, the -@code{load-extension} call looks for the @file{foobar-c-code.so} +@code{load-extension} call looks for the @file{foobar-c-code.so} (etc) 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. +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 @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}, +results in library files as say @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. Its value is intended to be expanded by @command{make}, and +can by substituted into a source file like @file{foo.scm.in} @example (define-module (foo bar)) -(load-extension "@@libdir@@/foobar-c-code" "foo_bar_init") +(load-extension "XXlibdirXX/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}). +@noindent +with the following in a @file{Makefile}, using @command{sed} +(@pxref{Top, , Introduction, sed, SED, A Stream Editor}), + +@example +foo.scm: foo.scm.in + sed 's|XXlibdirXX|$(libdir)|' <foo.scm.in >foo.scm +@end example -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. +The actual pattern @code{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 @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@@"") +(define-public foo-config-libdir "XXlibdirXX"") @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 +Such a file might have other locations too, for instance a 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 @@ -1296,12 +1299,12 @@ 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. +It will be noted all of the above requires that the Scheme code to 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. Presently there's no convention for having a Guile version number in module C code filenames or directories. This is primarily because |