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   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_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 `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
 185 @node Using the Guile Module System
 186 @subsection Using the Guile Module System
 187
 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.
 191
 192 For more details on the module system beyond this introductory material,
 193 @xref{Modules}.
 194
 195 @menu
 196 * Using Modules::
 197 * Writing new Modules::
 198 * Putting Extensions into Modules::
 199 @end menu
 200
 201
 202 @node Using Modules
 203 @subsubsection Using Modules
 204
 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
 208 installed manually.
 209
 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}.
 214
 215 @smallexample
 216 $ guile
 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)
 221 $1 = "total 30"
 222 scheme@@(guile-user)> (read-line p)
 223 $2 = "drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"
 224 @end smallexample
 225
 226 @node Writing new Modules
 227 @subsubsection Writing new Modules
 228
 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.
 232
 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.
 236
 237 @smallexample
 238 $ cat /usr/local/share/guile/foo/bar.scm
 239
 240 (define-module (foo bar)
 241   #:export (frob))
 242
 243 (define (frob x) (* 2 x))
 244
 245 $ guile
 246 scheme@@(guile-user)> (use-modules (foo bar))
 247 scheme@@(guile-user)> (frob 12)
 248 $1 = 24
 249 @end smallexample
 250
 251 @node Putting Extensions into Modules
 252 @subsubsection Putting Extensions into Modules
 253
 254 In addition to Scheme code you can also put things that are defined in
 255 C into a module.
 256
 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.
 259
 260 @smallexample
 261 $ cat /usr/local/share/guile/math/bessel.scm
 262
 263 (define-module (math bessel)
 264   #:export (j0))
 265
 266 (load-extension "libguile-bessel" "init_bessel")
 267
 268 $ file /usr/local/lib/libguile-bessel.so
 269 @dots{} ELF 32-bit LSB shared object @dots{}
 270 $ guile
 271 scheme@@(guile-user)> (use-modules (math bessel))
 272 scheme@@(guile-user)> (j0 2)
 273 $1 = 0.223890779141236
 274 @end smallexample
 275
 276 @xref{Modules and Extensions}, for more information.
 277
 278 @lowersections
 279
 280 @node Reporting Bugs
 281 @section Reporting Bugs
 282
 283 Any problems with the installation should be reported to
 284 @email{bug-guile@@gnu.org}.
 285
 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
 289 Guile yourself.
 290
 291 Before sending in bug reports, please check with the following list that
 292 you really have found a bug.
 293
 294 @itemize @bullet
 295 @item
 296 Whenever documentation and actual behavior differ, you have certainly
 297 found a bug, either in the documentation or in the program.
 298
 299 @item
 300 When Guile crashes, it is a bug.
 301
 302 @item
 303 When Guile hangs or takes forever to complete a task, it is a bug.
 304
 305 @item
 306 When calculations produce wrong results, it is a bug.
 307
 308 @item
 309 When Guile signals an error for valid Scheme programs, it is a bug.
 310
 311 @item
 312 When Guile does not signal an error for invalid Scheme programs, it may
 313 be a bug, unless this is explicitly documented.
 314
 315 @item
 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.
 318 @end itemize
 319
 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.
 328
 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.
 333
 334 @itemize @bullet
 335 @item
 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
 338 within Guile.
 339
 340 @item
 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}.
 345
 346 @example
 347 $ build-aux/config.guess
 348 x86_64-unknown-linux-gnu
 349 @end example
 350
 351 @item
 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}.
 355
 356 @item
 357 If you built Guile yourself, the build configuration that you used:
 358
 359 @example
 360 $ ./config.status --config
 361 '--enable-error-on-warning' '--disable-deprecated'...
 362 @end example
 363
 364 @item
 365 A complete description of how to reproduce the bug.
 366
 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.
 370
 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.
 373
 374 @item
 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."
 378
 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.
 383 @end itemize
 384
 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
 391 your report.
 392
 393
 394
 395 @c Local Variables:
 396 @c TeX-master: "guile.texi"
 397 @c End: