mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-02 04:40:29 +02:00
Code Activity

This commit was manufactured by cvs2svn to create branch

Browse source 
'branch_release-1-6'.
This commit is contained in:
cvs2svn 2002-01-02 23:56:18 +00:00
commit 7cdc2b1058
3 changed files with 389 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

123
doc/ref/autoconf.texi Normal file
View file

@ -0,0 +1,123 @@
@page
@node Autoconf Support
@chapter Autoconf Support
When Guile is installed, a set of autoconf macros is also installed as
PREFIX/share/aclocal/guile.m4. This chapter documents the macros provided in
that file. @xref{Top,The GNU Autoconf Manual,,autoconf}, for more info.
@menu
* Autoconf Background:: Why use autoconf?
* Autoconf Macros:: The GUILE_* macros.
* Using Autoconf Macros:: How to use them, plus examples.
@end menu
@node Autoconf Background
@section Autoconf Background
As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
package needs configuration at build-time. If your package uses Guile (or
uses a package that in turn uses Guile), you probably need to know what
specific Guile features are available and details about them.
The way to do this is to write feature tests and arrange for their execution
by the @file{configure} script, typically by adding the tests to
@file{configure.ac}, and running @code{autoconf} to create @file{configure}.
Users of your package then run @file{configure} in the normal way.
Macros are a way to make common feature tests easy to express. Autoconf
provides a wide range macros (@pxref{Existing Tests,,,autoconf}), and Guile
installation provides Guile-specific tests in the areas of: program detection,
compilation flags reporting, and Scheme module checks.
@node Autoconf Macros
@section Autoconf Macros
The macro names all begin with "GUILE_".
@c see Makefile.am
@include autoconf-macros.texi
@node Using Autoconf Macros
@section Using Autoconf Macros
Using the autoconf macros is straightforward: Add the macro "calls" (actually
instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
run @code{autoconf}. If your system doesn't have guile.m4 installed, place
the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
and @code{aclocal} will do the right thing.
Some of the macros can be used inside normal shell constructs: @code{if foo ;
then GUILE_BAZ ; fi}, but this is not guaranteed. It's probably a good idea
to instantiate macros at top-level.
We now include two examples, one simple and one complicated.
The first example is for a package that uses libguile, and thus needs to know
how to compile and link against it. So we use @code{GUILE_FLAGS} to set the
vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
substituted in the Makefile.
@example
In configure.ac:
GUILE_FLAGS
In Makefile.in:
GUILE_CFLAGS = @@GUILE_CFLAGS@@
GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
myprog.o: myprog.c
$(CC) -o $@ $(GUILE_CFLAGS) $<
myprog: myprog.o
$(CC) -o $@ $< $(GUILE_LDFLAGS)
@end example
The second example is for a package of Guile Scheme modules that uses an
external program and other Guile Scheme modules (some might call this a "pure
scheme" package). So we use the @code{GUILE_SITE_DIR} macro, a regular
@code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
@example
In configure.ac:
GUILE_SITE_DIR
probably_wont_work=""
# pgtype pgtable
GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
test $have_guile_pg = no &&
probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
# gpgutils
AC_PATH_PROG(GNUPG,gpg)
test x"$GNUPG" = x &&
probably_wont_work="(my gpgutils) $probably_wont_work"
if test ! "$probably_wont_work" = "" ; then
p=" ***"
echo
echo "$p"
echo "$p NOTE:"
echo "$p The following modules probably won't work:"
echo "$p $probably_wont_work"
echo "$p They can be installed anyway, and will work if their"
echo "$p dependencies are installed later. Please see README."
echo "$p"
echo
fi
In Makefile.in:
instdir = @@GUILE_SITE@@/my
install:
$(INSTALL) my/*.scm $(instdir)
@end example
@c autoconf.texi ends here

181
doc/ref/debugging.texi Normal file
View file

@ -0,0 +1,181 @@
@page
@node Debugger User Interface
@chapter Debugger User Interface
@c --- The title and introduction of this appendix need to
@c distinguish this clearly from the chapter on the internal
@c debugging interface.
When debugging a program, programmers often find it helpful to examine
the program's internal status while it runs: the values of internal
variables, the choices made in @code{if} and @code{cond} statements, and
so forth. Guile Scheme provides a debugging interface that programmers
can use to single-step through Scheme functions and examine symbol
bindings. This is different from the @ref{Debugging}, which permits
programmers to debug the Guile interpreter itself. Most programmers
will be more interested in debugging their own Scheme programs than the
interpreter which evaluates them.
[FIXME: should we include examples of traditional debuggers
and explain why they can't be used to debug interpreted Scheme or Lisp?]
@menu
* Single-Step:: Execute a program or function one step at a time.
* Trace:: Print a report each time a given function is called.
* Backtrace:: See a list of the statements that caused an error.
* Stacks and Frames:: Examine the state of an interrupted program.
@end menu
@node Single-Step
@section Single-Step
@node Trace
@section Trace
When a function is @dfn{traced}, it means that every call to that
function is reported to the user during a program run. This can help a
programmer determine whether a function is being called at the wrong
time or with the wrong set of arguments.
@defun trace function
Enable debug tracing on @code{function}. While a program is being run, Guile
will print a brief report at each call to a traced function,
advising the user which function was called and the arguments that were
passed to it.
@end defun
@defun untrace function
Disable debug tracing for @code{function}.
@end defun
Example:
@lisp
(define (rev ls)
(if (null? ls)
'()
(append (rev (cdr ls))
(cons (car ls) '())))) @result{} rev
(trace rev) @result{} (rev)
(rev '(a b c d e))
@result{} [rev (a b c d e)]
| [rev (b c d e)]
| | [rev (c d e)]
| | | [rev (d e)]
| | | | [rev (e)]
| | | | | [rev ()]
| | | | | ()
| | | | (e)
| | | (e d)
| | (e d c)
| (e d c b)
(e d c b a)
(e d c b a)
@end lisp
Note the way Guile indents the output, illustrating the depth of
execution at each function call. This can be used to demonstrate, for
example, that Guile implements self-tail-recursion properly:
@lisp
(define (rev ls sl)
(if (null? ls)
sl
(rev (cdr ls)
(cons (car ls) sl)))) @result{} rev
(trace rev) @result{} (rev)
(rev '(a b c d e) '())
@result{} [rev (a b c d e) ()]
[rev (b c d e) (a)]
[rev (c d e) (b a)]
[rev (d e) (c b a)]
[rev (e) (d c b a)]
[rev () (e d c b a)]
(e d c b a)
(e d c b a)
@end lisp
Since the tail call is effectively optimized to a @code{goto} statement,
there is no need for Guile to create a new stack frame for each
iteration. Using @code{trace} here helps us see why this is so.
@node Backtrace
@section Backtrace
@node Stacks and Frames
@section Stacks and Frames
When a running program is interrupted, usually upon reaching an error or
breakpoint, its state is represented by a @dfn{stack} of suspended
function calls, each of which is called a @dfn{frame}. The programmer
can learn more about the program's state at the point of interruption by
inspecting and modifying these frames.
@deffn {Scheme Procedure} stack? obj
Return @code{#t} if @var{obj} is a calling stack.
@end deffn
@deffn {Scheme Procedure} make-stack
@end deffn
@deffn syntax start-stack id exp
Evaluate @var{exp} on a new calling stack with identity @var{id}. If
@var{exp} is interrupted during evaluation, backtraces will not display
frames farther back than @var{exp}'s top-level form. This macro is a
way of artificially limiting backtraces and stack procedures, largely as
a convenience to the user.
@end deffn
@deffn {Scheme Procedure} stack-id stack
Return the identifier given to @var{stack} by @code{start-stack}.
@end deffn
@deffn {Scheme Procedure} stack-ref
@end deffn
@deffn {Scheme Procedure} stack-length
@end deffn
@deffn {Scheme Procedure} frame?
@end deffn
@deffn {Scheme Procedure} last-stack-frame
@end deffn
@deffn {Scheme Procedure} frame-number
@end deffn
@deffn {Scheme Procedure} frame-source
@end deffn
@deffn {Scheme Procedure} frame-procedure
@end deffn
@deffn {Scheme Procedure} frame-arguments
@end deffn
@deffn {Scheme Procedure} frame-previous
@end deffn
@deffn {Scheme Procedure} frame-next
@end deffn
@deffn {Scheme Procedure} frame-real?
@end deffn
@deffn {Scheme Procedure} frame-procedure?
@end deffn
@deffn {Scheme Procedure} frame-evaluating-args?
@end deffn
@deffn {Scheme Procedure} frame-overflow
@end deffn

85
scripts/snarf-guile-m4-docs Executable file
View file

@ -0,0 +1,85 @@
#!/bin/sh
# aside from this initial boilerplate, this is actually -*- scheme -*- code
main='(module-ref (resolve-module '\''(scripts snarf-guile-m4-docs)) '\'main')'
exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
!#
;;; snarf-guile-m4-docs --- Parse guile.m4 comments for texi documentation
;; Copyright (C) 2002 Free Software Foundation, Inc.
;;
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this software; see the file COPYING. If not, write to
;; the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
;; Boston, MA 02111-1307 USA
;;; Author: Thien-Thi Nguyen <ttn@gnu.org>
;;; Commentary:
;; Usage: snarf-guile-m4-docs FILE
;;
;; Grep FILE for comments preceding macro definitions, massage
;; them into valid texi, and display to stdout. For each comment,
;; lines preceding "^# Usage:" are discarded.
;;
;; TODO: Generalize.
;;; Code:
(define-module (scripts snarf-guile-m4-docs)
:use-module (ice-9 rdelim)
:export (snarf-guile-m4-docs))
(define (display-texi lines)
(display "@deffn {Autoconf Macro}")
(for-each (lambda (line)
(display (if (string=? "#" (substring line 0 1))
(substring line 1)
line))
(newline))
lines)
(display "@end deffn")
(newline) (newline))
(define (prefix? line sub)
(false-if-exception
(string=? sub (substring line 0 (string-length sub)))))
(define (massage-usage line)
(let loop ((line (string->list line)) (acc '()))
(if (null? line)
(list (list->string (reverse acc)))
(loop (cdr line)
(cons (case (car line)
((#\( #\) #\,) #\space)
(else (car line)))
acc)))))
(define (snarf-guile-m4-docs . args)
(let* ((p (open-file (car args) "r"))
(next (lambda () (read-line p))))
(let loop ((line (next)) (acc #f))
(or (eof-object? line)
(cond ((prefix? line "# Usage:")
(loop (next) (massage-usage (substring line 8))))
((prefix? line "AC_DEFUN")
(display-texi (reverse acc))
(loop (next) #f))
((and acc (prefix? line "#"))
(loop (next) (cons line acc)))
(else
(loop (next) #f)))))))
(define main snarf-guile-m4-docs)
;;; snarf-guile-m4-docs ends here