2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
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/}
14 directory in the Guile source distribution. It also explains how best to report
15 any problems that you find.
17 The following examples assume that Guile has been installed in
21 * Running Guile Interactively::
22 * Running Guile Scripts::
23 * Linking Guile into Programs::
24 * Writing Guile Extensions::
25 * Using the Guile Module System::
30 @node Running Guile Interactively
31 @subsection Running Guile Interactively
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
37 @code{scheme@@(guile-user)>} prompts:
41 scheme@@(guile-user)> (+ 1 2 3) ; add some numbers
43 scheme@@(guile-user)> (define (factorial n) ; define a function
44 (if (zero? n) 1 (* n (factorial (- n 1)))))
45 scheme@@(guile-user)> (factorial 20)
46 $2 = 2432902008176640000
47 scheme@@(guile-user)> (getpwnam "root") ; look in /etc/passwd
48 $3 = #("root" "x" 0 0 "root" "/root" "/bin/bash")
49 scheme@@(guile-user)> @kbd{C-d}
54 @node Running Guile Scripts
55 @subsection Running Guile Scripts
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.
62 Here is a trivial Guile script. @xref{Guile Scripting}, for more details.
65 #!/usr/local/bin/guile -s
67 (display "Hello, world!")
72 @node Linking Guile into Programs
73 @subsection Linking Guile into Programs
75 The Guile interpreter is available as an object library, to be linked
76 into applications using Scheme as a configuration or extension
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
91 char *s = getenv ("HOSTNAME");
95 return scm_from_locale_string (s);
99 inner_main (void *data, int argc, char **argv)
101 scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
102 scm_shell (argc, argv);
106 main (int argc, char **argv)
108 scm_boot_guile (argc, argv, inner_main, 0);
109 return 0; /* never reached */
113 When Guile is correctly installed on your system, the above program
114 can be compiled and linked like this:
117 $ gcc -o simple-guile simple-guile.c \
118 `pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}`
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.
126 scheme@@(guile-user)> (+ 1 2 3)
128 scheme@@(guile-user)> (my-hostname)
132 @node Writing Guile Extensions
133 @subsection Writing Guile Extensions
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.
139 A library that is linked into Guile is called an @dfn{extension}, but it
140 really just is an ordinary object library.
142 The following example shows how to write a simple extension for Guile
143 that makes the @code{j0} function available to Scheme code.
147 #include <libguile.h>
152 return scm_make_real (j0 (scm_num2dbl (x, "j0")));
158 scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
162 This C source file needs to be compiled into a shared library. Here is
163 how to do it on GNU/Linux:
166 gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
167 -shared -o libguile-bessel.so -fPIC bessel.c
170 For creating shared libraries portably, we recommend the use of GNU
171 Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
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
179 scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
180 scheme@@(guile-user)> (j0 2)
181 $1 = 0.223890779141236
185 @node Using the Guile Module System
186 @subsection Using the Guile Module System
188 Guile has support for dividing a program into @dfn{modules}. By using
189 modules, you can group related code together and manage the
190 composition of complete programs from largely independent parts.
192 For more details on the module system beyond this introductory material,
197 * Writing new Modules::
198 * Putting Extensions into Modules::
203 @subsubsection Using Modules
205 Guile comes with a lot of useful modules, for example for string
206 processing or command line parsing. Additionally, there exist many
207 Guile modules written by other Guile hackers, but which have to be
210 Here is a sample interactive session that shows how to use the
211 @code{(ice-9 popen)} module which provides the means for communicating
212 with other processes over pipes together with the @code{(ice-9
213 rdelim)} module that provides the function @code{read-line}.
217 scheme@@(guile-user)> (use-modules (ice-9 popen))
218 scheme@@(guile-user)> (use-modules (ice-9 rdelim))
219 scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
220 scheme@@(guile-user)> (read-line p)
222 scheme@@(guile-user)> (read-line p)
223 $2 = "drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
226 @node Writing new Modules
227 @subsubsection Writing new Modules
229 You can create new modules using the syntactic form
230 @code{define-module}. All definitions following this form until the
231 next @code{define-module} are placed into the new module.
233 One module is usually placed into one file, and that file is installed
234 in a location where Guile can automatically find it. The following
235 session shows a simple example.
238 $ cat /usr/local/share/guile/site/foo/bar.scm
240 (define-module (foo bar)
243 (define (frob x) (* 2 x))
246 scheme@@(guile-user)> (use-modules (foo bar))
247 scheme@@(guile-user)> (frob 12)
251 @node Putting Extensions into Modules
252 @subsubsection Putting Extensions into Modules
254 In addition to Scheme code you can also put things that are defined in
257 You do this by writing a small Scheme file that defines the module and
258 call @code{load-extension} directly in the body of the module.
261 $ cat /usr/local/share/guile/site/math/bessel.scm
263 (define-module (math bessel)
266 (load-extension "libguile-bessel" "init_bessel")
268 $ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/libguile-bessel.so
269 @dots{} ELF 32-bit LSB shared object @dots{}
271 scheme@@(guile-user)> (use-modules (math bessel))
272 scheme@@(guile-user)> (j0 2)
273 $1 = 0.223890779141236
276 @xref{Modules and Extensions}, for more information.
281 @section Reporting Bugs
283 Any problems with the installation should be reported to
284 @email{bug-guile@@gnu.org}.
286 If you find a bug in Guile, please report it to the Guile developers, so
287 they can fix it. They may also be able to suggest workarounds when it
288 is not possible for you to apply the bug-fix or install a new version of
291 Before sending in bug reports, please check with the following list that
292 you really have found a bug.
296 Whenever documentation and actual behavior differ, you have certainly
297 found a bug, either in the documentation or in the program.
300 When Guile crashes, it is a bug.
303 When Guile hangs or takes forever to complete a task, it is a bug.
306 When calculations produce wrong results, it is a bug.
309 When Guile signals an error for valid Scheme programs, it is a bug.
312 When Guile does not signal an error for invalid Scheme programs, it may
313 be a bug, unless this is explicitly documented.
316 When some part of the documentation is not clear and does not make sense
317 to you even after re-reading the section, it is a bug.
320 Before reporting the bug, check whether any programs you have loaded
321 into Guile, including your @file{.guile} file, set any variables that
322 may affect the functioning of Guile. Also, see whether the problem
323 happens in a freshly started Guile without loading your @file{.guile}
324 file (start Guile with the @code{-q} switch to prevent loading the init
325 file). If the problem does @emph{not} occur then, you must report the
326 precise contents of any programs that you must load into Guile in order
327 to cause the problem to occur.
329 When you write a bug report, please make sure to include as much of the
330 information described below in the report. If you can't figure out some
331 of the items, it is not a problem, but the more information we get, the
332 more likely we can diagnose and fix the bug.
336 The version number of Guile. You can get this information from invoking
337 @samp{guile --version} at your shell, or calling @code{(version)} from
341 Your machine type, as determined by the @code{config.guess} shell
342 script. If you have a Guile checkout, this file is located in
343 @code{build-aux}; otherwise you can fetch the latest version from
344 @uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}.
347 $ build-aux/config.guess
348 x86_64-unknown-linux-gnu
352 If you installed Guile from a binary package, the version of that
353 package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems
354 that use DPKG, @code{dpkg -l | grep guile}.
357 If you built Guile yourself, the build configuration that you used:
360 $ ./config.status --config
361 '--enable-error-on-warning' '--disable-deprecated'...
365 A complete description of how to reproduce the bug.
367 If you have a Scheme program that produces the bug, please include it in
368 the bug report. If your program is too big to include. please try to
369 reduce your code to a minimal test case.
371 If you can reproduce your problem at the REPL, that is best. Give a
372 transcript of the expressions you typed at the REPL.
375 A description of the incorrect behavior. For example, "The Guile
376 process gets a fatal signal," or, "The resulting output is as follows,
377 which I think is wrong."
379 If the manifestation of the bug is a Guile error message, it is
380 important to report the precise text of the error message, and a
381 backtrace showing how the Scheme program arrived at the error. This can
382 be done using the @code{,backtrace} command in Guile's debugger.
385 If your bug causes Guile to crash, additional information from a
386 low-level debugger such as GDB might be helpful. If you have built Guile
387 yourself, you can run Guile under GDB via the
388 @code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
389 usual, invoke the wrapper script, type @code{run} to start the process,
390 then @code{backtrace} when the crash comes. Include that backtrace in
396 @c TeX-master: "guile.texi"