diff options
-rw-r--r-- | doc/ref/guile.texi | 9 | ||||
-rw-r--r-- | doc/ref/libguile-autoconf.texi (renamed from doc/ref/autoconf.texi) | 44 | ||||
-rw-r--r-- | doc/ref/libguile-linking.texi | 26 | ||||
-rw-r--r-- | doc/ref/libguile-parallel.texi | 48 |
4 files changed, 78 insertions, 49 deletions
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 9581f0c05..e293325c6 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -182,8 +182,6 @@ x * Guile Implementation:: -* Autoconf Support:: - Appendices * GNU Free Documentation License:: The license of this manual. @@ -264,20 +262,25 @@ etc. that make up Guile's application programming interface (API), @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 @@ -426,8 +429,6 @@ merely familiar with Scheme to being a real hacker. @include vm.texi @include compiler.texi -@include autoconf.texi - @node GNU Free Documentation License @appendix GNU Free Documentation License diff --git a/doc/ref/autoconf.texi b/doc/ref/libguile-autoconf.texi index 675c9d6b7..b4a9f409d 100644 --- a/doc/ref/autoconf.texi +++ b/doc/ref/libguile-autoconf.texi @@ -6,11 +6,10 @@ @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? @@ -20,7 +19,7 @@ Autoconf support, as well as the high-level guile-tool Autofrisk. @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 @@ -42,29 +41,14 @@ checks. @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 @@ -72,6 +56,10 @@ accordingly, or prints an error and exits if Guile was not found: 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_}. @@ -81,7 +69,7 @@ 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, diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi index 3a90208be..de9076800 100644 --- a/doc/ref/libguile-linking.texi +++ b/doc/ref/libguile-linking.texi @@ -16,23 +16,15 @@ head of any C source file that uses identifiers described in this 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. diff --git a/doc/ref/libguile-parallel.texi b/doc/ref/libguile-parallel.texi new file mode 100644 index 000000000..09c60f545 --- /dev/null +++ b/doc/ref/libguile-parallel.texi @@ -0,0 +1,48 @@ +@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: |