Commit | Line | Data |
---|---|---|
45a272c5 NJ |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
8a84f7fb LC |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011, |
4 | @c 2012 Free Software Foundation, Inc. | |
45a272c5 NJ |
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 | ||
ced9917e | 62 | Here is a trivial Guile script. @xref{Guile Scripting}, for more details. |
45a272c5 NJ |
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 \ | |
4b93693d | 118 | `pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}` |
45a272c5 NJ |
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 | ||
ced9917e AW |
139 | A library that is linked into Guile is called an @dfn{extension}, but it |
140 | really just is an ordinary object library. | |
45a272c5 NJ |
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 | @{ | |
8a84f7fb | 152 | return scm_from_double (j0 (scm_to_double (x))); |
45a272c5 NJ |
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 | |
f244cc51 AW |
166 | gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \ |
167 | -shared -o libguile-bessel.so -fPIC bessel.c | |
45a272c5 NJ |
168 | @end smallexample |
169 | ||
170 | For creating shared libraries portably, we recommend the use of GNU | |
171 | Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}). | |
172 | ||
173 | A shared library can be loaded into a running Guile process with the | |
174 | function @code{load-extension}. The @code{j0} is then immediately | |
175 | available: | |
176 | ||
177 | @smallexample | |
178 | $ guile | |
04ca2043 AW |
179 | scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel") |
180 | scheme@@(guile-user)> (j0 2) | |
181 | $1 = 0.223890779141236 | |
45a272c5 NJ |
182 | @end smallexample |
183 | ||
24cc7832 AW |
184 | For more on how to install your extension, @pxref{Installing Site |
185 | Packages}. | |
186 | ||
45a272c5 NJ |
187 | |
188 | @node Using the Guile Module System | |
189 | @subsection Using the Guile Module System | |
190 | ||
191 | Guile has support for dividing a program into @dfn{modules}. By using | |
192 | modules, you can group related code together and manage the | |
193 | composition of complete programs from largely independent parts. | |
194 | ||
9866cfe4 | 195 | For more details on the module system beyond this introductory material, |
45a272c5 NJ |
196 | @xref{Modules}. |
197 | ||
198 | @menu | |
199 | * Using Modules:: | |
200 | * Writing new Modules:: | |
201 | * Putting Extensions into Modules:: | |
202 | @end menu | |
203 | ||
204 | ||
205 | @node Using Modules | |
206 | @subsubsection Using Modules | |
207 | ||
208 | Guile comes with a lot of useful modules, for example for string | |
209 | processing or command line parsing. Additionally, there exist many | |
210 | Guile modules written by other Guile hackers, but which have to be | |
211 | installed manually. | |
212 | ||
213 | Here is a sample interactive session that shows how to use the | |
214 | @code{(ice-9 popen)} module which provides the means for communicating | |
215 | with other processes over pipes together with the @code{(ice-9 | |
216 | rdelim)} module that provides the function @code{read-line}. | |
217 | ||
218 | @smallexample | |
219 | $ guile | |
04ca2043 AW |
220 | scheme@@(guile-user)> (use-modules (ice-9 popen)) |
221 | scheme@@(guile-user)> (use-modules (ice-9 rdelim)) | |
222 | scheme@@(guile-user)> (define p (open-input-pipe "ls -l")) | |
223 | scheme@@(guile-user)> (read-line p) | |
224 | $1 = "total 30" | |
225 | scheme@@(guile-user)> (read-line p) | |
226 | $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS" | |
45a272c5 NJ |
227 | @end smallexample |
228 | ||
229 | @node Writing new Modules | |
230 | @subsubsection Writing new Modules | |
231 | ||
232 | You can create new modules using the syntactic form | |
233 | @code{define-module}. All definitions following this form until the | |
234 | next @code{define-module} are placed into the new module. | |
235 | ||
236 | One module is usually placed into one file, and that file is installed | |
237 | in a location where Guile can automatically find it. The following | |
238 | session shows a simple example. | |
239 | ||
240 | @smallexample | |
067df233 | 241 | $ cat /usr/local/share/guile/site/foo/bar.scm |
45a272c5 | 242 | |
9866cfe4 AW |
243 | (define-module (foo bar) |
244 | #:export (frob)) | |
45a272c5 NJ |
245 | |
246 | (define (frob x) (* 2 x)) | |
247 | ||
248 | $ guile | |
04ca2043 AW |
249 | scheme@@(guile-user)> (use-modules (foo bar)) |
250 | scheme@@(guile-user)> (frob 12) | |
251 | $1 = 24 | |
45a272c5 NJ |
252 | @end smallexample |
253 | ||
24cc7832 AW |
254 | For more on how to install your module, @pxref{Installing Site |
255 | Packages}. | |
256 | ||
257 | ||
45a272c5 NJ |
258 | @node Putting Extensions into Modules |
259 | @subsubsection Putting Extensions into Modules | |
260 | ||
261 | In addition to Scheme code you can also put things that are defined in | |
262 | C into a module. | |
263 | ||
264 | You do this by writing a small Scheme file that defines the module and | |
265 | call @code{load-extension} directly in the body of the module. | |
266 | ||
267 | @smallexample | |
067df233 | 268 | $ cat /usr/local/share/guile/site/math/bessel.scm |
45a272c5 | 269 | |
9866cfe4 AW |
270 | (define-module (math bessel) |
271 | #:export (j0)) | |
45a272c5 NJ |
272 | |
273 | (load-extension "libguile-bessel" "init_bessel") | |
274 | ||
067df233 | 275 | $ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/libguile-bessel.so |
45a272c5 NJ |
276 | @dots{} ELF 32-bit LSB shared object @dots{} |
277 | $ guile | |
04ca2043 AW |
278 | scheme@@(guile-user)> (use-modules (math bessel)) |
279 | scheme@@(guile-user)> (j0 2) | |
280 | $1 = 0.223890779141236 | |
45a272c5 NJ |
281 | @end smallexample |
282 | ||
9866cfe4 | 283 | @xref{Modules and Extensions}, for more information. |
45a272c5 | 284 | |
46733b42 NJ |
285 | @lowersections |
286 | ||
287 | @node Reporting Bugs | |
288 | @section Reporting Bugs | |
289 | ||
290 | Any problems with the installation should be reported to | |
291 | @email{bug-guile@@gnu.org}. | |
292 | ||
04ca2043 AW |
293 | If you find a bug in Guile, please report it to the Guile developers, so |
294 | they can fix it. They may also be able to suggest workarounds when it | |
295 | is not possible for you to apply the bug-fix or install a new version of | |
296 | Guile yourself. | |
46733b42 NJ |
297 | |
298 | Before sending in bug reports, please check with the following list that | |
299 | you really have found a bug. | |
300 | ||
301 | @itemize @bullet | |
302 | @item | |
303 | Whenever documentation and actual behavior differ, you have certainly | |
304 | found a bug, either in the documentation or in the program. | |
305 | ||
306 | @item | |
307 | When Guile crashes, it is a bug. | |
308 | ||
309 | @item | |
310 | When Guile hangs or takes forever to complete a task, it is a bug. | |
311 | ||
312 | @item | |
313 | When calculations produce wrong results, it is a bug. | |
314 | ||
315 | @item | |
316 | When Guile signals an error for valid Scheme programs, it is a bug. | |
317 | ||
318 | @item | |
319 | When Guile does not signal an error for invalid Scheme programs, it may | |
320 | be a bug, unless this is explicitly documented. | |
321 | ||
322 | @item | |
323 | When some part of the documentation is not clear and does not make sense | |
324 | to you even after re-reading the section, it is a bug. | |
325 | @end itemize | |
326 | ||
04ca2043 AW |
327 | Before reporting the bug, check whether any programs you have loaded |
328 | into Guile, including your @file{.guile} file, set any variables that | |
329 | may affect the functioning of Guile. Also, see whether the problem | |
330 | happens in a freshly started Guile without loading your @file{.guile} | |
331 | file (start Guile with the @code{-q} switch to prevent loading the init | |
332 | file). If the problem does @emph{not} occur then, you must report the | |
333 | precise contents of any programs that you must load into Guile in order | |
334 | to cause the problem to occur. | |
335 | ||
46733b42 NJ |
336 | When you write a bug report, please make sure to include as much of the |
337 | information described below in the report. If you can't figure out some | |
338 | of the items, it is not a problem, but the more information we get, the | |
339 | more likely we can diagnose and fix the bug. | |
340 | ||
341 | @itemize @bullet | |
342 | @item | |
04ca2043 AW |
343 | The version number of Guile. You can get this information from invoking |
344 | @samp{guile --version} at your shell, or calling @code{(version)} from | |
345 | within Guile. | |
46733b42 NJ |
346 | |
347 | @item | |
04ca2043 AW |
348 | Your machine type, as determined by the @code{config.guess} shell |
349 | script. If you have a Guile checkout, this file is located in | |
350 | @code{build-aux}; otherwise you can fetch the latest version from | |
351 | @uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}. | |
46733b42 NJ |
352 | |
353 | @example | |
04ca2043 AW |
354 | $ build-aux/config.guess |
355 | x86_64-unknown-linux-gnu | |
46733b42 NJ |
356 | @end example |
357 | ||
358 | @item | |
04ca2043 AW |
359 | If you installed Guile from a binary package, the version of that |
360 | package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems | |
361 | that use DPKG, @code{dpkg -l | grep guile}. | |
46733b42 NJ |
362 | |
363 | @item | |
04ca2043 | 364 | If you built Guile yourself, the build configuration that you used: |
46733b42 | 365 | |
04ca2043 AW |
366 | @example |
367 | $ ./config.status --config | |
ced9917e | 368 | '--enable-error-on-warning' '--disable-deprecated'... |
04ca2043 | 369 | @end example |
46733b42 NJ |
370 | |
371 | @item | |
04ca2043 | 372 | A complete description of how to reproduce the bug. |
46733b42 | 373 | |
04ca2043 AW |
374 | If you have a Scheme program that produces the bug, please include it in |
375 | the bug report. If your program is too big to include. please try to | |
376 | reduce your code to a minimal test case. | |
46733b42 | 377 | |
04ca2043 AW |
378 | If you can reproduce your problem at the REPL, that is best. Give a |
379 | transcript of the expressions you typed at the REPL. | |
46733b42 NJ |
380 | |
381 | @item | |
04ca2043 AW |
382 | A description of the incorrect behavior. For example, "The Guile |
383 | process gets a fatal signal," or, "The resulting output is as follows, | |
384 | which I think is wrong." | |
46733b42 NJ |
385 | |
386 | If the manifestation of the bug is a Guile error message, it is | |
387 | important to report the precise text of the error message, and a | |
04ca2043 AW |
388 | backtrace showing how the Scheme program arrived at the error. This can |
389 | be done using the @code{,backtrace} command in Guile's debugger. | |
390 | @end itemize | |
46733b42 | 391 | |
04ca2043 AW |
392 | If your bug causes Guile to crash, additional information from a |
393 | low-level debugger such as GDB might be helpful. If you have built Guile | |
394 | yourself, you can run Guile under GDB via the | |
395 | @code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as | |
396 | usual, invoke the wrapper script, type @code{run} to start the process, | |
397 | then @code{backtrace} when the crash comes. Include that backtrace in | |
398 | your report. | |
46733b42 | 399 | |
46733b42 | 400 | |
45a272c5 NJ |
401 | |
402 | @c Local Variables: | |
403 | @c TeX-master: "guile.texi" | |
404 | @c End: |