[ << Programming work ]	[Top][Contents][Index][ ? ]			[ Release work >> ]
[ < Debugging Scheme code ]		[  Up : Programming work ]	[ Adding or modifying features > ]

10.8 Tracing object relationships

Understanding the LilyPond source often boils down to figuring out what is happening to the Grobs. Where (and why) are they being created, modified and destroyed? Tracing Lily through a debugger in order to identify these relationships can be time-consuming and tedious.

In order to simplify this process, a facility has been added to display the grobs that are created and the properties that are set and modified. Although it can be complex to get set up, once set up it easily provides detailed information about the life of grobs in the form of a network graph.

Each of the steps necessary to use the graphviz utility is described below.

1. Installing graphviz

   In order to create the graph of the object relationships, it is first necessary to install Graphviz. Graphviz is available for a number of different platforms:

   http://www.graphviz.org/Download..php
   

2. Modifying config.make

   In order for the Graphviz tool to work, config.make must be modified. It is probably a good idea to first save a copy of config.make under a different name. Then, edit config.make by removing every occurrence of ‘-DNDEBUG’.

3. Rebuilding LilyPond

   The executable code of LilyPond must be rebuilt from scratch:

   make -C lily clean && make -C lily
   

4. Create a graphviz-compatible ‘.ly’ file

   In order to use the graphviz utility, the ‘.ly’ file must include ‘ly/graphviz-init.ly’, and should then specify the grobs and symbols that should be tracked. An example of this is found in ‘input/regression/graphviz.ly’.

5. Run lilypond with output sent to a log file

   The Graphviz data is sent to stderr by lilypond, so it is necessary to redirect stderr to a logfile:

   lilypond graphviz.ly 2> graphviz.log
   

6. Edit the logfile

   The logfile has standard lilypond output, as well as the Graphviz output data. Delete everything from the beginning of the file up to but not including the first occurrence of digraph.

   Also, delete the final lilypond message about success from the end of the file.

7. Process the logfile with dot

   The directed graph is created from the log file with the program dot:

   dot -Tpdf graphviz.log > graphviz.pdf
   

The pdf file can then be viewed with any pdf viewer.

When compiled without ‘-DNDEBUG’, lilypond may run slower than normal. The original configuration can be restored by either renaming the saved copy of config.make or rerunning configure. Then rebuild lilypond with

make -C lily clean && make -C lily

---

[ << Programming work ]	[Top][Contents][Index][ ? ]			[ Release work >> ]
[ < Debugging Scheme code ]		[  Up : Programming work ]	[ Adding or modifying features > ]

<< Back to Documentation Index

LilyPond — Contributor’s Guide