2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Linking Programs With Guile
8 @section Linking Programs With Guile
10 This section covers the mechanics of linking your program with Guile
11 on a typical POSIX system.
13 The header file @code{<libguile.h>} provides declarations for all of
14 Guile's functions and constants. You should @code{#include} it at the
15 head of any C source file that uses identifiers described in this
16 manual. Once you've compiled your source files, you need to link them
17 against the Guile object code library, @code{libguile}.
19 As noted in the previous section, @code{<libguile.h>} is not in the
20 default search path for headers. The following command lines give
21 respectively the C compilation and link flags needed to build programs
22 using Guile @value{EFFECTIVE-VERSION}:
25 pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
26 pkg-config guile-@value{EFFECTIVE-VERSION} --libs
30 * Guile Initialization Functions:: What to call first.
31 * A Sample Guile Main Program:: Sources and makefiles.
35 @node Guile Initialization Functions
36 @subsection Guile Initialization Functions
38 To initialize Guile, you can use one of several functions. The first,
39 @code{scm_with_guile}, is the most portable way to initialize Guile. It
40 will initialize Guile when necessary and then call a function that you
41 can specify. Multiple threads can call @code{scm_with_guile}
42 concurrently and it can also be called more than once in a given thread.
43 The global state of Guile will survive from one call of
44 @code{scm_with_guile} to the next. Your function is called from within
45 @code{scm_with_guile} since the garbage collector of Guile needs to know
46 where the stack of each thread is.
48 A second function, @code{scm_init_guile}, initializes Guile for the
49 current thread. When it returns, you can use the Guile API in the
50 current thread. This function employs some non-portable magic to learn
51 about stack bounds and might thus not be available on all platforms.
53 One common way to use Guile is to write a set of C functions which
54 perform some useful task, make them callable from Scheme, and then link
55 the program with Guile. This yields a Scheme interpreter just like
56 @code{guile}, but augmented with extra functions for some specific
57 application --- a special-purpose scripting language.
59 In this situation, the application should probably process its
60 command-line arguments in the same manner as the stock Guile
61 interpreter. To make that straightforward, Guile provides the
62 @code{scm_boot_guile} and @code{scm_shell} function.
64 For more about these functions, see @ref{Initialization}.
66 @node A Sample Guile Main Program
67 @subsection A Sample Guile Main Program
69 Here is @file{simple-guile.c}, source code for a @code{main} and an
70 @code{inner_main} function that will produce a complete Guile
74 /* simple-guile.c --- Start Guile from C. */
79 inner_main (void *closure, int argc, char **argv)
82 scm_shell (argc, argv);
87 main (int argc, char **argv)
89 scm_boot_guile (argc, argv, inner_main, 0);
90 return 0; /* never reached, see inner_main */
94 The @code{main} function calls @code{scm_boot_guile} to initialize
95 Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
96 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
97 process the command-line arguments in the usual way.
99 @subsection Building the Example with Make
101 Here is a Makefile which you can use to compile the example program. It
102 uses @code{pkg-config} to learn about the necessary compiler and
105 # Use GCC, if you have it installed.
108 # Tell the C compiler where to find <libguile.h>
109 CFLAGS=`pkg-config --cflags guile-@value{EFFECTIVE-VERSION}`
111 # Tell the linker what libraries to use and where to find them.
112 LIBS=`pkg-config --libs guile-@value{EFFECTIVE-VERSION}`
114 simple-guile: simple-guile.o
115 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
117 simple-guile.o: simple-guile.c
118 $@{CC@} -c $@{CFLAGS@} simple-guile.c
121 @subsection Building the Example with Autoconf
123 If you are using the GNU Autoconf package to make your application more
124 portable, Autoconf will settle many of the details in the Makefile
125 automatically, making it much simpler and more portable; we recommend
126 using Autoconf with Guile. Here is a @file{configure.ac} file for
127 @code{simple-guile} that uses the standard @code{PKG_CHECK_MODULES}
128 macro to check for Guile. Autoconf will process this file into a
129 @code{configure} script. We recommend invoking Autoconf via the
130 @code{autoreconf} utility.
133 AC_INIT(simple-guile.c)
139 PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
141 # Generate a Makefile, based on the results.
145 Run @code{autoreconf -vif} to generate @code{configure}.
147 Here is a @code{Makefile.in} template, from which the @code{configure}
148 script produces a Makefile customized for the host system:
150 # The configure script fills in these values.
152 CFLAGS=@@GUILE_CFLAGS@@
155 simple-guile: simple-guile.o
156 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
157 simple-guile.o: simple-guile.c
158 $@{CC@} -c $@{CFLAGS@} simple-guile.c
161 The developer should use Autoconf to generate the @file{configure}
162 script from the @file{configure.ac} template, and distribute
163 @file{configure} with the application. Here's how a user might go about
164 building the application:
168 Makefile.in configure* configure.ac simple-guile.c
170 checking for gcc... ccache gcc
171 checking whether the C compiler works... yes
172 checking for C compiler default output file name... a.out
173 checking for suffix of executables...
174 checking whether we are cross compiling... no
175 checking for suffix of object files... o
176 checking whether we are using the GNU C compiler... yes
177 checking whether ccache gcc accepts -g... yes
178 checking for ccache gcc option to accept ISO C89... none needed
179 checking for pkg-config... /usr/bin/pkg-config
180 checking pkg-config is at least version 0.9.0... yes
181 checking for GUILE... yes
182 configure: creating ./config.status
183 config.status: creating Makefile
189 guile> (getpwnam "jimb")
190 #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
191 "/usr/local/bin/bash")
198 @c TeX-master: "guile.texi"