bug#7995: [PATCH 1/4] Documentation for Guile support.

[Ralf Wildenhues]

* doc/automake.texi (Guile): New chapter.
(Top, Other GNU Tools): Update menus.
* NEWS: Update.
Initial suggestion and lots of ideas and from Andy Wingo and
Ludovic Courtè.
---
 ChangeLog         |    9 +++
 NEWS              |    5 ++
 doc/automake.texi |  154 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 167 insertions(+), 1 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 12b8e9f..c338e8a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2011-02-20  Ralf Wildenhues  <address@hidden>
+
+       Documentation for Guile support.
+       * doc/automake.texi (Guile): New chapter.
+       (Top, Other GNU Tools): Update menus.
+       * NEWS: Update.
+       Initial suggestion and lots of ideas and from Andy Wingo and
+       Ludovic Courtès.
+
 2011-02-16  Stefano Lattarini  <address@hidden>
            Ralf Wildenhues  <address@hidden>
 
diff --git a/NEWS b/NEWS
index a5dc93f..401d69b 100644
--- a/NEWS
+++ b/NEWS
@@ -11,6 +11,11 @@ New in 1.11a:
 
   - New `cscope' target to build a cscope database for the source tree.
 
+* Languages changes:
+
+  - Support for compilation and installation of Guile source code and compiled
+    Guile source code via the new `GUILE' primary.
+
 * Miscellaneous changes:
 
   - The `dist' and `dist-all' targets now can run compressors in parallel.
diff --git a/doc/automake.texi b/doc/automake.texi
index 474f5a1..078dfbb 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -291,6 +291,7 @@ Top
 * Libtool::                     Libtool
 * Java::                        Java
 * Python::                      Python
+* Guile::                       Guile
 
 Building documentation
 
@@ -2073,7 +2074,7 @@ Uniform
 objects are not installed either.
 
 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
address@hidden, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
address@hidden, @samp{LISP}, @samp{PYTHON}, @samp{GUILE}, @samp{JAVA},
 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
 @samp{TEXINFOS}.
 @vindex PROGRAMS
@@ -2081,6 +2082,7 @@ Uniform
 @vindex LTLIBRARIES
 @vindex LISP
 @vindex PYTHON
address@hidden GUILE
 @vindex JAVA
 @vindex SCRIPTS
 @vindex DATA
@@ -7446,6 +7448,7 @@ Other GNU Tools
 * Libtool::                     Libtool
 * Java::                        Java
 * Python::                      Python
+* Guile::                       Guile
 @end menu
 
 
@@ -7736,6 +7739,155 @@ Python
 Install Paths}.
 
 
address@hidden Guile
address@hidden Guile
+
address@hidden @code{_GUILE} primary, defined
address@hidden @code{GUILE} primary, defined
address@hidden Primary variable, @code{GUILE}
address@hidden _GUILE
+
+Automake provides support for compiled Guile source files with the
address@hidden primary as well as for installation of extensions modules
+for Guile in a compiled language such as C.  A typical setup is to call
address@hidden in @file{configure.ac} and use a line like the
+following in @file{Makefile.am}:
+
address@hidden
+guile_GUILE = foo.scm bar.sls baz.sps zork.ss
address@hidden example
+
+Here's a longer example with different types of file handling:
+
address@hidden
+guile_GUILE = compiled-and-installed.scm
+nodist_guile_GUILE = not-distributed.scm
+guile_DATA = not-compiled.scm
+noinst_GUILE = compiled-but-not-installed.scm
+dist_noinst_DATA = just-distributed-blob.scm
+
+# object files will be installed in respective subdir of guileexecdir.
+nobase_guile_GUILE = installed-in-subdir/foo.scm
+
+pkgguile_GUILE = installed-in-package-dir.scm
address@hidden example
+
+Here's an example of a typical extension module written in C:
+
address@hidden
+guileext_LTLIBRARIES = foo.la
+foo_la_SOURCES = foo.c
+foo_la_LDFLAGS = -module -avoid-version
+foo_la_LIBADD = $(GUILELIBS)
+AM_CFLAGS = $(GUILECFLAGS)
+AM_CPPFLAGS = $(GUILECPPFLAGS)
address@hidden example
+
+When @samp{AM_PATH_GUILE} is used, the suffixes @file{.scm}, @file{.sls},
address@hidden, and @file{.ss} are assumed to be Guile sources, and
+compiled files will carry the @file{.go} extension.
+
+Any files listed in a @code{_GUILE} variable will be byte-compiled
+with @command{guile-tools compile} if that is available and new enough
+to compile Guile sources.
+
+Automake ships with an Autoconf macro called @code{AM_PATH_GUILE}
+that will determine some Guile-related directory variables (see
+below).  If you have called @code{AM_PATH_GUILE} from
address@hidden, then you may use the variables
address@hidden or @code{pkgguile_GUILE} to list Guile source
+files in your @file{Makefile.am}, depending on where you want your files
+installed (see the definitions of @code{guiledir} and
address@hidden below).
+
address@hidden AM_PATH_GUILE (@ovar{version}, @ovar{action-if-found}, @
+  @ovar{action-if-not-found})
+
+Search for a Guile compiler @samp{guile-tools compile} on the system.
+This macro takes three optional arguments.  The first argument, if
+present, is the minimum version of Guile required for this package:
address@hidden will skip any Guile interpreter that is older than
address@hidden  If an interpreter is found and satisfies @var{version},
+then @var{action-if-found} is run.  Otherwise, @var{action-if-not-found}
+is run.  Without a @var{version} argument, a minimum version of 1.8 is
+checked against.
+
+If @var{action-if-not-found} is not specified, as in the following
+example, the default is to abort @command{configure}.
+
address@hidden
+AM_PATH_GUILE([2.0])
address@hidden example
+
address@hidden
+This is fine when Guile is an absolute requirement for the package.
+If Guile >= 2.0 was only @emph{optional} to the package,
address@hidden could be called as follows.
+
address@hidden
+AM_PATH_GUILE([2.0],, [:])
address@hidden example
+
address@hidden creates the following output variables based on
+the Guile installation found during configuration.
address@hidden defmac
+
address@hidden @code
address@hidden GUILE_TOOLS
+The name of the @command{guile-tools} executable, or @samp{:} if no
+suitable compiler could be found.
+
+Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
+will abort if Guile is absent), the value of @code{GUILE} can be used
+to setup a conditional in order to disable the relevant part of a build
+as follows.
+
address@hidden
+AM_PATH_GUILE(,, [:])
+AM_CONDITIONAL([HAVE_GUILE], [test "$GUILE_TOOLS" != :])
address@hidden example
+
address@hidden GUILE_VERSION
+The Guile version number, in the form @address@hidden
+(e.g., @samp{1.8}).
+
address@hidden guiledir
+The directory name for the installation of user Guile source code.
+By default, that is @samp{$(datarootdir)/guile/site/@var{x.y}} for
+Guile versions @var{x.y} greater than 1.8, and
address@hidden(datarootdir)/guile/site} for version 1.8.
+
address@hidden pkgguiledir
+This is the directory under @code{guiledir} that is named after the
+package.  That is, it is @samp{$(guiledir)/$(PACKAGE)}.  It is provided
+as a convenience.
+
address@hidden guileexecdir
+This is the directory where compiled Guile source code will be installed.
+The default is @samp{$(libdir)/guile/@var{x.y}/ccache} if a Guile Scheme
+compiler is available, and @samp{$(libdir)} otherwise.
+
address@hidden guileextdir
+This is the directory where Guile C extensions will be installed.
+The default is @samp{$(libdir)/guile/@var{x.y}/extensions} for versions
address@hidden greater than 1.8, and @samp{$(libdir)} otherwise.
+
address@hidden @example
address@hidden XXX
address@hidden @end example
address@hidden vtable
+
+All these directory variables have values that start with either
address@hidden@address@hidden or @address@hidden@}} unexpanded.  This works
+fine in @file{Makefiles}, but it makes these variables hard to use in
address@hidden  This is mandated by the GNU coding standards, so
+that the user can run @samp{make prefix=/foo install}.  The Autoconf
+manual has a section with more details on this topic
+(@pxref{Installation Directory Variables, , Installation Directory
+Variables, autoconf, The Autoconf Manual}).  See also @ref{Hard-Coded
+Install Paths}.
+
+
 @node Documentation
 @chapter Building documentation
 
-- 
1.7.4.1.48.g5673d