doc/ref/tour.texi

   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: