Commit | Line | Data |
---|---|---|
3229f68b MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
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 | ||
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. | |
28 | ||
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 MV |
63 | |
64 | @node A Sample Guile Main Program | |
65 | @subsection A Sample Guile Main Program | |
66 | ||
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 | |
69 | interpreter. | |
70 | ||
71 | @example | |
72 | /* simple-guile.c --- how to start up the Guile | |
73 | interpreter from C code. */ | |
74 | ||
75 | /* Get declarations for all the scm_ functions. */ | |
76 | #include <libguile.h> | |
77 | ||
78 | static void | |
79 | inner_main (void *closure, int argc, char **argv) | |
80 | @{ | |
81 | /* module initializations would go here */ | |
82 | scm_shell (argc, argv); | |
83 | @} | |
84 | ||
85 | int | |
86 | main (int argc, char **argv) | |
87 | @{ | |
88 | scm_boot_guile (argc, argv, inner_main, 0); | |
89 | return 0; /* never reached */ | |
90 | @} | |
91 | @end example | |
92 | ||
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. | |
97 | ||
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 | |
100 | linker flags. | |
101 | @example | |
102 | # Use GCC, if you have it installed. | |
103 | CC=gcc | |
104 | ||
105 | # Tell the C compiler where to find <libguile.h> | |
106 | CFLAGS=`guile-config compile` | |
107 | ||
108 | # Tell the linker what libraries to use and where to find them. | |
109 | LIBS=`guile-config link` | |
110 | ||
111 | simple-guile: simple-guile.o | |
112 | $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile | |
113 | ||
114 | simple-guile.o: simple-guile.c | |
115 | $@{CC@} -c $@{CFLAGS@} simple-guile.c | |
116 | @end example | |
117 | ||
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 as this file as 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. This is not really Guile | |
127 | specific, so you should refer to the Autoconf documentation REFFIXME | |
128 | when in doubt. | |
129 | @example | |
130 | AC_INIT(simple-guile.c) | |
131 | ||
132 | # Find a C compiler. | |
133 | AC_PROG_CC | |
134 | ||
135 | # Check for Guile | |
136 | GUILE_FLAGS | |
137 | ||
138 | # Generate a Makefile, based on the results. | |
139 | AC_OUTPUT(Makefile) | |
140 | @end example | |
141 | ||
142 | Here is a @code{Makefile.in} template, from which the @code{configure} | |
143 | script produces a Makefile customized for the host system: | |
144 | @example | |
145 | # The configure script fills in these values. | |
146 | CC=@@CC@@ | |
147 | CFLAGS=@@GUILE_CFLAGS@@ | |
148 | LIBS=@@GUILE_LDFLAGS@@ | |
149 | ||
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 | |
154 | @end example | |
155 | ||
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: | |
160 | ||
161 | @example | |
162 | $ ls | |
163 | Makefile.in configure* configure.in simple-guile.c | |
164 | $ ./configure | |
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 | |
173 | creating Makefile | |
174 | $ make | |
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 | |
177 | $ ./simple-guile | |
178 | guile> (+ 1 2 3) | |
179 | 6 | |
180 | guile> (getpwnam "jimb") | |
181 | #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb" | |
182 | "/usr/local/bin/bash") | |
183 | guile> (exit) | |
184 | $ | |
185 | @end example | |
186 |