[PATCH] Make Guile Debugger less flaky.

[Ian Hulin <ian@xxxxxxxxxxxx>]

Move break-point and trace routines to a separate .scm file.

Update Debugging Chapter in CG.
---
 Documentation/contributor/programming-work.itexi |   59 ++++++++++-------
 ly/guile-debugger.ly                             |   22 +++---
 scm/guile-debugger.scm                           |   74 ++++++++++++++++------
 3 files changed, 100 insertions(+), 55 deletions(-)

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index c2d7c20..d5efeca 100644
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -28,6 +28,7 @@ execution is found in Erik Sandberg's
 @uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
 thesis}.
 
+
 The first stage of LilyPond processing is @emph{parsing}.  In the parsing
 process, music expressions in LilyPond input format are converted to music
 expressions in Scheme format.  In Scheme format, a music expression is a list
@@ -710,12 +711,12 @@ $ gdb out/bin/lilypond
 @end example
 or you may use a graphical interface to gdb such as ddd
 @example
-$ gdb out/bin/lilypond
+$ ddd out/bin/lilypond
 @end example
-You can also use sets of standard gdb commands stored in a .gdbinit file (see next
+You can also use sets of standard gdb commands stored in a .gdbinit file (see next 
 section).
 
-
+ 
 @subsection Typical .gdbinit files
 
 The behavior of gdb can be readily customized through the use of a
@@ -896,7 +897,7 @@ At this point in the code you could add this to set a breakpoint at print-book-w
 
 @end example
 
-@strong{Tracing}
+@subsection Enabling Tracing
 
 In the above example you will note that trace-points have also been set.  There are two
 forms of trace available:
@@ -1122,7 +1123,7 @@ as a reference source for the patch.  Generally, this will be the
 SHA1 ID of origin/master, and in that case the command
 
 @example
-git cl upload origin/master
+git-cl upload origin/master
 @end example
 
 @noindent
@@ -1157,8 +1158,7 @@ to the left of the issue name.
 
 If the changes were in response to a feature request on the Google
 issue tracker for LilyPond, the author should change the status to
-Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was
-fixed in version x.y.z.  If
+@q{Fixed_x_y_z} where the patch was fixed in version x.y.z.  If
 the author does not have privileges to change the status, an email
 should be sent to bug-lilypond requesting the BugMeister to change
 the status.
@@ -1349,29 +1349,39 @@ foo = 1
 @end example
 
 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
-nested scope inside the @file{.ly} file-level scope.  @w{@code{foo = 1}}
-is translated in to a scheme variable definition.
+nested scope inside the .ly file-level scope.  @w{@code{foo = 1}} is
+translated in to a scheme variable definition.
 
 This implemented using modules, with each scope being an anonymous
 module that imports its enclosing scope's module.
 
-Lilypond's core, loaded from @file{.scm} files, is usually placed in the
-@code{lily} module, outside the @file{.ly} level.  In the case of
+The reason to put some functions (@qq{builtin}) outside the .ly level,
+is that in case of
 
 @example
 lilypond a.ly b.ly
 @end example
 
 @noindent
-we want to reuse the built-in definitions, without changes effected in
-user-level @file{a.ly} leaking into the processing of @file{b.ly}.
+we want to reuse the built-in definitions, without changes
+effected in a.ly leaking into the processing of b.ly.
+
+Maintaining this scoping when one .ly file can be included in another
+.ly file can be challenging.  A @code{define-public-toplevel} macro
+has been created in order to handle a difficulty caused by the modules
+being not the same when a .ly file is included into another.
+This provided a way to define all markup commands in the same module.
+At this time, we have found no easier way to define a function in a given
+module (not the current one) than to define this macro.
+
+With this architecture, the guile module system is not bypassed:
+module-define!, module-export!  and module-ref are all guile module
+primitives.
+
+A second reason for using this current architecture is to avoid memory
+leaks that could occur when running multiple files if toplevel
+functions were registered permanently.
 
-The user-accessible definition commands have to take care to avoid
-memory leaks that could occur when running multiple files.  All
-information belonging to user-defined commands and markups is stored in
-a manner that allows it to be garbage-collected when the module is
-dispersed, either by being stored module-locally, or in weak hash
-tables.
 
 @node LilyPond miscellany
 @section LilyPond miscellany
@@ -1402,7 +1412,7 @@ Spanners (derived class) -slurs, beams- or Items (also a derived
 class) -notes, clefs, etc.
 
 There are two other derived classes System (derived from Spanner,
-contaning a "line of music") and Paper_column (derived from Item, it
+containing a "line of music") and Paper_column (derived from Item, it
 contains all items that happen at the same moment). They are separate
 classes because they play a special role in the linebreaking process.
 
@@ -1582,8 +1592,8 @@ part-combine-status is part of such a synthetic event, used by
 Part_combine_iterator to communicate with Part_combine_engraver.
 
 
-@unnumberedsubsubsec I'm adding a property to affect how \autochange works.  It seems to
-me that it should be a context property, but the Scheme autochange
+@unnumberedsubsubsec I'm adding a property to affect how \autochange works.
+It seems to me that it should be a context property, but the Scheme autochange
 procecure has a Music argument.  Does this mean I should use
 a Music property?
 
@@ -1620,7 +1630,7 @@ hit the breakpoint, do a backtrace. You can inspect Scheme objects
 along the way by doing
 
 @example
-p ly_display_scm(obj)
+bp ly_display_scm(obj)
 @end example
 
 this will display OBJ through GUILE.
@@ -1630,7 +1640,7 @@ this will display OBJ through GUILE.
 Ian Hulin was trying to do some debugging in music functions, and
 came up with the following question
 
-HI all,
+Hi all,
 I'm working on the Guile Debugger Stuff, and would like to try
 debugging a music function definition such as:
 
@@ -1649,6 +1659,7 @@ equivalent of a Scheme
 @noindent
 although something gets defined because Scheme apparently recognizes
 
+
 @example
 #(set-break! conditionalMark)
 @end example
diff --git a/ly/guile-debugger.ly b/ly/guile-debugger.ly
index 401aff9..be61226 100644
--- a/ly/guile-debugger.ly
+++ b/ly/guile-debugger.ly
@@ -23,28 +23,28 @@
 %%  at the debug prompt to get a list of possible commands.
 %%  For more information, see the Contributor's Guide.
 
-
-\version "2.13.10"
-
-% define lilypond-module as a variable in the guile-user module and set to the current
-% Scheme module (which will be the lilypond top-level
-% module)
-
+\version "2.13.4"
+% define lilypond-module as a variable in the guile-user module set to the current Scheme module
+% (which will be the lilypond top-level module)
+%
 #(module-define! (resolve-module '(guile-user))
-                 'lilypond-module
-                 (current-module))
+                 'lilypond-module (current-module))
 %
 % Ensure we have command-line recall available at guile> prompt
 %
 #(use-modules (ice-9 readline))
 #(activate-readline)
 #(display "\n Guile debugger for Lilypond\n")
-#(use-modules (scm guile-debugger))
 #(newline)
+%
+% Ensure debugger definitions are available in lilypond-module and guile-user
+%
+#(use-modules (scm guile-debugger))
+#(debug-help)
+#(ly:module-copy (resolve-module '(guile-user)) (resolve-module '(scm guile-debugger)))
 #(top-repl)
 %
 % top-repl has re-set the module to guile-user,
 %  so we need to set it back to lilypond-module
 %
-#(ly:module-copy (current-module) (resolve-module '(lilypond-module)))
 #(set-current-module lilypond-module)
diff --git a/scm/guile-debugger.scm b/scm/guile-debugger.scm
index 809f01e..52b7997 100755
--- a/scm/guile-debugger.scm
+++ b/scm/guile-debugger.scm
@@ -15,28 +15,62 @@
 ;;;; You should have received a copy of the GNU General Public License
 ;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
 
-(define-module (scm guile-debugger)
-  #:use-module (ice-9 debugger)
-  #:use-module (ice-9 debugging traps)
-  #:use-module (ice-9 debugging trace)
-  #:use-module (ice-9 debugging steps)
-  #:use-module (ice-9 debugging ice-9-debugger-extensions)
-  #:use-module (ice-9 readline)
-  #:export (set-break! set-trace! set-trace-subtree!))
+(define-module ( scm guile-debugger)  
+  #:use-module  (ice-9 debugger) 
+  #:use-module  (ice-9 debugging traps)
+  #:use-module  (ice-9 debugging trace)
+  #:use-module  (ice-9 debugging steps) 
+  #:use-module  (ice-9 debugging ice-9-debugger-extensions) 
+  #:use-module  (ice-9 readline)
+  #:export     (set-break!
+                clear-break!
+                set-trace-call!
+                clear-trace-call!
+                set-trace-subtree!
+                clear-trace-subtree!
+                debug-help))
 
 (define (set-break! proc)
-  (install-trap (make <procedure-trap>
-		      #:procedure proc
-		      #:behaviour debug-trap)))
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour debug-trap)))
+(define (clear-break! proc)
+       (uninstall-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour debug-trap)))
 
-(define (set-trace! proc)
-  (install-trap (make <procedure-trap>
-		      #:procedure proc
-		      #:behaviour (list trace-trap
-					trace-at-exit))))
+
+(define (set-trace-call! proc)
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-at-exit))))
+(define (clear-trace-call! proc)
+       (uninstall-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-at-exit))))
 
 (define (set-trace-subtree! proc)
-  (install-trap (make <procedure-trap>
-		      #:procedure proc
-		      #:behaviour (list trace-trap
-					trace-until-exit))))
+       (install-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-until-exit))))
+
+(define (clear-trace-subtree! proc)
+       (uninstall-trap (make <procedure-trap>
+                       #:procedure proc
+                       #:behaviour (list trace-trap
+                                         trace-until-exit))))
+
+(define (debug-help )
+    (display "You may add the following commands as debugging statements in your source file:\n\n")
+    (display "\t set-break! <procedure> \t\tto cause guile to halt on a call to <procedure>\n")
+    (display "\t clear-break! <procedure> \t\tto disable a breakpoint previously set on a call to <procedure>\n")
+    (display "\t set-trace-call! <procedure> \t\tScheme will print out a line when it enters or exits <procedure>\n")
+    (display "\t clear-trace-call! <procedure> \t\tScheme will no longer print out a line when it enters or exits <procedure>\n")
+    (display "\t set-trace-subtree! <procedure> \tto display each line of Scheme code executed during a call to <procedure>\n")
+    (display "\t clear-trace-subtree! <procedure> \tto turn off tracing code during calls to <procedure>\n\n")
+    (display "\t- use (set-current-module lilypond-module)\n")
+    (display "\t  to access your procedures or Lilypond Procedures")
+    (newline))
-- 
1.6.3.3


--------------070602080907050909020503--

---
----
Join the Frogs!