| 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, 2011, |
| 4 | @c 2012 Free Software Foundation, Inc. |
| 5 | @c See the file guile.texi for copying conditions. |
| 6 | |
| 7 | @raisesections |
| 8 | |
| 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/} |
| 14 | directory in the Guile source distribution. It also explains how best to report |
| 15 | any problems that you find. |
| 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:: |
| 26 | * Reporting Bugs:: |
| 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 |
| 37 | @code{scheme@@(guile-user)>} prompts: |
| 38 | |
| 39 | @example |
| 40 | $ guile |
| 41 | scheme@@(guile-user)> (+ 1 2 3) ; add some numbers |
| 42 | $1 = 6 |
| 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} |
| 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. @xref{Guile Scripting}, for more details. |
| 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-@value{EFFECTIVE-VERSION}` |
| 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 |
| 126 | scheme@@(guile-user)> (+ 1 2 3) |
| 127 | $1 = 6 |
| 128 | scheme@@(guile-user)> (my-hostname) |
| 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{extension}, but it |
| 140 | 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_from_double (j0 (scm_to_double (x))); |
| 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 `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \ |
| 167 | -shared -o libguile-bessel.so -fPIC bessel.c |
| 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 |
| 179 | scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel") |
| 180 | scheme@@(guile-user)> (j0 2) |
| 181 | $1 = 0.223890779141236 |
| 182 | @end smallexample |
| 183 | |
| 184 | For more on how to install your extension, @pxref{Installing Site |
| 185 | Packages}. |
| 186 | |
| 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 | |
| 195 | For more details on the module system beyond this introductory material, |
| 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 |
| 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" |
| 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 |
| 241 | $ cat /usr/local/share/guile/site/foo/bar.scm |
| 242 | |
| 243 | (define-module (foo bar) |
| 244 | #:export (frob)) |
| 245 | |
| 246 | (define (frob x) (* 2 x)) |
| 247 | |
| 248 | $ guile |
| 249 | scheme@@(guile-user)> (use-modules (foo bar)) |
| 250 | scheme@@(guile-user)> (frob 12) |
| 251 | $1 = 24 |
| 252 | @end smallexample |
| 253 | |
| 254 | For more on how to install your module, @pxref{Installing Site |
| 255 | Packages}. |
| 256 | |
| 257 | |
| 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 |
| 268 | $ cat /usr/local/share/guile/site/math/bessel.scm |
| 269 | |
| 270 | (define-module (math bessel) |
| 271 | #:export (j0)) |
| 272 | |
| 273 | (load-extension "libguile-bessel" "init_bessel") |
| 274 | |
| 275 | $ file /usr/local/lib/guile/@value{EFFECTIVE-VERSION}/extensions/libguile-bessel.so |
| 276 | @dots{} ELF 32-bit LSB shared object @dots{} |
| 277 | $ guile |
| 278 | scheme@@(guile-user)> (use-modules (math bessel)) |
| 279 | scheme@@(guile-user)> (j0 2) |
| 280 | $1 = 0.223890779141236 |
| 281 | @end smallexample |
| 282 | |
| 283 | @xref{Modules and Extensions}, for more information. |
| 284 | |
| 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 | |
| 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. |
| 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 | |
| 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 | |
| 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 |
| 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. |
| 346 | |
| 347 | @item |
| 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}. |
| 352 | |
| 353 | @example |
| 354 | $ build-aux/config.guess |
| 355 | x86_64-unknown-linux-gnu |
| 356 | @end example |
| 357 | |
| 358 | @item |
| 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}. |
| 362 | |
| 363 | @item |
| 364 | If you built Guile yourself, the build configuration that you used: |
| 365 | |
| 366 | @example |
| 367 | $ ./config.status --config |
| 368 | '--enable-error-on-warning' '--disable-deprecated'... |
| 369 | @end example |
| 370 | |
| 371 | @item |
| 372 | A complete description of how to reproduce the bug. |
| 373 | |
| 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. |
| 377 | |
| 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. |
| 380 | |
| 381 | @item |
| 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." |
| 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 |
| 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 |
| 391 | |
| 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. |
| 399 | |
| 400 | |
| 401 | |
| 402 | @c Local Variables: |
| 403 | @c TeX-master: "guile.texi" |
| 404 | @c End: |