2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005
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 On most systems, you should not need to tell the compiler and linker
20 explicitly where they can find @file{libguile.h} and @file{libguile}.
21 When Guile has been installed in a peculiar way, or when you are on a
22 peculiar system, things might not be so easy and you might need to pass
23 additional @code{-I} or @code{-L} options to the compiler. Guile
24 provides the utility program @code{guile-config} to help you find the
25 right values for these options. You would typically run
26 @code{guile-config} during the configuration phase of your program and
27 use the obtained information in the Makefile.
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 @node A Sample Guile Main Program
65 @subsection A Sample Guile Main Program
67 Here is @file{simple-guile.c}, source code for a @code{main} and an
68 @code{inner_main} function that will produce a complete Guile
72 /* simple-guile.c --- how to start up the Guile
73 interpreter from C code. */
75 /* Get declarations for all the scm_ functions. */
79 inner_main (void *closure, int argc, char **argv)
81 /* module initializations would go here */
82 scm_shell (argc, argv);
86 main (int argc, char **argv)
88 scm_boot_guile (argc, argv, inner_main, 0);
89 return 0; /* never reached */
93 The @code{main} function calls @code{scm_boot_guile} to initialize
94 Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
95 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
96 process the command-line arguments in the usual way.
98 Here is a Makefile which you can use to compile the above program. It
99 uses @code{guile-config} to learn about the necessary compiler and
102 # Use GCC, if you have it installed.
105 # Tell the C compiler where to find <libguile.h>
106 CFLAGS=`guile-config compile`
108 # Tell the linker what libraries to use and where to find them.
109 LIBS=`guile-config link`
111 simple-guile: simple-guile.o
112 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
114 simple-guile.o: simple-guile.c
115 $@{CC@} -c $@{CFLAGS@} simple-guile.c
118 If you are using the GNU Autoconf package to make your application more
119 portable, Autoconf will settle many of the details in the Makefile above
120 automatically, making it much simpler and more portable; we recommend
121 using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
122 macro for autoconf that performs all necessary checks. Here is a
123 @file{configure.in} file for @code{simple-guile} that uses this macro.
124 Autoconf can use this file as a template to generate a @code{configure}
125 script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
126 will need to run @code{aclocal} first (@pxref{Invoking aclocal,,,
127 automake, GNU Automake}).
130 AC_INIT(simple-guile.c)
138 # Generate a Makefile, based on the results.
142 Here is a @code{Makefile.in} template, from which the @code{configure}
143 script produces a Makefile customized for the host system:
145 # The configure script fills in these values.
147 CFLAGS=@@GUILE_CFLAGS@@
148 LIBS=@@GUILE_LDFLAGS@@
150 simple-guile: simple-guile.o
151 $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
152 simple-guile.o: simple-guile.c
153 $@{CC@} -c $@{CFLAGS@} simple-guile.c
156 The developer should use Autoconf to generate the @file{configure}
157 script from the @file{configure.in} template, and distribute
158 @file{configure} with the application. Here's how a user might go about
159 building the application:
163 Makefile.in configure* configure.in simple-guile.c
165 creating cache ./config.cache
166 checking for gcc... (cached) gcc
167 checking whether the C compiler (gcc ) works... yes
168 checking whether the C compiler (gcc ) is a cross-compiler... no
169 checking whether we are using GNU C... (cached) yes
170 checking whether gcc accepts -g... (cached) yes
171 checking for Guile... yes
172 creating ./config.status
175 gcc -c -I/usr/local/include simple-guile.c
176 gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
180 guile> (getpwnam "jimb")
181 #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
182 "/usr/local/bin/bash")
189 @c TeX-master: "guile.texi"