+@subsection Using the Guile debugger
+
+To set breakpoints and/or enable tracing in Scheme functions, put
+
+@example
+\include "guile-debugger.ly"
+@end example
+
+in your input file after any scheme procedures you have defined in
+that file.
+This will invoke the Guile command-line and have set up the environment for the debug
+command lines.
+When your input file is processed, a guile prompt will be displayed.
+You may now enter commands to set up breakpoints and enable tracing by the Guile debugger.
+
+@subsection Using Breakpoints
+
+At the guile prompt, you can set breakpoints with
+the @code{set-break!} procedure:
+
+@example
+guile> (set-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
+
+Alternatively you may code the breakpoints in your Lilypond source file using a command
+such as:
+@example
+#(set-break! my-scheme-procedure)
+@end example
+immediately after the @code{\include} statement. In this case the breakpoint will be set
+straight after you enter the @code{(quit)} command at the guile prompt.
+
+Embedding breakpoint commands like this is particularly useful if you want to look at how
+the Scheme procedures in the @var{.scm} files supplied with LilyPond work.
+
+In this case you can edit the file in the relevant directory to add this line near the top:
+
+@example
+(use-modules (scm guile-debugger)
+@end example
+Now you can set a breakpoint after the procedure you are interested in has been declared.
+For example if you are working on routines called by @var{print-book-with} in
+@var{lily-library.scm}:
+
+@example
+(define (print-book-with parser book process-procedure)
+ (let* ((paper (ly:parser-lookup parser '$defaultpaper))
+ (layout (ly:parser-lookup parser '$defaultlayout))
+ (outfile-name (get-outfile-name parser)))
+ (process-procedure book paper layout outfile-name)))
+
+(define-public (print-book-with-defaults parser book)
+ (print-book-with parser book ly:book-process))
+
+(define-public (print-book-with-defaults-as-systems parser book)
+ (print-book-with parser book ly:book-process-to-systems))
+
+@end example
+
+At this point in the code you could add this to set a breakpoint at print-book-with:
+
+@example
+
+(set-break print-book-with)
+
+@end example
+
+@strong{Tracing}
+
+In the above example you will note that trace-points have also been set. There are two
+forms of trace available:
+
+@example
+(set-trace! my-scheme-procedure)
+@end example
+and
+@example
+(set-trace-subtree! my-scheme-procedure)
+@end example
+
+@code{set-trace!} allows Scheme to log a line to the standard output to show when the
+procedure is called and when it exits. @code{set-trace-subtree!} traces each line in the
+body of the procedure as it is executed.
+
projects / lilypond.git / commitdiff