diff options
-rw-r--r-- | doc/ref/debugging.texi | 181 | ||||
-rw-r--r-- | doc/ref/program.texi | 276 |
2 files changed, 0 insertions, 457 deletions
diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi deleted file mode 100644 index 45fef5082..000000000 --- a/doc/ref/debugging.texi +++ /dev/null @@ -1,181 +0,0 @@ -@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 diff --git a/doc/ref/program.texi b/doc/ref/program.texi deleted file mode 100644 index 61aa69096..000000000 --- a/doc/ref/program.texi +++ /dev/null @@ -1,276 +0,0 @@ -@page -@node Programming Overview -@chapter An Overview of Guile Programming - -Guile is designed as an extension language interpreter that is -straightforward to integrate with applications written in C (and C++). -The big win here for the application developer is that Guile -integration, as the Guile web page says, ``lowers your project's -hacktivation energy.'' Lowering the hacktivation energy means that you, -as the application developer, @emph{and your users}, reap the benefits -that flow from being able to extend the application in a high level -extension language rather than in plain old C. - -Underlying this argument is the assumption that programming in a high -level language, specifically Guile's implementation of Scheme, is -necessarily better in some way than programming in C. What do we mean -by this claim, and how can we be so sure? - -One class of advantages applies not only to Scheme, but more generally -to any interpretable, high level, scripting language, such as Emacs -Lisp, Python, Ruby, or @TeX{}'s macro language. Common features of all -such languages, when compared to C, are that: - -@itemize @bullet -@item -They lend themselves to rapid and experimental development cycles, -owing usually to a combination of their interpretability and the -integrated development environment in which they are used. - -@item -They free developers from some of the low level bookkeeping tasks -associated with C programming, notably memory management. - -@item -They provide high level features such as container objects and exception -handling that make common programming tasks easier. -@end itemize - -In the case of Scheme, further features that make programming easier --- -and more fun! --- are its powerful mechanisms for abstracting parts of -programs (closures --- @pxref{About Closure}) and for iteration -(@pxref{while do}). - -The evidence in support of this argument is empirical: the huge amount -of code that has been written in extension languages for applications -that support this mechanism. Most notable are extensions written in -Emacs Lisp for GNU Emacs, in @TeX{}'s macro language for @TeX{}, and in -Script-Fu for the Gimp, but there is increasingly now a significant code -eco-system for Guile-based applications as well, such as Lilypond and -GnuCash. It is close to inconceivable that similar amounts of -functionality could have been added to these applications just by -writing new code in their base implementation languages. - -@menu -* Testbed Example:: Example: using Guile in a testbed. -* Programming Options:: Options for Guile programming. -* User Programming:: How about application users? -@end menu - - -@node Testbed Example -@section Example: Using Guile for an Application Testbed - -As an example of what this means in practice, imagine writing a testbed -for an application that is tested by submitting various requests (via a -C interface) and validating the output received. Suppose further that -the application keeps an idea of its current state, and that the -``correct'' output for a given request may depend on the current -application state. A complete ``white box''@footnote{A @dfn{white box} -test plan is one that incorporates knowledge of the internal design of -the application under test.} test plan for this application would aim to -submit all possible requests in each distinguishable state, and validate -the output for all request/state combinations. - -To write all this test code in C would be very tedious. Suppose instead -that the testbed code adds a single new C function, to submit an -arbitrary request and return the response, and then uses Guile to export -this function as a Scheme procedure. The rest of the testbed can then -be written in Scheme, and so benefits from all the advantages of -programming in Scheme that were described in the previous section. - -(In this particular example, there is an additional benefit of writing -most of the testbed in Scheme. A common problem for white box testing -is that mistakes and mistaken assumptions in the application under test -can easily be reproduced in the testbed code. It is more difficult to -copy mistakes like this when the testbed is written in a different -language from the application.) - - -@node Programming Options -@section A Choice of Programming Options - -The preceding arguments and example point to a model of Guile -programming that is applicable in many cases. According to this model, -Guile programming involves a balance between C and Scheme programming, -with the aim being to extract the greatest possible Scheme level benefit -from the least amount of C level work. - -The C level work required in this model usually consists of packaging -and exporting functions and application objects such that they can be -seen and manipulated on the Scheme level. To help with this, Guile's C -language interface includes utility features that aim to make this kind -of integration very easy for the application developer. These features -are documented later in this part of the manual: see REFFIXME. - -This model, though, is really just one of a range of possible -programming options. If all of the functionality that you need is -available from Scheme, you could choose instead to write your whole -application in Scheme (or one of the other high level languages that -Guile supports through translation), and simply use Guile as an -interpreter for Scheme. (In the future, we hope that Guile will also be -able to compile Scheme code, so lessening the performance gap between C -and Scheme code.) Or, at the other end of the C--Scheme scale, you -could write the majority of your application in C, and only call out to -Guile occasionally for specific actions such as reading a configuration -file or executing a user-specified extension. The choices boil down to -two basic questions: - -@itemize @bullet -@item -Which parts of the application do you write in C, and which in Scheme -(or another high level translated language)? - -@item -How do you design the interface between the C and Scheme parts of your -application? -@end itemize - -These are of course design questions, and the right design for any given -application will always depend upon the particular requirements that you -are trying to meet. In the context of Guile, however, there are some -generally applicable considerations that can help you when designing -your answers. - -@menu -* Available Functionality:: What functionality is already available? -* Basic Constraints:: Functional and performance constraints. -* Style Choices:: Your preferred programming style. -* Program Control:: What controls program execution? -@end menu - - -@node Available Functionality -@subsection What Functionality is Already Available? - -Suppose, for the sake of argument, that you would prefer to write your -whole application in Scheme. Then the API available to you consists of: - -@itemize @bullet -@item -standard Scheme - -@item -plus the extensions to standard Scheme provided by -Guile in its core distribution - -@item -plus any additional functionality that you or others have packaged so -that it can be loaded as a Guile Scheme module. -@end itemize - -A module in the last category can either be a pure Scheme module --- in -other words a collection of utility procedures coded in Scheme --- or a -module that provides a Scheme interface to an extension library coded in -C --- in other words a nice package where someone else has done the work -of wrapping up some useful C code for you. The set of available modules -is growing quickly and already includes such useful examples as -@code{(gtk gtk)}, which makes Gtk+ drawing functions available in -Scheme, and @code{(database postgres)}, which provides SQL access to a -Postgres database. - -Given the growing collection of pre-existing modules, it is quite -feasible that your application could be implemented by combining a -selection of these modules together with new application code written in -Scheme. - -If this approach is not enough, because the functionality that your -application needs is not already available in this form, and it is -impossible to write the new functionality in Scheme, you will need to -write some C code. If the required function is already available in C -(e.g. in a library), all you need is a little glue to connect it to the -world of Guile. If not, you need both to write the basic code and to -plumb it into Guile. - -In either case, two general considerations are important. Firstly, what -is the interface by which the functionality is presented to the Scheme -world? Does the interface consist only of function calls (for example, -a simple drawing interface), or does it need to include @dfn{objects} of -some kind that can be passed between C and Scheme and manipulated by -both worlds. Secondly, how does the lifetime and memory management of -objects in the C code relate to the garbage collection governed approach -of Scheme objects? In the case where the basic C code is not already -written, most of the difficulties of memory management can be avoided by -using Guile's C interface features from the start. - -For the full documentation on writing C code for Guile and connecting -existing C code to the Guile world, see REFFIXME. - - -@node Basic Constraints -@subsection Functional and Performance Constraints - - -@node Style Choices -@subsection Your Preferred Programming Style - - -@node Program Control -@subsection What Controls Program Execution? - - -@node User Programming -@section How About Application Users? - -So far we have considered what Guile programming means for an -application developer. But what if you are instead @emph{using} an -existing Guile-based application, and want to know what your -options are for programming and extending this application? - -The answer to this question varies from one application to another, -because the options available depend inevitably on whether the -application developer has provided any hooks for you to hang your own -code on and, if there are such hooks, what they allow you to -do.@footnote{Of course, in the world of free software, you always have -the freedom to modify the application's source code to your own -requirements. Here we are concerned with the extension options that the -application has provided for without your needing to modify its source -code.} For example@dots{} - -@itemize @bullet -@item -If the application permits you to load and execute any Guile code, the -world is your oyster. You can extend the application in any way that -you choose. - -@item -A more cautious application might allow you to load and execute Guile -code, but only in a @dfn{safe} environment, where the interface -available is restricted by the application from the standard Guile API. - -@item -Or a really fearful application might not provide a hook to really -execute user code at all, but just use Scheme syntax as a convenient way -for users to specify application data or configuration options. -@end itemize - -In the last two cases, what you can do is, by definition, restricted by -the application, and you should refer to the application's own manual to -find out your options. - -The most well known example of the first case is Emacs, with its -extension language Emacs Lisp: as well as being a text editor, Emacs -supports the loading and execution of arbitrary Emacs Lisp code. The -result of such openness has been dramatic: Emacs now benefits from -user-contributed Emacs Lisp libraries that extend the basic editing -function to do everything from reading news to psychoanalysis and -playing adventure games. The only limitation is that extensions are -restricted to the functionality provided by Emacs's built-in set of -primitive operations. For example, you can interact and display data by -manipulating the contents of an Emacs buffer, but you can't pop-up and -draw a window with a layout that is totally different to the Emacs -standard. - -This situation with a Guile application that supports the loading of -arbitrary user code is similar, except perhaps even more so, because -Guile also supports the loading of extension libraries written in C. -This last point enables user code to add new primitive operations to -Guile, and so to bypass the limitation present in Emacs Lisp. - -At this point, the distinction between an application developer and an -application user becomes rather blurred. Instead of seeing yourself as -a user extending an application, you could equally well say that you are -developing a new application of your own using some of the primitive -functionality provided by the original application. As such, all the -discussions of the preceding sections of this chapter are relevant to -how you can proceed with developing your extension. |