[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Programming work ] | [ > ] |
7.6 Debugging LilyPond
The most commonly used tool for debugging LilyPond is the GNU debugger gdb. Use of gdb is described in this section.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < Debugging LilyPond ] | [ Up : Debugging LilyPond ] | [ > ] |
7.6.1 Debugging overview
Using a debugger simplifies troubleshooting in at least two ways.
First, breakpoints can be set to pause execution at any desired point. Then, when execution has paused, debugger commands can be issued to explore the values of various variables or to execute functions.
Second, the debugger allows the display of a stack trace, which shows the sequence in which functions are called and the arguments to the various function calls.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Debugging LilyPond ] | [ > ] |
7.6.2 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 ...
TODO – get good description here, or perhaps add debugging compile to AU1.1 as it comes to CG and just use a reference here.
TODO – Test the following to make sure it is true.
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 ...
TODO – get compiling description for guile here.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Debugging LilyPond ] | [ > ] |
7.6.3 Typical gdb usage
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Debugging LilyPond ] | [ > ] |
7.6.4 Typical .gdbinit files
The behavior of gdb can be readily customized through the use of .gdbinit files. A .gdbinit file is a file named .gdbinit (notice the “.” at the beginning of the file name) that is placed in a user’s home directory.
The .gdbinit file below is from Han-Wen. It sets breakpoints for all errors and defines functions for displaying scheme objects (ps), grobs (pgrob), and parsed music expressions (pmusic).
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
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Debugging LilyPond ] | [ Release work > ] |
7.6.5 Using Guile interactively with LilyPond
In order to experiment with Scheme programming in the LilyPond environment, it is convenient to have a Guile interpreter that has all the LilyPond modules loaded. This requires the following steps.
First, define a Scheme symbol for the active module in the .ly file:
#(module-define! (resolve-module '(guile-user)) 'lilypond-module (current-module))
Second, place a Scheme function in the .ly file that gives an interactive Guile prompt:
#(top-repl)
When the .ly file is compiled, this causes the compilation to be interrupted and an interactive guile prompt to appear. When the guile prompt appears, the LilyPond active module must be set as the current guile module:
guile> (set-current-module lilypond-module)
Proper operation of these commands can be demonstrated by typing the name of a LilyPond public scheme function to see if it’s properly defined:
guile> fret-diagram-verbose-markup #<procedure fret-diagram-verbose-markup (layout props marking-list)>
If the LilyPond module has not been correctly loaded, an error message will be generated:
guile> fret-diagram-verbose-markup ERROR: Unbound variable: fret-diagram-verbose-markup ABORT: (unbound-variable)
Once the module is properly loaded, any valid LilyPond Scheme expression can be entered at the interactive prompt.
After the investigation is complete, the interactive guile interpreter can be exited:
guile> (quit)
The compilation of the .ly file will then continue.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Debugging LilyPond ] | [ Release work > ] |