Commit | Line | Data |
---|---|---|
45a272c5 NJ |
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, 2006, 2010 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
46733b42 NJ |
7 | @raisesections |
8 | ||
45a272c5 NJ |
9 | @node Hello Guile! |
10 | @section Hello Guile! | |
11 | ||
12 | This chapter presents a quick tour of all the ways that Guile can be | |
13 | used. There are additional examples in the @file{examples/} | |
46733b42 NJ |
14 | directory in the Guile source distribution. It also explains how best to report |
15 | any problems that you find. | |
45a272c5 NJ |
16 | |
17 | The following examples assume that Guile has been installed in | |
18 | @code{/usr/local/}. | |
19 | ||
20 | @menu | |
21 | * Running Guile Interactively:: | |
22 | * Running Guile Scripts:: | |
23 | * Linking Guile into Programs:: | |
24 | * Writing Guile Extensions:: | |
25 | * Using the Guile Module System:: | |
46733b42 | 26 | * Reporting Bugs:: |
45a272c5 NJ |
27 | @end menu |
28 | ||
29 | ||
30 | @node Running Guile Interactively | |
31 | @subsection Running Guile Interactively | |
32 | ||
33 | In its simplest form, Guile acts as an interactive interpreter for the | |
34 | Scheme programming language, reading and evaluating Scheme expressions | |
35 | the user enters from the terminal. Here is a sample interaction between | |
36 | Guile and a user; the user's input appears after the @code{$} and | |
04ca2043 | 37 | @code{scheme@@(guile-user)>} prompts: |
45a272c5 NJ |
38 | |
39 | @example | |
40 | $ guile | |
04ca2043 AW |
41 | scheme@@(guile-user)> (+ 1 2 3) ; add some numbers |
42 | $1 = 6 | |
43 | scheme@@(guile-user)> (define (factorial n) ; define a function | |
21476d84 | 44 | (if (zero? n) 1 (* n (factorial (- n 1))))) |
04ca2043 AW |
45 | scheme@@(guile-user)> (factorial 20) |
46 | $2 = 2432902008176640000 | |
21476d84 AW |
47 | scheme@@(guile-user)> (getpwnam "root") ; look in /etc/passwd |
48 | $3 = #("root" "x" 0 0 "root" "/root" "/bin/bash") | |
04ca2043 | 49 | scheme@@(guile-user)> @kbd{C-d} |
45a272c5 NJ |
50 | $ |
51 | @end example | |
52 | ||
53 | ||
54 | @node Running Guile Scripts | |
55 | @subsection Running Guile Scripts | |
56 | ||
57 | Like AWK, Perl, or any shell, Guile can interpret script files. A Guile | |
58 | script is simply a file of Scheme code with some extra information at | |
59 | the beginning which tells the operating system how to invoke Guile, and | |
60 | then tells Guile how to handle the Scheme code. | |
61 | ||
62 | Here is a trivial Guile script, for more details @xref{Guile Scripting}. | |
63 | ||
64 | @example | |
65 | #!/usr/local/bin/guile -s | |
66 | !# | |
67 | (display "Hello, world!") | |
68 | (newline) | |
69 | @end example | |
70 | ||
71 | ||
72 | @node Linking Guile into Programs | |
73 | @subsection Linking Guile into Programs | |
74 | ||
75 | The Guile interpreter is available as an object library, to be linked | |
76 | into applications using Scheme as a configuration or extension | |
77 | language. | |
78 | ||
79 | Here is @file{simple-guile.c}, source code for a program that will | |
80 | produce a complete Guile interpreter. In addition to all usual | |
81 | functions provided by Guile, it will also offer the function | |
82 | @code{my-hostname}. | |
83 | ||
84 | @example | |
85 | #include <stdlib.h> | |
86 | #include <libguile.h> | |
87 | ||
88 | static SCM | |
89 | my_hostname (void) | |
90 | @{ | |
91 | char *s = getenv ("HOSTNAME"); | |
92 | if (s == NULL) | |
93 | return SCM_BOOL_F; | |
94 | else | |
95 | return scm_from_locale_string (s); | |
96 | @} | |
97 | ||
98 | static void | |
99 | inner_main (void *data, int argc, char **argv) | |
100 | @{ | |
101 | scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname); | |
102 | scm_shell (argc, argv); | |
103 | @} | |
104 | ||
105 | int | |
106 | main (int argc, char **argv) | |
107 | @{ | |
108 | scm_boot_guile (argc, argv, inner_main, 0); | |
109 | return 0; /* never reached */ | |
110 | @} | |
111 | @end example | |
112 | ||
113 | When Guile is correctly installed on your system, the above program | |
114 | can be compiled and linked like this: | |
115 | ||
116 | @example | |
117 | $ gcc -o simple-guile simple-guile.c \ | |
118 | `pkg-config --cflags --libs guile-2.0` | |
119 | @end example | |
120 | ||
121 | When it is run, it behaves just like the @code{guile} program except | |
122 | that you can also call the new @code{my-hostname} function. | |
123 | ||
124 | @example | |
125 | $ ./simple-guile | |
04ca2043 AW |
126 | scheme@@(guile-user)> (+ 1 2 3) |
127 | $1 = 6 | |
128 | scheme@@(guile-user)> (my-hostname) | |
45a272c5 NJ |
129 | "burns" |
130 | @end example | |
131 | ||
132 | @node Writing Guile Extensions | |
133 | @subsection Writing Guile Extensions | |
134 | ||
135 | You can link Guile into your program and make Scheme available to the | |
136 | users of your program. You can also link your library into Guile and | |
137 | make its functionality available to all users of Guile. | |
138 | ||
139 | A library that is linked into Guile is called an @dfn{extensions}, but | |
140 | it really just is an ordinary object library. | |
141 | ||
142 | The following example shows how to write a simple extension for Guile | |
143 | that makes the @code{j0} function available to Scheme code. | |
144 | ||
145 | @smallexample | |
146 | #include <math.h> | |
147 | #include <libguile.h> | |
148 | ||
149 | SCM | |
150 | j0_wrapper (SCM x) | |
151 | @{ | |
152 | return scm_make_real (j0 (scm_num2dbl (x, "j0"))); | |
153 | @} | |
154 | ||
155 | void | |
156 | init_bessel () | |
157 | @{ | |
158 | scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper); | |
159 | @} | |
160 | @end smallexample | |
161 | ||
162 | This C source file needs to be compiled into a shared library. Here is | |
163 | how to do it on GNU/Linux: | |
164 | ||
165 | @smallexample | |
166 | gcc -shared -o libguile-bessel.so -fPIC bessel.c | |
167 | @end smallexample | |
168 | ||
169 | For creating shared libraries portably, we recommend the use of GNU | |
170 | Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}). | |
171 | ||
172 | A shared library can be loaded into a running Guile process with the | |
173 | function @code{load-extension}. The @code{j0} is then immediately | |
174 | available: | |
175 | ||
176 | @smallexample | |
177 | $ guile | |
04ca2043 AW |
178 | scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel") |
179 | scheme@@(guile-user)> (j0 2) | |
180 | $1 = 0.223890779141236 | |
45a272c5 NJ |
181 | @end smallexample |
182 | ||
183 | ||
184 | @node Using the Guile Module System | |
185 | @subsection Using the Guile Module System | |
186 | ||
187 | Guile has support for dividing a program into @dfn{modules}. By using | |
188 | modules, you can group related code together and manage the | |
189 | composition of complete programs from largely independent parts. | |
190 | ||
191 | (Although the module system implementation is in flux, feel free to use it | |
192 | anyway. Guile will provide reasonable backwards compatibility.) | |
193 | ||
194 | Details on the module system beyond this introductory material can be found in | |
195 | @xref{Modules}. | |
196 | ||
197 | @menu | |
198 | * Using Modules:: | |
199 | * Writing new Modules:: | |
200 | * Putting Extensions into Modules:: | |
201 | @end menu | |
202 | ||
203 | ||
204 | @node Using Modules | |
205 | @subsubsection Using Modules | |
206 | ||
207 | Guile comes with a lot of useful modules, for example for string | |
208 | processing or command line parsing. Additionally, there exist many | |
209 | Guile modules written by other Guile hackers, but which have to be | |
210 | installed manually. | |
211 | ||
212 | Here is a sample interactive session that shows how to use the | |
213 | @code{(ice-9 popen)} module which provides the means for communicating | |
214 | with other processes over pipes together with the @code{(ice-9 | |
215 | rdelim)} module that provides the function @code{read-line}. | |
216 | ||
217 | @smallexample | |
218 | $ guile | |
04ca2043 AW |
219 | scheme@@(guile-user)> (use-modules (ice-9 popen)) |
220 | scheme@@(guile-user)> (use-modules (ice-9 rdelim)) | |
221 | scheme@@(guile-user)> (define p (open-input-pipe "ls -l")) | |
222 | scheme@@(guile-user)> (read-line p) | |
223 | $1 = "total 30" | |
224 | scheme@@(guile-user)> (read-line p) | |
225 | $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" | |
45a272c5 NJ |
226 | @end smallexample |
227 | ||
228 | @node Writing new Modules | |
229 | @subsubsection Writing new Modules | |
230 | ||
231 | You can create new modules using the syntactic form | |
232 | @code{define-module}. All definitions following this form until the | |
233 | next @code{define-module} are placed into the new module. | |
234 | ||
235 | One module is usually placed into one file, and that file is installed | |
236 | in a location where Guile can automatically find it. The following | |
237 | session shows a simple example. | |
238 | ||
239 | @smallexample | |
240 | $ cat /usr/local/share/guile/foo/bar.scm | |
241 | ||
242 | (define-module (foo bar)) | |
243 | (export frob) | |
244 | ||
245 | (define (frob x) (* 2 x)) | |
246 | ||
247 | $ guile | |
04ca2043 AW |
248 | scheme@@(guile-user)> (use-modules (foo bar)) |
249 | scheme@@(guile-user)> (frob 12) | |
250 | $1 = 24 | |
45a272c5 NJ |
251 | @end smallexample |
252 | ||
253 | @node Putting Extensions into Modules | |
254 | @subsubsection Putting Extensions into Modules | |
255 | ||
256 | In addition to Scheme code you can also put things that are defined in | |
257 | C into a module. | |
258 | ||
259 | You do this by writing a small Scheme file that defines the module and | |
260 | call @code{load-extension} directly in the body of the module. | |
261 | ||
262 | @smallexample | |
263 | $ cat /usr/local/share/guile/math/bessel.scm | |
264 | ||
265 | (define-module (math bessel)) | |
266 | (export j0) | |
267 | ||
268 | (load-extension "libguile-bessel" "init_bessel") | |
269 | ||
270 | $ file /usr/local/lib/libguile-bessel.so | |
271 | @dots{} ELF 32-bit LSB shared object @dots{} | |
272 | $ guile | |
04ca2043 AW |
273 | scheme@@(guile-user)> (use-modules (math bessel)) |
274 | scheme@@(guile-user)> (j0 2) | |
275 | $1 = 0.223890779141236 | |
45a272c5 NJ |
276 | @end smallexample |
277 | ||
278 | There is also a way to manipulate the module system from C but only | |
279 | Scheme files can be autoloaded. Thus, we recommend that you define | |
280 | your modules in Scheme. | |
281 | ||
46733b42 NJ |
282 | @lowersections |
283 | ||
284 | @node Reporting Bugs | |
285 | @section Reporting Bugs | |
286 | ||
287 | Any problems with the installation should be reported to | |
288 | @email{bug-guile@@gnu.org}. | |
289 | ||
04ca2043 AW |
290 | If you find a bug in Guile, please report it to the Guile developers, so |
291 | they can fix it. They may also be able to suggest workarounds when it | |
292 | is not possible for you to apply the bug-fix or install a new version of | |
293 | Guile yourself. | |
46733b42 NJ |
294 | |
295 | Before sending in bug reports, please check with the following list that | |
296 | you really have found a bug. | |
297 | ||
298 | @itemize @bullet | |
299 | @item | |
300 | Whenever documentation and actual behavior differ, you have certainly | |
301 | found a bug, either in the documentation or in the program. | |
302 | ||
303 | @item | |
304 | When Guile crashes, it is a bug. | |
305 | ||
306 | @item | |
307 | When Guile hangs or takes forever to complete a task, it is a bug. | |
308 | ||
309 | @item | |
310 | When calculations produce wrong results, it is a bug. | |
311 | ||
312 | @item | |
313 | When Guile signals an error for valid Scheme programs, it is a bug. | |
314 | ||
315 | @item | |
316 | When Guile does not signal an error for invalid Scheme programs, it may | |
317 | be a bug, unless this is explicitly documented. | |
318 | ||
319 | @item | |
320 | When some part of the documentation is not clear and does not make sense | |
321 | to you even after re-reading the section, it is a bug. | |
322 | @end itemize | |
323 | ||
04ca2043 AW |
324 | Before reporting the bug, check whether any programs you have loaded |
325 | into Guile, including your @file{.guile} file, set any variables that | |
326 | may affect the functioning of Guile. Also, see whether the problem | |
327 | happens in a freshly started Guile without loading your @file{.guile} | |
328 | file (start Guile with the @code{-q} switch to prevent loading the init | |
329 | file). If the problem does @emph{not} occur then, you must report the | |
330 | precise contents of any programs that you must load into Guile in order | |
331 | to cause the problem to occur. | |
332 | ||
46733b42 NJ |
333 | When you write a bug report, please make sure to include as much of the |
334 | information described below in the report. If you can't figure out some | |
335 | of the items, it is not a problem, but the more information we get, the | |
336 | more likely we can diagnose and fix the bug. | |
337 | ||
338 | @itemize @bullet | |
339 | @item | |
04ca2043 AW |
340 | The version number of Guile. You can get this information from invoking |
341 | @samp{guile --version} at your shell, or calling @code{(version)} from | |
342 | within Guile. | |
46733b42 NJ |
343 | |
344 | @item | |
04ca2043 AW |
345 | Your machine type, as determined by the @code{config.guess} shell |
346 | script. If you have a Guile checkout, this file is located in | |
347 | @code{build-aux}; otherwise you can fetch the latest version from | |
348 | @uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}. | |
46733b42 NJ |
349 | |
350 | @example | |
04ca2043 AW |
351 | $ build-aux/config.guess |
352 | x86_64-unknown-linux-gnu | |
46733b42 NJ |
353 | @end example |
354 | ||
355 | @item | |
04ca2043 AW |
356 | If you installed Guile from a binary package, the version of that |
357 | package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems | |
358 | that use DPKG, @code{dpkg -l | grep guile}. | |
46733b42 NJ |
359 | |
360 | @item | |
04ca2043 | 361 | If you built Guile yourself, the build configuration that you used: |
46733b42 | 362 | |
04ca2043 AW |
363 | @example |
364 | $ ./config.status --config | |
365 | '--enable-error-on-warning' '--disable-deprecated' '--prefix=/opt/guile' '--libdir=/opt/guile/lib64' 'CC=ccache gcc' | |
366 | @end example | |
46733b42 NJ |
367 | |
368 | @item | |
04ca2043 | 369 | A complete description of how to reproduce the bug. |
46733b42 | 370 | |
04ca2043 AW |
371 | If you have a Scheme program that produces the bug, please include it in |
372 | the bug report. If your program is too big to include. please try to | |
373 | reduce your code to a minimal test case. | |
46733b42 | 374 | |
04ca2043 AW |
375 | If you can reproduce your problem at the REPL, that is best. Give a |
376 | transcript of the expressions you typed at the REPL. | |
46733b42 NJ |
377 | |
378 | @item | |
04ca2043 AW |
379 | A description of the incorrect behavior. For example, "The Guile |
380 | process gets a fatal signal," or, "The resulting output is as follows, | |
381 | which I think is wrong." | |
46733b42 NJ |
382 | |
383 | If the manifestation of the bug is a Guile error message, it is | |
384 | important to report the precise text of the error message, and a | |
04ca2043 AW |
385 | backtrace showing how the Scheme program arrived at the error. This can |
386 | be done using the @code{,backtrace} command in Guile's debugger. | |
387 | @end itemize | |
46733b42 | 388 | |
04ca2043 AW |
389 | If your bug causes Guile to crash, additional information from a |
390 | low-level debugger such as GDB might be helpful. If you have built Guile | |
391 | yourself, you can run Guile under GDB via the | |
392 | @code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as | |
393 | usual, invoke the wrapper script, type @code{run} to start the process, | |
394 | then @code{backtrace} when the crash comes. Include that backtrace in | |
395 | your report. | |
46733b42 | 396 | |
46733b42 | 397 | |
45a272c5 NJ |
398 | |
399 | @c Local Variables: | |
400 | @c TeX-master: "guile.texi" | |
401 | @c End: |