mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

manual: reorganize autoconf, pkg-config info

Browse source 
* doc/ref/libguile-parallel.texi: New file, documenting parallel
  installation and the use of pkg-config.

* doc/ref/libguile-linking.texi: Adapt.

* doc/ref/libguile-autoconf.texi: Rename from autoconf.texi.  Lower
  sections, and integrate in the "Programming in C" chapter.

* doc/ref/guile.texi: Adapt.
This commit is contained in:
Andy Wingo 2011-10-12 13:07:30 +02:00
parent b09179d0eb
commit d32df1325d
4 changed files with 77 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

9
doc/ref/guile.texi
View file

@ -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

44
doc/ref/autoconf.texi → doc/ref/libguile-autoconf.texi
View file

@ -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,

24
doc/ref/libguile-linking.texi
View file

@ -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.
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}:
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.
@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.

48
doc/ref/libguile-parallel.texi Normal file
View file

@ -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: