summaryrefslogtreecommitdiff
path: root/doc/ref/libguile-linking.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/libguile-linking.texi')
-rw-r--r--doc/ref/libguile-linking.texi77
1 files changed, 45 insertions, 32 deletions
diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi
index b6a88556e..3a90208be 100644
--- a/doc/ref/libguile-linking.texi
+++ b/doc/ref/libguile-linking.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010
+@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.
@@ -16,16 +16,24 @@ 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}.
-On most systems, you should not need to tell the compiler and linker
-explicitly where they can find @file{libguile.h} and @file{libguile}.
-When Guile has been installed in a peculiar way, or when you are on a
-peculiar system, things might not be so easy and you might need to pass
-additional @code{-I} or @code{-L} options to the compiler. Guile
-provides the utility program @code{guile-config} to help you find the
-right values for these options. You would typically run
-@code{guile-config} during the configuration phase of your program and
+@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.
+
@menu
* Guile Initialization Functions:: What to call first.
* A Sample Guile Main Program:: Sources and makefiles.
@@ -98,17 +106,17 @@ ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
process the command-line arguments in the usual way.
Here is a Makefile which you can use to compile the above program. It
-uses @code{guile-config} to learn about the necessary compiler and
+uses @code{pkg-config} to learn about the necessary compiler and
linker flags.
@example
# Use GCC, if you have it installed.
CC=gcc
# Tell the C compiler where to find <libguile.h>
-CFLAGS=`guile-config compile`
+CFLAGS=`pkg-config --cflags guile-@value{EFFECTIVE-VERSION}`
# Tell the linker what libraries to use and where to find them.
-LIBS=`guile-config link`
+LIBS=`pkg-config --libs guile-@value{EFFECTIVE-VERSION}`
simple-guile: simple-guile.o
$@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
@@ -120,13 +128,11 @@ simple-guile.o: simple-guile.c
If you are using the GNU Autoconf package to make your application more
portable, Autoconf will settle many of the details in the Makefile above
automatically, making it much simpler and more portable; we recommend
-using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
-macro for autoconf that performs all necessary checks. Here is a
-@file{configure.in} file for @code{simple-guile} that uses this macro.
-Autoconf can use this file as a template to generate a @code{configure}
-script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
-will need to run @code{aclocal} first (@pxref{Invoking aclocal,,,
-automake, GNU Automake}).
+using Autoconf with Guile. Here is a @file{configure.ac} file for
+@code{simple-guile} that uses the standard @code{PKG_CHECK_MODULES}
+macro to check for Guile. Autoconf will process this file into a
+@code{configure} script. We recommend invoking Autoconf via the
+@code{autoreconf} utility.
@example
AC_INIT(simple-guile.c)
@@ -135,19 +141,21 @@ AC_INIT(simple-guile.c)
AC_PROG_CC
# Check for Guile
-GUILE_FLAGS
+PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
# Generate a Makefile, based on the results.
AC_OUTPUT(Makefile)
@end example
+Run @code{autoreconf -vif} to generate @code{configure}.
+
Here is a @code{Makefile.in} template, from which the @code{configure}
script produces a Makefile customized for the host system:
@example
# The configure script fills in these values.
CC=@@CC@@
CFLAGS=@@GUILE_CFLAGS@@
-LIBS=@@GUILE_LDFLAGS@@
+LIBS=@@GUILE_LIBS@@
simple-guile: simple-guile.o
$@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
@@ -156,23 +164,28 @@ simple-guile.o: simple-guile.c
@end example
The developer should use Autoconf to generate the @file{configure}
-script from the @file{configure.in} template, and distribute
+script from the @file{configure.ac} template, and distribute
@file{configure} with the application. Here's how a user might go about
building the application:
@example
$ ls
-Makefile.in configure* configure.in simple-guile.c
+Makefile.in configure* configure.ac simple-guile.c
$ ./configure
-creating cache ./config.cache
-checking for gcc... (cached) gcc
-checking whether the C compiler (gcc ) works... yes
-checking whether the C compiler (gcc ) is a cross-compiler... no
-checking whether we are using GNU C... (cached) yes
-checking whether gcc accepts -g... (cached) yes
-checking for Guile... yes
-creating ./config.status
-creating Makefile
+checking for gcc... ccache gcc
+checking whether the C compiler works... yes
+checking for C compiler default output file name... a.out
+checking for suffix of executables...
+checking whether we are cross compiling... no
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether ccache gcc accepts -g... yes
+checking for ccache gcc option to accept ISO C89... none needed
+checking for pkg-config... /usr/bin/pkg-config
+checking pkg-config is at least version 0.9.0... yes
+checking for GUILE... yes
+configure: creating ./config.status
+config.status: creating Makefile
$ make
[...]
$ ./simple-guile