Commit | Line | Data |
---|---|---|
3229f68b MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
097a793b | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011 |
3229f68b MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @node Linking Programs With Guile | |
8 | @section Linking Programs With Guile | |
9 | ||
10 | This section covers the mechanics of linking your program with Guile | |
11 | on a typical POSIX system. | |
12 | ||
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}. | |
18 | ||
d32df132 AW |
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}: | |
23 | ||
24 | @example | |
25 | pkg-config guile-@value{EFFECTIVE-VERSION} --cflags | |
26 | pkg-config guile-@value{EFFECTIVE-VERSION} --libs | |
27 | @end example | |
097a793b | 28 | |
3229f68b MV |
29 | @menu |
30 | * Guile Initialization Functions:: What to call first. | |
31 | * A Sample Guile Main Program:: Sources and makefiles. | |
32 | @end menu | |
33 | ||
34 | ||
35 | @node Guile Initialization Functions | |
36 | @subsection Guile Initialization Functions | |
37 | ||
beac6039 MV |
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. | |
47 | ||
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. | |
3229f68b MV |
52 | |
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. | |
58 | ||
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 | |
beac6039 | 62 | @code{scm_boot_guile} and @code{scm_shell} function. |
3229f68b | 63 | |
871d8543 NJ |
64 | For more about these functions, see @ref{Initialization}. |
65 | ||
3229f68b MV |
66 | @node A Sample Guile Main Program |
67 | @subsection A Sample Guile Main Program | |
68 | ||
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 | |
71 | interpreter. | |
72 | ||
73 | @example | |
611563fb | 74 | /* simple-guile.c --- Start Guile from C. */ |
3229f68b | 75 | |
3229f68b MV |
76 | #include <libguile.h> |
77 | ||
78 | static void | |
79 | inner_main (void *closure, int argc, char **argv) | |
80 | @{ | |
611563fb | 81 | /* preparation */ |
3229f68b | 82 | scm_shell (argc, argv); |
611563fb | 83 | /* after exit */ |
3229f68b MV |
84 | @} |
85 | ||
86 | int | |
87 | main (int argc, char **argv) | |
88 | @{ | |
89 | scm_boot_guile (argc, argv, inner_main, 0); | |
611563fb | 90 | return 0; /* never reached, see inner_main */ |
3229f68b MV |
91 | @} |
92 | @end example | |
93 | ||
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. | |
98 | ||
611563fb AB |
99 | @subsection Building the Example with Make |
100 | ||
101 | Here is a Makefile which you can use to compile the example program. It | |
097a793b | 102 | uses @code{pkg-config} to learn about the necessary compiler and |
3229f68b MV |
103 | linker flags. |
104 | @example | |
105 | # Use GCC, if you have it installed. | |
106 | CC=gcc | |
107 | ||
108 | # Tell the C compiler where to find <libguile.h> | |
097a793b | 109 | CFLAGS=`pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` |
3229f68b MV |
110 | |
111 | # Tell the linker what libraries to use and where to find them. | |
097a793b | 112 | LIBS=`pkg-config --libs guile-@value{EFFECTIVE-VERSION}` |
3229f68b MV |
113 | |
114 | simple-guile: simple-guile.o | |
115 | $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile | |
116 | ||
117 | simple-guile.o: simple-guile.c | |
118 | $@{CC@} -c $@{CFLAGS@} simple-guile.c | |
119 | @end example | |
120 | ||
611563fb AB |
121 | @subsection Building the Example with Autoconf |
122 | ||
3229f68b | 123 | If you are using the GNU Autoconf package to make your application more |
611563fb | 124 | portable, Autoconf will settle many of the details in the Makefile |
3229f68b | 125 | automatically, making it much simpler and more portable; we recommend |
0e8a11c4 AW |
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. | |
39067a9f | 131 | |
3229f68b MV |
132 | @example |
133 | AC_INIT(simple-guile.c) | |
134 | ||
135 | # Find a C compiler. | |
136 | AC_PROG_CC | |
137 | ||
138 | # Check for Guile | |
0e8a11c4 | 139 | PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}]) |
3229f68b MV |
140 | |
141 | # Generate a Makefile, based on the results. | |
142 | AC_OUTPUT(Makefile) | |
143 | @end example | |
144 | ||
0e8a11c4 AW |
145 | Run @code{autoreconf -vif} to generate @code{configure}. |
146 | ||
3229f68b MV |
147 | Here is a @code{Makefile.in} template, from which the @code{configure} |
148 | script produces a Makefile customized for the host system: | |
149 | @example | |
150 | # The configure script fills in these values. | |
151 | CC=@@CC@@ | |
152 | CFLAGS=@@GUILE_CFLAGS@@ | |
0e8a11c4 | 153 | LIBS=@@GUILE_LIBS@@ |
3229f68b MV |
154 | |
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 | |
159 | @end example | |
160 | ||
161 | The developer should use Autoconf to generate the @file{configure} | |
0e8a11c4 | 162 | script from the @file{configure.ac} template, and distribute |
3229f68b MV |
163 | @file{configure} with the application. Here's how a user might go about |
164 | building the application: | |
165 | ||
166 | @example | |
167 | $ ls | |
0e8a11c4 | 168 | Makefile.in configure* configure.ac simple-guile.c |
3229f68b | 169 | $ ./configure |
0e8a11c4 AW |
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 | |
3229f68b | 184 | $ make |
1ea8aa7d | 185 | [...] |
3229f68b MV |
186 | $ ./simple-guile |
187 | guile> (+ 1 2 3) | |
188 | 6 | |
189 | guile> (getpwnam "jimb") | |
190 | #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb" | |
191 | "/usr/local/bin/bash") | |
192 | guile> (exit) | |
193 | $ | |
194 | @end example | |
195 | ||
39067a9f KR |
196 | |
197 | @c Local Variables: | |
198 | @c TeX-master: "guile.texi" | |
199 | @c End: |