* Guile Implementation::
-* Autoconf Support::
-
Appendices
* GNU Free Documentation License:: The license of this manual.
@xref{API Reference}.
@menu
+* Parallel Installations:: Finding the right Guile.
* Linking Programs With Guile:: More precisely, with the libguile library.
* Linking Guile with Libraries:: To extend Guile itself.
* General Libguile Concepts:: General concepts for using libguile.
* Defining New Types (Smobs):: Adding new types to Guile.
* Function Snarfing:: A way to define new functions.
* Programming Overview:: An overview of Guile programming.
+* Autoconf Support:: Putting m4 to good use.
@end menu
+@include libguile-parallel.texi
@include libguile-linking.texi
@include libguile-extensions.texi
@include libguile-concepts.texi
@include libguile-smobs.texi
@include libguile-snarf.texi
@include libguile-program.texi
+@include libguile-autoconf.texi
+
@node API Reference
@chapter API Reference
@include vm.texi
@include compiler.texi
-@include autoconf.texi
-
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@page
@node Autoconf Support
-@chapter Autoconf Support
+@section Autoconf Support
-When Guile is installed, a pkg-config description file and a set of
-Autoconf macros is installed. This chapter documents pkg-config and
-Autoconf support, as well as the high-level guile-tool Autofrisk.
+Autoconf, a part of the GNU build system, makes it easy for users to
+build your package. This section documents Guile's Autoconf support.
@menu
* Autoconf Background:: Why use autoconf?
@node Autoconf Background
-@section Autoconf Background
+@subsection Autoconf Background
As explained in the @cite{GNU Autoconf Manual}, any package needs
configuration at build-time (@pxref{Top, ,Introduction,autoconf,The GNU
@node Autoconf Macros
-@section Autoconf Macros
+@subsection Autoconf Macros
-@cindex pkg-config
-@cindex autoconf
-
-GNU Guile provides a @dfn{pkg-config} description file, which contains
-all the information necessary to compile and link C applications that
-use Guile. The @code{pkg-config} program is able to read this file
-and provide this information to application programmers; it can be
-obtained at @url{http://pkg-config.freedesktop.org/}.
-
-The following command lines give respectively the C compilation and link
-flags needed to build Guile-using programs:
-
-@example
-pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
-pkg-config guile-@value{EFFECTIVE-VERSION} --libs
-@end example
-
-To ease use of pkg-config with Autoconf, pkg-config comes with a
-convenient Autoconf macro. The following example looks for Guile and
-sets the @code{GUILE_CFLAGS} and @code{GUILE_LIBS} variables
-accordingly, or prints an error and exits if Guile was not found:
+As mentioned earlier in this chapter, Guile supports parallel
+installation, and uses @code{pkg-config} to let the user choose which
+version of Guile they are interested in. @code{pkg-config} has its own
+set of Autoconf macros that are probably installed on most every
+development system. The most useful of these macros is
+@code{PKG_CHECK_MODULES}.
@findex PKG_CHECK_MODULES
PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
@end example
+This example looks for Guile and sets the @code{GUILE_CFLAGS} and
+@code{GUILE_LIBS} variables accordingly, or prints an error and exits if
+Guile was not found.
+
Guile comes with additional Autoconf macros providing more information,
installed as @file{@var{prefix}/share/aclocal/guile.m4}. Their names
all begin with @code{GUILE_}.
@node Using Autoconf Macros
-@section Using Autoconf Macros
+@subsection Using Autoconf Macros
Using the autoconf macros is straightforward: Add the macro "calls" (actually
instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
manual. Once you've compiled your source files, you need to link them
against the Guile object code library, @code{libguile}.
-@code{<libguile.h>} is not in the default search path for headers,
-because Guile supports parallel installation of multiple versions of
-Guile, with each version's headers under their own directories. This is
-to allow development against, say, both Guile 2.0 and 2.2.
-
-To compile code that includes @code{<libguile.h>}, or links to
-@code{libguile}, you need to select the effective version you are
-interested in, and then ask @code{pkg-config} for the compilation flags
-or linking instructions. For effective version
-@value{EFFECTIVE-VERSION}, for example, you would invoke
-@code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}} to get
-the compilation and linking flags necessary to link to version
-@value{EFFECTIVE-VERSION} of Guile. You would typically run
-@code{pkg-config} during the configuration phase of your program and
-use the obtained information in the Makefile.
-
-See the @code{pkg-config} man page, for more information.
+As noted in the previous section, @code{<libguile.h>} is not in the
+default search path for headers. The following command lines give
+respectively the C compilation and link flags needed to build programs
+using Guile @value{EFFECTIVE-VERSION}:
+
+@example
+pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
+pkg-config guile-@value{EFFECTIVE-VERSION} --libs
+@end example
@menu
* Guile Initialization Functions:: What to call first.
--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Parallel Installations
+@section Parallel Installations
+
+@cindex pkg-config
+@cindex effective version
+
+Guile provides strong API and ABI stability guarantees during stable
+series, so that if a user writes a program against Guile version 2.0.3,
+it will be compatible with some future version 2.0.7. We say in this
+case that 2.0 is the @dfn{effective version}, composed of the major and
+minor versions, in this case 2 and 0.
+
+Users may install multiple effective versions of Guile, with each
+version's headers, libraries, and Scheme files under their own
+directories. This provides the necessary stability guarantee for users,
+while also allowing Guile developers to evolve the language and its
+implementation.
+
+However, parallel installability does have a down-side, in that users
+need to know which version of Guile to ask for, when they build against
+Guile. Guile solves this problem by installing a file to be read by the
+@code{pkg-config} utility, a tool to query installed packages by name.
+Guile encodes the version into its pkg-config name, so that users can
+ask for @code{guile-2.0} or @code{guile-2.2}, as appropriate.
+
+For effective version @value{EFFECTIVE-VERSION}, for example, you would
+invoke @code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}}
+to get the compilation and linking flags necessary to link to version
+@value{EFFECTIVE-VERSION} of Guile. You would typically run
+@code{pkg-config} during the configuration phase of your program and use
+the obtained information in the Makefile.
+
+See the @code{pkg-config} man page, for more information, or its web
+site, @url{http://pkg-config.freedesktop.org/}.
+
+@xref{Autoconf Support}, for more on checking for Guile from within a
+@code{configure.ac} file.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / commitdiff