From: Carl Sorensen <c_sorensen@byu.edu>
Date: Wed, 1 Jul 2009 14:17:52 +0000 (-0600)
Subject: Add guile debugging information
X-Git-Tag: release/2.13.3-0~1
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=5a3c2d8bc13549a9a304345f4be6feabe55ce5ab;p=lilypond.git

Add guile debugging information
---

diff --git a/Documentation/devel/programming-work.itexi b/Documentation/devel/programming-work.itexi
index 900d0a6846..a50ec66723 100644
--- a/Documentation/devel/programming-work.itexi
+++ b/Documentation/devel/programming-work.itexi
@@ -560,18 +560,53 @@ various function calls.
 @subsection Compiling with debugging information
 
 In order to use a debugger with LilyPond, it is necessary to compile
-LilyPond with debugging information.  This is accomplished by ...
+LilyPond with debugging information.  This is accomplished by running
+the following commands in the main LilyPond source directory.
 
-TODO -- get good description here, or perhaps add debugging compile
-to AU1.1 as it comes to CG and just use a reference here.
+@example
+./configure  --disable-optimization
+
+make
+@end example
+
+This will create a version of LilyPond that contains the debugging
+information that will allow the debugger to tie the source code
+to the compiled code.
+
+You should not do @var{make install} if you want to use a debugger
+with LilyPond.  @var{make install} will strip the debugging information
+from the LilyPond binary.
 
-TODO -- Test the following to make sure it is true.
+To set breakpoints in Scheme functions, put
 
-If you want to be able to set breakpoints in Scheme functions, it is
-necessary to compile guile with debugging information.  This is done
-by ...
+@example
+\include "guile-debugger.ly"
+@end example
+
+in your input file after any scheme procedures you have defined in
+that file.  When your input file is processed, a guile prompt
+will be displayed.  At the guile prompt, you can set breakpoints with
+the @code{break!} procedure:
 
-TODO -- get compiling description for guile here.
+@example
+guile> (break! my-scheme-procedure)
+@end example
+
+Once you have set the desired breakpoints, you exit the guile repl frame
+by typing:
+
+@example
+guile> (quit)
+@end example
+
+When one of the scheme routines for which you have set breakpoints is
+entered, guile will interrupt execution in a debug frame.  At this point,
+you will have access to guile debugging commands.  For a listing of these
+commands, type:
+
+@example
+debug> help
+@end example
 
 @subsection Typical gdb usage
 
@@ -580,7 +615,7 @@ TODO -- get compiling description for guile here.
 The behavior of gdb can be readily customized through the use of
 @var{.gdbinit} files.  A @var{.gdbinit} file is a file named
 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
-  that is placed in a user's home directory.
+that is placed in a user's home directory.
 
 The @var{.gdbinit} file below is from Han-Wen.  It sets breakpoints
 for all errors and defines functions for displaying scheme objects
@@ -588,24 +623,23 @@ for all errors and defines functions for displaying scheme objects
 
 @example
 file lily/out/lilypond
-b scm_error
 b programming_error
 b Grob::programming_error
 
 define ps
    print ly_display_scm($arg0)
-  end
-  define pgrob
-     print ly_display_scm($arg0->self_scm_)
-     print ly_display_scm($arg0->mutable_property_alist_)
-     print ly_display_scm($arg0->immutable_property_alist_)
-     print ly_display_scm($arg0->object_alist_)
-  end
-  define pmusic
-     print ly_display_scm($arg0->self_scm_)
-     print ly_display_scm($arg0->mutable_property_alist_)
-     print ly_display_scm($arg0->immutable_property_alist_)
-  end
+end
+define pgrob
+  print ly_display_scm($arg0->self_scm_)
+  print ly_display_scm($arg0->mutable_property_alist_)
+  print ly_display_scm($arg0->immutable_property_alist_)
+  print ly_display_scm($arg0->object_alist_)
+end
+define pmusic
+  print ly_display_scm($arg0->self_scm_)
+  print ly_display_scm($arg0->mutable_property_alist_)
+  print ly_display_scm($arg0->immutable_property_alist_)
+end
 @end example
 
 @subsection Using Guile interactively with LilyPond
diff --git a/ly/guile-debugger.ly b/ly/guile-debugger.ly
new file mode 100644
index 0000000000..26179d1178
--- /dev/null
+++ b/ly/guile-debugger.ly
@@ -0,0 +1,36 @@
+%%%% guile-debugger.ly
+%%%%
+%%%% Source file of the GNU LilyPond music typesetter
+%%%%
+%%%% (c) 2009 by Ian Hulin <ian@hulin.org.uk>
+
+%%  \include this file to enable the setting of breakpoints in guile.
+%%  Once loaded, this file will open a guile debug prompt.  Type
+%%  help
+%%  at the debug prompt to get a list of possible commands.
+%%  For more information, see the Contributors' Guide.
+
+
+\version "2.13.0"
+
+#(use-modules (ice-9 debugger) (ice-9 debugging trace) (ice-9 debugging steps) (ice-9 debugging ice-9-debugger-extensions)  )
+
+#(define (break! proc)
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour debug-trap)))
+     
+#(define (trace! proc)
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-at-exit))))
+     
+#(define (trace-subtree! proc)
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-until-exit))))
+#(module-define! (resolve-module '(guile-user)) 'lilypond-module (current-module))
+#(top-repl)
+#(set-current-module lilypond-module)