7.5 Debugging LilyPond

The most commonly used tool for debugging LilyPond is the GNU debugger gdb. Use of gdb is described in this section.


7.5.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.


7.5.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.


7.5.3 Typical gdb usage


7.5.4 Typical .gdbinit files

The behavior of gdb can be readily customized through the use of .gdbinit files. The 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 


Contributor’s Guide