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.


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.


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.


7.6.3 Typical gdb usage


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

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.


Contributor’s Guide