[gnutls-dev] Guile related 'make install' failure

[Simon Josefsson]

ludo at gnu.org (Ludovic Courtès) writes:

> Sure, this would work.  By "fails by default", I meant this:
>
>   $ ./configure && make && sudo make install
>   $ guile
>   guile> (use-modules (gnutls))
>   <unnamed port>: no code for module (gnutls)
>
> Users would have to go through the manual or `README' and find out the
> right option.

They need to read some instructions anyway, the above won't work unless
the user has also added /usr/local/lib to /etc/ld.so.conf or set
LD_LIBRARY_PATH to where libguile-gnutls-v-0.so is installed.  Otherwise
you get error messages such as:

guile> (use-modules (gnutls))
...
In /usr/local/share/guile/site/gnutls.scm:
 361: 32* [load-extension "libguile-gnutls-v-0" "scm_init_gnutls"]

/usr/share/guile/site/gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"):
/usr/share/guile/site/gnutls.scm:361:1: file: "libguile-gnutls-v-0", message: "libguile-gnutls-v-0.so: cannot open shared object file: No such file or directory"
ABORT: (misc-error)
guile>

I think the few users that will be affected by this need to read up on
how to install things for their environment, in particular do one of:

1) Set %load-path, and possibly also the run-time linker search path, to
let guile know where the gnutls module is located.

2) Use --with-guile-site-dir=no during installation.

I have added a new section 'Guile Preparations' to the manual, see
below.  What do you think?

>> If the user builds with --prefix=/usr, the guile paths will be
>> correct.
>
> But `$(GUILE_SITE)' could be anything outside `/usr'.

I think the new section covers this case too.

>> I believe it is more important to not install anything outside of
>> $prefix by default.
>
> Well, we definitely have to make a compromise.  I won't fight strongly
> against having Guile code installed under `$prefix'.  Nevertheless, I
> believe that Guile users will likely be surprised to see that it
> "doesn't work out of the box".

The GnuTLS library itself needs similar "load-path" settings: the
-R/usr/local/lib or LD_LIBRARY_PATH setting for the run-time linker.
You need to install GnuTLS into /usr for the library to just "work out
of the box".  Installing it anywhere else, including the default of
/usr/local, requires that users go through extra steps to have it work.
I think this is a pretty common scenario.

> BTW, Libtool issues a message at installation-time in this sort of
> circumstance:
>
>   ----------------------------------------------------------------------
>   Libraries have been installed in:
>      /usr/local/lib
>
>   If you ever happen to want to link against installed libraries
>   in a given directory, LIBDIR, you must either use libtool, and
>   specify the full pathname of the library, or use the `-LLIBDIR'
>   flag during linking and do at least one of the following:
>      - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
>        during execution
>      - add LIBDIR to the `LD_RUN_PATH' environment variable
>        during linking
>      - use the `-Wl,--rpath -Wl,LIBDIR' linker flag
>      - have your system administrator add LIBDIR to `/etc/ld.so.conf'
>
> Maybe something similar should be done when installing Guile modules?

That could be added, although I'm not sure if anyone ever actually reads
such messages.  Still, having things documented in the manual should
provide information for users.

/Simon

diff --git a/doc/guile.texi b/doc/guile.texi
index 502671b..8d4d075 100644
--- a/doc/guile.texi
+++ b/doc/guile.texi
@@ -14,12 +14,88 @@ a large subset thereof is available.
 
 
 @menu
+* Guile Preparations::          Note on installation and environment.
 * Guile API Conventions::       Naming conventions and other idiosyncrasies.
 * Guile Examples::              Quick start.
 * Guile Reference::             The Scheme GnuTLS programming interface.
 @end menu
 
 @c *********************************************************************
+ at node Guile Preparations
+ at section Guile Preparations
+
+The GnuTLS Guile bindings are by default installed under the GnuTLS
+installation directory (e.g., typically
+ at file{/usr/local/share/guile/site/}).  Normally Guile will not find
+the module there without help.  You may experience something like
+this:
+
+ at example
+$ guile
+guile> (use-modules (gnutls))
+<unnamed port>: no code for module (gnutls)
+guile>
+ at end example
+
+There are two ways to solve this.  The first is to make sure that when
+building GnuTLS, the Guile bindings will be installed in the same
+place where Guile looks.  You may do this by using the
+ at code{--with-guile-site-dir} parameter as follows:
+
+ at example
+$ ./configure --with-guile-site-dir=no
+ at end example
+
+This will instruct GnuTLS to attempt to install the Guile bindings
+where Guile will look for them.  It will use @code{guile-config info
+pkgdatadir} to learn the path to use.
+
+If Guile was installed into @code{/usr}, you may also install GnuTLS
+using the same prefix:
+
+ at example
+$ ./configure --prefix=/usr
+ at end example
+
+If you want to specify the path to install the Guile bindings you can
+also specify the path directly:
+
+ at example
+$ ./configure --with-guile-site-dir=/opt/guile/share/guile/site
+ at end example
+
+The second solution requires some more work but may be easier to use
+if you do not have system administrator rights to your machine.  You
+need to instruct Guile so that it finds the GnuTLS Guile bindings.
+Either use the @code{GUILE_LOAD_PATH} environment variable as follows:
+
+ at example
+$ GUILE_LOAD_PATH=/usr/local/share/guile/site guile
+guile> (use-modules (gnutls))
+guile>
+ at end example
+
+If you get an error regarding @file{libguile-gnutls-v-0} similar to:
+
+ at example
+gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"):
+gnutls.scm:361:1: file: "libguile-gnutls-v-0", message: "libguile-gnutls-v-0.so: cannot open shared object file: No such file or directory"
+ at end example
+
+You will need to modify the run-time linker path, for example as
+follows.
+
+ at example
+$ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile
+guile> (use-modules (gnutls))
+guile>
+ at end example
+
+As another solution, it may be possible to modify the
+ at code{%load-path} variable.
+
+
+ at c *********************************************************************
 @node Guile API Conventions
 @section Guile API Conventions