1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Programming work
6 * Overview of LilyPond architecture::
7 * LilyPond programming languages::
8 * Programming without compiling::
11 * Warnings Errors Progress and Debug Output::
12 * Debugging LilyPond::
13 * Tracing object relationships::
14 * Adding or modifying features::
18 * Understanding pure properties::
20 * Scheme->C interface::
21 * LilyPond miscellany::
24 @node Overview of LilyPond architecture
25 @section Overview of LilyPond architecture
27 LilyPond processes the input file into graphical and musical output in a
28 number of stages. This process, along with the types of routines that
29 accomplish the various stages of the process, is described in this section. A
30 more complete description of the LilyPond architecture and internal program
31 execution is found in Erik Sandberg's
32 @uref{http://lilypond.org/website/pdf/thesis-erik-sandberg.pdf, master's
35 The first stage of LilyPond processing is @emph{parsing}. In the parsing
36 process, music expressions in LilyPond input format are converted to music
37 expressions in Scheme format. In Scheme format, a music expression is a list
38 in tree form, with nodes that indicate the relationships between various music
39 events. The LilyPond parser is written in Bison.
41 The second stage of LilyPond processing is @emph{iterating}. Iterating
42 assigns each music event to a context, which is the environment in which the
43 music will be finally engraved. The context is responsible for all further
44 processing of the music. It is during the iteration stage that contexts are
45 created as necessary to ensure that every note has a Voice type context (e.g.
46 Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
47 GregorianTranscriptionVoice), that the Voice type contexts exist in
48 appropriate Staff type contexts, and that parallel Staff type contexts exist
49 in StaffGroup type contexts. In addition, during the iteration stage each
50 music event is assigned a moment, or a time in the music when the event
53 Each type of music event has an associated iterator. Iterators are defined in
54 @file{*-iterator.cc}. During iteration, an
55 event's iterator is called to deliver that music event to the appropriate
58 The final stage of LilyPond processing is @emph{translation}. During
59 translation, music events are prepared for graphical or midi output. The
60 translation step is accomplished by the polymorphic base class Translator
61 through its two derived classes: Engraver (for graphical output) and
62 Performer (for midi output).
64 Translators are defined in C++ files named @file{*-engraver.cc}
65 and @file{*-performer.cc}.
66 Much of the work of translating is handled by Scheme functions,
67 which is one of the keys to LilyPond's exceptional flexibility.
69 @sourceimage{architecture-diagram,,,png}
72 @node LilyPond programming languages
73 @section LilyPond programming languages
75 Programming in LilyPond is done in a variety of programming languages. Each
76 language is used for a specific purpose or purposes. This section describes
77 the languages used and provides links to reference manuals and tutorials for
78 the relevant language.
82 The core functionality of LilyPond is implemented in C++.
84 C++ is so ubiquitous that it is difficult to identify either a reference
85 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
86 time to learn the language before attempting to modify the C++ code.
88 The C++ code calls Scheme/GUILE through the GUILE interface, which is
90 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
95 The LilyPond lexer is implemented in Flex, an implementation of the Unix lex
96 lexical analyser generator. Resources for Flex can be found
97 @uref{http://flex.sourceforge.net/, here}.
101 The LilyPond parser is implemented in Bison, a GNU parser generator. The
102 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
103 gnu.org}. The manual (which includes both a reference and tutorial) is
104 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
109 GNU Make is used to control the compiling process and to build the
110 documentation and the website. GNU Make documentation is available at
111 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
113 @subsection GUILE or Scheme
115 GUILE is the dialect of Scheme that is used as LilyPond's extension language.
116 Many extensions to LilyPond are written entirely in GUILE. The
117 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
118 GUILE Reference Manual} is available online.
120 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
121 Interpretation of Computer Programs}, a popular textbook used to teach
122 programming in Scheme is available in its entirety online.
124 An introduction to Guile/Scheme as used in LilyPond can be found in the
125 @rextend{Scheme tutorial}.
129 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
130 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
131 METAFONT tutorial page}.
133 @subsection PostScript
135 PostScript is used to generate graphical output. A brief PostScript tutorial
136 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
137 available online}. The
138 @uref{http://www.adobe.com/products/postscript/pdfs/PLRM.pdf, PostScript Language
139 Reference} is available online in PDF format.
143 Python is used for XML2ly and is used for building the documentation and the
146 Python documentation is available at @uref{http://www.python.org/doc/,
149 @subsection Scalable Vector Graphics (SVG)
151 Scalable Vector Graphics (SVG) is an XML-based markup language used to generate
152 graphical output. A brief SVG tutorial is
153 @uref{https://www.w3schools.com/graphics/svg_intro.asp, available online} through
154 W3 Schools. The World Wide Web Consortium's
155 @uref{https://www.w3.org/TR/SVG/REC-SVG11-20110816.pdf, SVG 1.2 Recommendation}
156 is available online in PDF format.
158 @node Programming without compiling
159 @section Programming without compiling
161 Much of the development work in LilyPond takes place by changing @file{*.ly} or
162 @file{*.scm} files. These changes can be made without compiling LilyPond. Such
163 changes are described in this section.
166 @subsection Modifying distribution files
168 Much of LilyPond is written in Scheme or LilyPond input files. These
169 files are interpreted when the program is run, rather than being compiled
170 when the program is built, and are present in all LilyPond distributions.
171 You will find @file{.ly} files in the @file{ly/} directory and the Scheme files in the
172 @file{scm/} directory. Both Scheme files and @file{.ly} files can be modified and
173 saved with any text editor. It's probably wise to make a backup copy of
174 your files before you modify them, although you can reinstall if the
175 files become corrupted.
177 Once you've modified the files, you can test the changes just by running
178 LilyPond on some input file. It's a good idea to create a file that
179 demonstrates the feature you're trying to add. This file will eventually
180 become a regression test and will be part of the LilyPond distribution.
182 @subsection Desired file formatting
184 Files that are part of the LilyPond distribution have Unix-style line
185 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
186 sure you use the necessary tools to ensure that Unix-style line endings are
187 preserved in the patches you create.
189 Tab characters should not be included in files for distribution. All
190 indentation should be done with spaces. Most editors have settings to
191 allow the setting of tab stops and ensuring that no tab characters are
192 included in the file.
194 Scheme files and LilyPond files should be written according to standard
195 style guidelines. Scheme file guidelines can be found at
196 @uref{http://community.schemewiki.org/?scheme-style}. Following these
197 guidelines will make your code easier to read. Both you and others that
198 work on your code will be glad you followed these guidelines.
200 For LilyPond files, you should follow the guidelines for LilyPond snippets
201 in the documentation. You can find these guidelines at
202 @ref{Texinfo introduction and usage policy}.
204 @node Finding functions
205 @section Finding functions
207 When making changes or fixing bugs in LilyPond, one of the initial
208 challenges is finding out where in the code tree the functions to
209 be modified live. With nearly 3000 files in the source tree,
210 trial-and-error searching is generally ineffective. This section
211 describes a process for finding interesting code.
213 @subsection Using the ROADMAP
215 The file ROADMAP is located in the main directory of the lilypond source.
216 ROADMAP lists all of the directories in the LilyPond source tree, along
217 with a brief description of the kind of files found in each directory.
218 This can be a very helpful tool for deciding which directories to search
219 when looking for a function.
222 @subsection Using grep to search
224 Having identified a likely subdirectory to search, the grep utility can
225 be used to search for a function name. The format of the grep command is
228 grep -i functionName subdirectory/*
231 This command will search all the contents of the directory subdirectory/
232 and display every line in any of the files that contains
233 functionName. The @option{-i} option makes @command{grep} ignore
234 case -- this can be very useful if you are not yet familiar with
235 our capitalization conventions.
237 The most likely directories to grep for function names are @file{scm/} for
238 scheme files, ly/ for lilypond input (@file{*.ly}) files, and @file{lily/} for C++
242 @subsection Using git grep to search
244 If you have used git to obtain the source, you have access to a
245 powerful tool to search for functions. The command:
248 git grep functionName
251 will search through all of the files that are present in the git
252 repository looking for functionName. It also presents the results
253 of the search using @code{less}, so the results are displayed one page
256 @subsection Searching on the git repository at Savannah
258 You can also use the equivalent of git grep on the Savannah server.
263 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
266 In the pulldown box that says commit, select grep.
269 Type functionName in the search box, and hit enter/return
273 This will initiate a search of the remote git repository.
279 This section describes style guidelines for LilyPond
286 * Naming conventions::
295 @subsection Languages
297 C++ and Python are preferred. Python code should use PEP 8.
301 @subsection Filenames
303 Definitions of classes that are only accessed via pointers (*) or
304 references (&) shall not be included as include files.
310 ".cc" Implementation files
311 ".icc" Inline definition files
312 ".tcc" non inline Template defs
316 (setq auto-mode-alist
317 (append '(("\\.make$" . makefile-mode)
318 ("\\.cc$" . c++-mode)
319 ("\\.icc$" . c++-mode)
320 ("\\.tcc$" . c++-mode)
321 ("\\.hh$" . c++-mode)
322 ("\\.pod$" . text-mode)
327 The class Class_name is coded in @q{class-name.*}
331 @subsection Indentation
333 Standard GNU coding style is used.
335 @subsubheading Indenting files with @code{fixcc.py} (recommended)
337 LilyPond provides a python script that will adjust the indentation
338 and spacing on a @code{.cc} or @code{.hh} file to very near the
342 scripts/auxiliar/fixcc.py FILENAME
345 This can be run on all files at once, but this is not recommended
346 for normal contributors or developers.
349 scripts/auxiliar/fixcc.py \
350 $(find flower lily -name '*cc' -o -name '*hh' | grep -v /out)
354 @subsubheading Indenting with emacs
356 The following hooks will produce indentation which is similar to
357 our official indentation as produced with @code{fixcc.py}.
360 (add-hook 'c++-mode-hook
363 (setq indent-tabs-mode nil))
366 If you like using font-lock, you can also add this to your
370 (setq font-lock-maximum-decoration t)
371 (setq c++-font-lock-keywords-3
373 c++-font-lock-keywords-3
374 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
379 @subsubheading Indenting with vim
381 Although emacs indentation is the GNU standard, correct
382 indentation for C++ files can be achieved by using the settings
384 @url{https://gcc.gnu.org/wiki/FormattingCodeForGCC, GNU GCC Wiki}.
385 Save the following in @file{~/.vim/after/ftplugin/cpp.vim}:
389 setlocal cinoptions=>4,n-2,@{2,^-2,:2,=2,g0,h2,p5,t0,+2,(0,u0,w1,m1
390 setlocal shiftwidth=2
391 setlocal softtabstop=2
392 setlocal textwidth=79
393 setlocal fo-=ro fo+=cql
394 " use spaces instead of tabs
396 " remove trailing whitespace on write
397 autocmd BufWritePre * :%s/\s\+$//e
400 With these settings, files can be reindented automatically by
401 highlighting the lines to be indented in visual mode (use V to
402 enter visual mode) and pressing @code{=}, or a single line
403 correctly indented in normal mode by pressing @code{==}.
405 A @file{scheme.vim} file will help improve the indentation of
406 Scheme code. This one was suggested by Patrick McCarty. It
407 should be saved in @file{~/.vim/after/syntax/scheme.vim}.
410 " Additional Guile-specific 'forms'
411 syn keyword schemeSyntax define-public define*-public
412 syn keyword schemeSyntax define* lambda* let-keywords*
413 syn keyword schemeSyntax defmacro defmacro* define-macro
414 syn keyword schemeSyntax defmacro-public defmacro*-public
415 syn keyword schemeSyntax use-modules define-module
416 syn keyword schemeSyntax define-method define-class
418 " Additional LilyPond-specific 'forms'
419 syn keyword schemeSyntax define-markup-command define-markup-list-command
420 syn keyword schemeSyntax define-safe-public define-music-function
421 syn keyword schemeSyntax def-grace-function
423 " All of the above should influence indenting too
424 setlocal lw+=define-public,define*-public
425 setlocal lw+=define*,lambda*,let-keywords*
426 setlocal lw+=defmacro,defmacro*,define-macro
427 setlocal lw+=defmacro-public,defmacro*-public
428 setlocal lw+=use-modules,define-module
429 setlocal lw+=define-method,define-class
430 setlocal lw+=define-markup-command,define-markup-list-command
431 setlocal lw+=define-safe-public,define-music-function
432 setlocal lw+=def-grace-function
434 " These forms should not influence indenting
438 " Try to highlight all ly: procedures
439 syn match schemeFunc "ly:[^) ]\+"
442 For documentation work on texinfo files, identify the file
443 extensions used as texinfo files in your @file{.vim/filetype.vim}:
446 if exists("did_load_filetypes")
449 augroup filetypedetect
450 au! BufRead,BufNewFile *.itely setfiletype texinfo
451 au! BufRead,BufNewFile *.itexi setfiletype texinfo
452 au! BufRead,BufNewFile *.tely setfiletype texinfo
456 and add these settings in @file{.vim/after/ftplugin/texinfo.vim}:
460 setlocal shiftwidth=2
461 setlocal textwidth=66
464 @node Naming conventions
465 @subsection Naming Conventions
467 Naming conventions have been established for LilyPond
470 @subheading Classes and Types
472 Classes begin with an uppercase letter, and words
473 in class names are separated with @code{_}:
481 Member variable names end with an underscore:
489 Macro names should be written in uppercase completely,
490 with words separated by @code{_}:
496 @subheading Variables
498 Variable names should be complete words, rather than abbreviations.
499 For example, it is preferred to use @code{thickness} rather than
500 @code{th} or @code{t}.
502 Multi-word variable names in C++ should have the words separated
503 by the underscore character (@q{_}):
506 cxx_multiword_variable
509 Multi-word variable names in Scheme should have the words separated
513 scheme-multiword-variable
517 @subsection Broken code
519 Do not write broken code. This includes hardwired dependencies,
520 hardwired constants, slow algorithms and obvious limitations. If
521 you can not avoid it, mark the place clearly, and add a comment
522 explaining shortcomings of the code.
524 Ideally, the comment marking the shortcoming would include
525 TODO, so that it is marked for future fixing.
527 We reject broken-in-advance on principle.
531 @subsection Code comments
533 Comments may not be needed if descriptive variable names are used
534 in the code and the logic is straightforward. However, if the
535 logic is difficult to follow, and particularly if non-obvious
536 code has been included to resolve a bug, a comment describing
537 the logic and/or the need for the non-obvious code should be included.
539 There are instances where the current code could be commented better.
540 If significant time is required to understand the code as part of
541 preparing a patch, it would be wise to add comments reflecting your
542 understanding to make future work easier.
545 @node Handling errors
546 @subsection Handling errors
548 As a general rule, you should always try to continue computations,
549 even if there is some kind of error. When the program stops, it
550 is often very hard for a user to pinpoint what part of the input
551 causes an error. Finding the culprit is much easier if there is
552 some viewable output.
554 So functions and methods do not return errorcodes, they never
555 crash, but report a programming_error and try to carry on.
557 Error and warning messages need to be localized.
561 @subsection Localization
563 This document provides some guidelines to help programmers write
565 messages. To help translations, user messages must follow
566 uniform conventions. Follow these rules when coding for LilyPond.
567 Hopefully, this can be replaced by general GNU guidelines in the
568 future. Even better would be to have an English (en_BR, en_AM)
569 guide helping programmers writing consistent messages for all GNU
572 Non-preferred messages are marked with `+'. By convention,
573 ungrammatical examples are marked with `*'. However, such ungrammatical
574 examples may still be preferred.
579 Every message to the user should be localized (and thus be marked
580 for localization). This includes warning and error messages.
583 Do not localize/gettextify:
587 `programming_error ()'s
590 `programming_warning ()'s
596 output strings (PostScript, TeX, etc.)
601 Messages to be localized must be encapsulated in `_ (STRING)' or
602 `_f (FORMAT, ...)'. E.g.:
605 warning (_ ("need music in a score"));
606 error (_f ("cannot open file: `%s'", file_name));
609 In some rare cases you may need to call `gettext ()' by hand. This
610 happens when you pre-define (a list of) string constants for later
611 use. In that case, you'll probably also need to mark these string
612 constants for translation, using `_i (STRING)'. The `_i' macro is
613 a no-op, it only serves as a marker for `xgettext'.
616 char const* messages[] = @{
617 _i ("enable debugging output"),
618 _i ("ignore lilypond version"),
625 puts (gettext (messages i));
629 See also @file{flower/getopt-long.cc} and @file{lily/main.cc}.
632 Do not use leading or trailing whitespace in messages. If you need
633 whitespace to be printed, prepend or append it to the translated
637 message ("Calculating line breaks..." + " ");
641 Error or warning messages displayed with a file name and line
642 number never start with a capital, eg,
645 foo.ly: 12: not a duration: 3
648 Messages containing a final verb, or a gerund (`-ing'-form) always
649 start with a capital. Other (simpler) messages start with a
655 Not declaring: `foo'.
659 Avoid abbreviations or short forms, use `cannot' and `do not'
660 rather than `can't' or `don't'
661 To avoid having a number of different messages for the same
662 situation, well will use quoting like this `"message: `%s'"' for all
663 strings. Numbers are not quoted:
666 _f ("cannot open file: `%s'", name_str)
667 _f ("cannot find character number: %d", i)
671 Think about translation issues. In a lot of cases, it is better to
672 translate a whole message. English grammar must not be imposed on the
673 translator. So, instead of
676 stem at + moment.str () + does not fit in beam
682 _f ("stem at %s does not fit in beam", moment.str ())
686 Split up multi-sentence messages, whenever possible. Instead of
689 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
690 warning (_f ("cannot find font `%s', loading default", font_name));
696 warning (_ ("out of tune:"));
697 warning (_f ("cannot find: `%s', "Key_engraver"));
698 warning (_f ("cannot find font: `%s', font_name));
699 warning (_f ("Loading default font"));
703 If you must have multiple-sentence messages, use full punctuation.
704 Use two spaces after end of sentence punctuation. No punctuation
705 (esp. period) is used at the end of simple messages.
708 _f ("Non-matching braces in text `%s', adding braces", text)
709 _ ("Debug output disabled. Compiled with NPRINT.")
710 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
714 Do not modularize too much; words frequently cannot be translated
715 without context. It is probably safe to treat most occurrences of
716 words like stem, beam, crescendo as separately translatable words.
719 When translating, it is preferable to put interesting information
720 at the end of the message, rather than embedded in the middle.
721 This especially applies to frequently used messages, even if this
722 would mean sacrificing a bit of eloquence. This holds for original
723 messages too, of course.
726 en: cannot open: `foo.ly'
727 + nl: kan `foo.ly' niet openen (1)
728 kan niet openen: `foo.ly'* (2)
729 niet te openen: `foo.ly'* (3)
733 The first nl message, although grammatically and stylistically
734 correct, is not friendly for parsing by humans (even if they speak
735 dutch). I guess we would prefer something like (2) or (3).
738 Do not run make po/po-update with GNU gettext < 0.10.35
743 @node Warnings Errors Progress and Debug Output
744 @section Warnings, Errors, Progress and Debug Output
746 @unnumberedsubsec Available log levels
748 LilyPond has several loglevels, which specify how verbose the output on
749 the console should be:
751 @item NONE: No output at all, even on failure
752 @item ERROR: Only error messages
753 @item WARN: Only error messages and warnings
754 @item BASIC_PROGRESS: Warnings, errors and basic progress (success, etc.)
755 @item PROGRESS: Warnings, errors and full progress messages
756 @item INFO: Warnings, errors, progress and more detailed information (default)
757 @item DEBUG: All messages, including full debug messages (very verbose!)
760 The loglevel can either be set with the environment variable
761 @code{LILYPOND_LOGLEVEL} or on the command line with the @option{--loglevel=...}
764 @unnumberedsubsec Functions for debug and log output
766 LilyPond has two different types of error and log functions:
770 If a warning or error is caused by an identified position in the input file,
771 e.g. by a grob or by a music expression, the functions of the @code{Input}
772 class provide logging functionality that prints the position of the message
773 in addition to the message.
776 If a message can not be associated with a particular position in an input file,
777 e.g. the output file cannot be written, then the functions in the
778 @code{flower/include/warn.hh} file will provide logging functionality that
779 only prints out the message, but no location.
783 There are also Scheme functions to access all of these logging functions from
784 scheme. In addition, the Grob class contains some convenience wrappers for
785 even easier access to these functions.
787 The message and debug functions in @code{warn.hh} also have an optional
788 argument @code{newline}, which specifies whether the message should always
789 start on a new line or continue a previous message.
790 By default, @code{progress_indication} does NOT start on a new line, but rather
791 continue the previous output. They also do not have a particular input
792 position associated, so there are no progress functions in the Input class.
793 All other functions by default start their output on a new line.
795 The error functions come in three different flavors: fatal error messages,
796 programming error messages and normal error messages. Errors written
797 by the @code{error ()} function will cause LilyPond to exit immediately,
798 errors by @code{Input::error ()} will continue the compilation, but
799 return a non-zero return value of the LilyPond call (i.e. indicate an
800 unsuccessful program execution). All other errors will be printed on the
801 console, but not exit LilyPond or indicate an unsuccessful return code.
802 Their only differences to a warnings are the displayed text and that
803 they will be shown with loglevel @code{ERROR}.
805 If the Scheme option @code{warning-as-error} is set, any warning will be
806 treated as if @code{Input::error} was called.
809 @unnumberedsubsec All logging functions at a glance
811 @multitable @columnfractions 0.16 0.42 0.42
813 @tab C++, no location
814 @tab C++ from input location
817 @tab @code{error ()}, @code{programming_error (msg)}, @code{non_fatal_error (msg)}
818 @tab @code{Input::error (msg)}, @code{Input::programming_error (msg)}
821 @tab @code{warning (msg)}
822 @tab @code{Input::warning (msg)}
825 @tab @code{basic_progress (msg)}
829 @tab @code{progress_indication (msg)}
833 @tab @code{message (msg)}
834 @tab @code{Input::message (msg)}
837 @tab @code{debug_output (msg)}
838 @tab @code{Input::debug_output (msg)}
844 @tab Scheme, music expression
847 @tab @code{Grob::programming_error (msg)}
851 @tab @code{Grob::warning (msg)}
852 @tab @code{(ly:music-warning music msg)}
864 @tab @code{(ly:music-message music msg)}
873 @tab Scheme, no location
874 @tab Scheme, input location
878 @tab @code{(ly:error msg args)}, @code{(ly:programming-error msg args)}
881 @tab @code{(ly:warning msg args)}
882 @tab @code{(ly:input-warning input msg args)}
885 @tab @code{(ly:basic-progress msg args)}
889 @tab @code{(ly:progress msg args)}
893 @tab @code{(ly:message msg args)}
894 @tab @code{(ly:input-message input msg args)}
897 @tab @code{(ly:debug msg args)}
905 @node Debugging LilyPond
906 @section Debugging LilyPond
908 The most commonly used tool for debugging LilyPond is the GNU
909 debugger gdb. The gdb tool is used for investigating and debugging
910 core LilyPond code written in C++. Another tool is available for
911 debugging Scheme code using the Guile debugger. This section
912 describes how to use both gdb and the Guile Debugger.
915 * Debugging overview::
916 * Debugging C++ code::
917 * Debugging Scheme code::
920 @node Debugging overview
921 @subsection Debugging overview
923 Using a debugger simplifies troubleshooting in at least two ways.
925 First, breakpoints can be set to pause execution at any desired point.
926 Then, when execution has paused, debugger commands can be issued to
927 explore the values of various variables or to execute functions.
929 Second, the debugger can display a stack trace, which shows the
930 sequence in which functions have been called and the arguments
931 passed to the called functions.
933 @node Debugging C++ code
934 @subsection Debugging C++ code
936 The GNU debugger, gdb, is the principal tool for debugging C++ code.
938 @subheading Compiling LilyPond for use with gdb
940 In order to use gdb with LilyPond, it is necessary to compile
941 LilyPond with debugging information. This is the current default
942 mode of compilation. Often debugging becomes more complicated
943 when the compiler has optimised variables and function calls away.
944 In that case it may be helpful to run the following command in the
945 main LilyPond source directory:
948 ./configure --disable-optimising
952 This will create a version of LilyPond with minimal optimization
953 which will allow the debugger to access all variables and step
954 through the source code in-order. It may not accurately reproduce
955 bugs encountered with the optimized version, however.
957 You should not do @var{make install} if you want to use a debugger
958 with LilyPond. The @var{make install} command will strip debugging
959 information from the LilyPond binary.
961 @subheading Typical gdb usage
963 Once you have compiled the LilyPond image with the necessary
964 debugging information it will have been written to a location in a
965 subfolder of your current working directory:
971 This is important as you will need to let gdb know where to find the
972 image containing the symbol tables. You can invoke gdb from the
973 command line using the following:
979 This loads the LilyPond symbol tables into gdb. Then, to run
980 LilyPond on @file{test.ly} under the debugger, enter the following:
989 As an alternative to running gdb at the command line you may try
990 a graphical interface to gdb such as ddd:
996 You can also use sets of standard gdb commands stored in a .gdbinit
997 file (see next section).
999 @subheading Typical .gdbinit files
1001 The behavior of gdb can be readily customized through the use of a
1002 @var{.gdbinit} file. A @var{.gdbinit} file is a file named
1003 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
1004 that is placed in a user's home directory.
1006 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
1007 for all errors and defines functions for displaying scheme objects
1008 (ps), grobs (pgrob), and parsed music expressions (pmusic).
1011 file $LILYPOND_GIT/build/out/bin/lilypond
1013 b Grob::programming_error
1016 print ly_display_scm($arg0)
1019 print ly_display_scm($arg0->self_scm_)
1020 print ly_display_scm($arg0->mutable_property_alist_)
1021 print ly_display_scm($arg0->immutable_property_alist_)
1022 print ly_display_scm($arg0->object_alist_)
1025 print ly_display_scm($arg0->self_scm_)
1026 print ly_display_scm($arg0->mutable_property_alist_)
1027 print ly_display_scm($arg0->immutable_property_alist_)
1031 @node Debugging Scheme code
1032 @subsection Debugging Scheme code
1034 Scheme code can be developed using the Guile command line
1035 interpreter @code{top-repl}. You can either investigate
1036 interactively using just Guile or you can use the debugging
1037 tools available within Guile.
1039 @subheading Using Guile interactively with LilyPond
1041 In order to experiment with Scheme programming in the LilyPond
1042 environment, it is necessary to have a Guile interpreter that
1043 has all the LilyPond modules loaded. This requires the following
1046 First, define a Scheme symbol for the active module in the @file{.ly} file:
1049 #(module-define! (resolve-module '(guile-user))
1050 'lilypond-module (current-module))
1053 Now place a Scheme function in the @file{.ly} file that gives an
1054 interactive Guile prompt:
1060 When the @file{.ly} file is compiled, this causes the compilation to be
1061 interrupted and an interactive guile prompt to appear. Once the
1062 guile prompt appears, the LilyPond active module must be set as the
1063 current guile module:
1066 guile> (set-current-module lilypond-module)
1069 You can demonstrate these commands are operating properly by typing the name
1070 of a LilyPond public scheme function to check it has been defined:
1073 guile> fret-diagram-verbose-markup
1074 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
1077 If the LilyPond module has not been correctly loaded, an error
1078 message will be generated:
1081 guile> fret-diagram-verbose-markup
1082 ERROR: Unbound variable: fret-diagram-verbose-markup
1083 ABORT: (unbound-variable)
1086 Once the module is properly loaded, any valid LilyPond Scheme
1087 expression can be entered at the interactive prompt.
1089 After the investigation is complete, the interactive guile
1090 interpreter can be exited:
1096 The compilation of the @file{.ly} file will then continue.
1098 @subheading Using the Guile debugger
1100 To set breakpoints and/or enable tracing in Scheme functions, put
1103 \include "guile-debugger.ly"
1106 in your input file after any scheme procedures you have defined in
1107 that file. This will invoke the Guile command-line after having set
1108 up the environment for the debug command-line. When your input file
1109 is processed, a guile prompt will be displayed. You may now enter
1110 commands to set up breakpoints and enable tracing by the Guile debugger.
1112 @subheading Using breakpoints
1114 At the guile prompt, you can set breakpoints with
1115 the @code{set-break!} procedure:
1118 guile> (set-break! my-scheme-procedure)
1121 Once you have set the desired breakpoints, you exit the guile repl frame
1128 Then, when one of the scheme routines for which you have set
1129 breakpoints is entered, guile will interrupt execution in a debug
1130 frame. At this point you will have access to Guile debugging
1131 commands. For a listing of these commands, type:
1137 Alternatively you may code the breakpoints in your LilyPond source
1138 file using a command such as:
1141 #(set-break! my-scheme-procedure)
1144 immediately after the @code{\include} statement. In this case the
1145 breakpoint will be set straight after you enter the @code{(quit)}
1146 command at the guile prompt.
1148 Embedding breakpoint commands like this is particularly useful if
1149 you want to look at how the Scheme procedures in the @file{.scm}
1150 files supplied with LilyPond work. To do this, edit the file in
1151 the relevant directory to add this line near the top:
1154 (use-modules (scm guile-debugger))
1157 Now you can set a breakpoint after the procedure you are interested
1158 in has been declared. For example, if you are working on routines
1159 called by @var{print-book-with} in @file{lily-library.scm}:
1162 (define (print-book-with book process-procedure)
1163 (let* ((paper (ly:parser-lookup '$defaultpaper))
1164 (layout (ly:parser-lookup '$defaultlayout))
1165 (outfile-name (get-outfile-name book)))
1166 (process-procedure book paper layout outfile-name)))
1168 (define-public (print-book-with-defaults book)
1169 (print-book-with book ly:book-process))
1171 (define-public (print-book-with-defaults-as-systems book)
1172 (print-book-with book ly:book-process-to-systems))
1175 At this point in the code you could add this to set a breakpoint at
1179 (set-break! print-book-with)
1182 @subheading Tracing procedure calls and evaluator steps
1184 Two forms of trace are available:
1187 (set-trace-call! my-scheme-procedure)
1193 (set-trace-subtree! my-scheme-procedure)
1196 @code{set-trace-call!} causes Scheme to log a line to the standard
1197 output to show when the procedure is called and when it exits.
1199 @code{set-trace-subtree!} traces every step the Scheme evaluator
1200 performs in evaluating the procedure.
1202 @node Tracing object relationships
1203 @section Tracing object relationships
1205 Understanding the LilyPond source often boils down to figuring out what
1206 is happening to the Grobs. Where (and why) are they being created,
1207 modified and destroyed? Tracing Lily through a debugger in order to
1208 identify these relationships can be time-consuming and tedious.
1210 In order to simplify this process, a facility has been added to
1211 display the grobs that are created and the properties that are set
1212 and modified. Although it can be complex to get set up, once set up
1213 it easily provides detailed information about the life of grobs
1214 in the form of a network graph.
1216 Each of the steps necessary to use the graphviz utility
1221 @item Installing graphviz
1223 In order to create the graph of the object relationships, it is
1224 first necessary to install Graphviz. Graphviz is available for a
1225 number of different platforms:
1228 @uref{http://www.graphviz.org/Download..php}
1231 @item Modifying config.make
1233 In order for the Graphviz tool to work, config.make must be modified.
1234 It is probably a good idea to first save a copy of config.make under
1237 In order to have the required functionality available, LilyPond
1238 needs to be compiled with the option @option{-DDEBUG}. You can
1239 achieve this by configuring with
1242 ./configure --enable-checking
1245 @item Rebuilding LilyPond
1247 The executable code of LilyPond must be rebuilt from scratch:
1253 @item Create a graphviz-compatible @file{.ly} file
1255 In order to use the graphviz utility, the @file{.ly} file must include
1256 @file{ly/graphviz-init.ly}, and should then specify the
1257 grobs and symbols that should be tracked. An example of this
1258 is found in @file{input/regression/graphviz.ly}.
1260 @item Run LilyPond with output sent to a log file
1262 The Graphviz data is sent to stderr by LilyPond, so it is
1263 necessary to redirect stderr to a logfile:
1266 lilypond graphviz.ly 2> graphviz.log
1269 @item Edit the logfile
1271 The logfile has standard LilyPond output, as well as the Graphviz
1272 output data. Delete everything from the beginning of the file
1273 up to but not including the first occurrence of @code{digraph}.
1275 Also, delete the final LilyPond message about success from the end
1278 @item Process the logfile with @code{dot}
1280 The directed graph is created from the log file with the program
1284 dot -Tpdf graphviz.log > graphviz.pdf
1289 The pdf file can then be viewed with any pdf viewer.
1291 When compiled with @option{-DDEBUG}, LilyPond may run slower
1292 than normal. The original configuration can be restored by rerunning
1293 @code{./configure} with @option{--disable-checking}. Then
1294 rebuild LilyPond with
1301 @node Adding or modifying features
1302 @section Adding or modifying features
1304 When a new feature is to be added to LilyPond, it is necessary to
1305 ensure that the feature is properly integrated to maintain
1306 its long-term support. This section describes the steps necessary
1307 for feature addition and modification.
1312 * Write regression tests::
1313 * Write convert-ly rule::
1314 * Automatically update documentation::
1315 * Manually update documentation::
1316 * Edit changes.tely::
1317 * Verify successful build::
1318 * Verify regression tests::
1319 * Post patch for comments::
1321 * Closing the issues::
1324 @node Write the code
1325 @subsection Write the code
1327 You should probably create a new git branch for writing the code, as that
1328 will separate it from the master branch and allow you to continue
1329 to work on small projects related to master.
1331 Please be sure to follow the rules for programming style discussed
1332 earlier in this chapter.
1335 @node Write regression tests
1336 @subsection Write regression tests
1338 In order to demonstrate that the code works properly, you will
1339 need to write one or more regression tests. These tests are
1340 typically @file{.ly} files that are found in @file{input/regression}.
1342 Regression tests should be as brief as possible to demonstrate the
1343 functionality of the code.
1345 Regression tests should generally cover one issue per test. Several
1346 short, single-issue regression tests are preferred to a single, long,
1347 multiple-issue regression test.
1349 If the change in the output is small or easy to overlook, use bigger
1350 staff size -- 40 or more (up to 100 in extreme cases). Size 30 means
1351 "pay extra attention to details in general".
1353 Use existing regression tests as templates to demonstrate the type of
1354 header information that should be included in a regression test.
1357 @node Write convert-ly rule
1358 @subsection Write convert-ly rule
1360 If the modification changes the input syntax, a convert-ly rule
1361 should be written to automatically update input files from older
1364 convert-ly rules are found in python/convertrules.py
1366 If possible, the convert-ly rule should allow automatic updating
1367 of the file. In some cases, this will not be possible, so the
1368 rule will simply point out to the user that the feature needs
1371 @subsubheading Updating version numbers
1373 If a development release occurs between you writing your patch and
1374 having it approved+pushed, you will need to update the version
1375 numbers in your tree. This can be done with:
1378 scripts/auxiliar/update-patch-version old.version.number new.version.number
1381 It will change all files in git, so use with caution and examine
1385 @node Automatically update documentation
1386 @subsection Automatically update documentation
1388 @command{convert-ly} should be used to update the documentation,
1389 the snippets, and the regression tests. This not only makes the
1390 necessary syntax changes, it also tests the @command{convert-ly}
1393 The automatic updating is performed by moving to the top-level
1394 source directory, then running:
1397 scripts/auxiliar/update-with-convert-ly.sh
1400 If you did an out-of-tree build, pass in the relative path:
1403 LILYPOND_BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh
1407 @node Manually update documentation
1408 @subsection Manually update documentation
1410 Where the convert-ly rule is not able to automatically update the inline
1411 LilyPond code in the documentation (i.e. if a NOT_SMART rule is used), the
1412 documentation must be manually updated. The inline snippets that require
1413 changing must be changed in the English version of the docs and all
1414 translated versions. If the inline code is not changed in the
1415 translated documentation, the old snippets will show up in the
1416 English version of the documentation.
1418 Where the convert-ly rule is not able to automatically update snippets
1419 in Documentation/snippets/, those snippets must be manually updated.
1420 Those snippets should be copied to Documentation/snippets/new. The
1421 comments at the top of the snippet describing its automatic generation
1422 should be removed. All translated texidoc strings should be removed.
1423 The comment @qq{% begin verbatim} should be removed. The syntax of
1424 the snippet should then be manually edited.
1426 Where snippets in Documentation/snippets are made obsolete, the snippet
1427 should be copied to Documentation/snippets/new. The comments and
1428 texidoc strings should be removed as described above. Then the body
1429 of the snippet should be changed to:
1433 This snippet is deprecated as of version X.Y.Z and
1434 will be removed from the documentation.
1439 where X.Y.Z is the version number for which the convert-ly rule was
1442 Update the snippet files by running:
1445 scripts/auxiliar/makelsr.py
1448 Where the convert-ly rule is not able to automatically update regression
1449 tests, the regression tests in input/regression should be manually
1452 Although it is not required, it is helpful if the developer
1453 can write relevant material for inclusion in the Notation
1454 Reference. If the developer does not feel qualified to write
1455 the documentation, a documentation editor will be able to
1456 write it from the regression tests. In this case the developer
1457 should raise a new issue with the Type=Documentation tag containing
1458 a reference to the original issue number and/or the committish of
1459 the pushed patch so that the need for new documention is not
1462 Any text that is added to or removed from the documentation should
1463 be changed only in the English version.
1466 @node Edit changes.tely
1467 @subsection Edit changes.tely
1469 An entry should be added to Documentation/changes.tely to describe
1470 the feature changes to be implemented. This is especially important
1471 for changes that change input file syntax.
1473 Hints for changes.tely entries are given at the top of the file.
1475 New entries in changes.tely go at the top of the file.
1477 The changes.tely entry should be written to show how the new change
1478 improves LilyPond, if possible.
1481 @node Verify successful build
1482 @subsection Verify successful build
1484 When the changes have been made, successful completion must be
1492 When these commands complete without error, the patch is
1493 considered to function successfully.
1495 Developers on Windows who are unable to build LilyPond should
1496 get help from a GNU/Linux or OSX developer to do the make tests.
1499 @node Verify regression tests
1500 @subsection Verify regression tests
1502 In order to avoid breaking LilyPond, it is important to verify that
1503 the regression tests succeed, and that no unwanted changes are
1504 introduced into the output. This process is described in
1505 @ref{Regtest comparison}.
1507 @subheading Typical developer's edit/compile/test cycle
1515 make [-j@var{X} CPU_COUNT=@var{X}] test-baseline
1516 make [-j@var{X} CPU_COUNT=@var{X}] check
1520 Edit/compile/test cycle:
1523 @emph{## edit source files, then...}
1525 make clean @emph{## only if needed (see below)}
1526 make [-j@var{X}] @emph{## only if needed (see below)}
1527 make [-j@var{X} CPU_COUNT=@var{X}] test-redo @emph{## redo files differing from baseline}
1528 make [-j@var{X} CPU_COUNT=@var{X}] check
1539 If you modify any source files that have to be compiled (such as
1540 @file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
1541 then you must run @command{make} before @command{make test-redo},
1542 so @command{make} can compile the modified files and relink all
1543 the object files. If you only modify files which are interpreted,
1544 like those in the @file{scm/} and @file{ly/} directories, then
1545 @command{make} is not needed before @command{make test-redo}.
1547 Also, if you modify any font definitions in the @file{mf/}
1548 directory then you must run @command{make clean} and
1549 @command{make} before running @command{make test-redo}. This will
1550 recompile everything, whether modified or not, and takes a lot
1553 Running @command{make@tie{}check} will leave an HTML page
1554 @file{out/test-results/index.html}. This page shows all the
1555 important differences that your change introduced, whether in the
1556 layout, MIDI, performance or error reporting.
1558 You only need to use @command{make test-clean} to start from
1559 scratch, prior to running @command{make@tie{}test-baseline}. To
1560 check new modifications, all that is needed is to repeat
1561 @command{make@tie{}test-redo} and @command{make@tie{}test-check}
1562 (not forgetting @command{make} if needed).
1567 @node Post patch for comments
1568 @subsection Post patch for comments
1570 See @ref{Uploading a patch for review}.
1574 @subsection Push patch
1576 Once all the comments have been addressed, the patch can be pushed.
1578 If the author has push privileges, the author will push the patch.
1579 Otherwise, a developer with push privileges will push the patch.
1582 @node Closing the issues
1583 @subsection Closing the issues
1585 Once the patch has been pushed, all the relevant issues should be
1588 On Rietveld, the author should log in and close the issue either by
1589 using the @q{Edit Issue} link, or by clicking the circled x icon
1590 to the left of the issue name.
1592 If the changes were in response to a feature request on the Google
1593 issue tracker for LilyPond, the author should change the status to
1594 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was
1595 fixed in version x.y.z. If
1596 the author does not have privileges to change the status, an email
1597 should be sent to bug-lilypond requesting the BugMeister to change
1601 @node Iterator tutorial
1602 @section Iterator tutorial
1604 TODO -- this is a placeholder for a tutorial on iterators
1606 Iterators are routines written in C++ that process music expressions
1607 and sent the music events to the appropriate engravers and/or
1610 See a short example discussing iterators and their duties in
1611 @ref{Articulations on EventChord}.
1614 @node Engraver tutorial
1615 @section Engraver tutorial
1617 Engravers are C++ classes that catch music events and
1618 create the appropriate grobs for display on the page. Though the
1619 majority of engravers are responsible for the creation of a single grob,
1620 in some cases (e.g. @code{New_fingering_engraver}), several different grobs
1623 Engravers listen for events and acknowledge grobs. Events are passed to
1624 the engraver in time-step order during the iteration phase. Grobs are
1625 made available to the engraver when they are created by other engravers
1626 during the iteration phase.
1630 * Useful methods for information processing::
1631 * Translation process::
1632 * Preventing garbage collection for SCM member variables::
1633 * Listening to music events::
1634 * Acknowledging grobs::
1635 * Engraver declaration/documentation::
1638 @node Useful methods for information processing
1639 @subsection Useful methods for information processing
1641 An engraver inherits the following public methods from the Translator
1642 base class, which can be used to process listened events and acknowledged
1646 @item @code{virtual void initialize ()}
1647 @item @code{void start_translation_timestep ()}
1648 @item @code{void process_music ()}
1649 @item @code{void process_acknowledged ()}
1650 @item @code{void stop_translation_timestep ()}
1651 @item @code{virtual void finalize ()}
1654 These methods are listed in order of translation time, with
1655 @code{initialize ()} and @code{finalize ()} bookending the whole
1656 process. @code{initialize ()} can be used for one-time initialization
1657 of context properties before translation starts, whereas
1658 @code{finalize ()} is often used to tie up loose ends at the end of
1659 translation: for example, an unterminated spanner might be completed
1660 automatically or reported with a warning message.
1663 @node Translation process
1664 @subsection Translation process
1666 At each timestep in the music, translation proceeds by calling the
1667 following methods in turn:
1669 @code{start_translation_timestep ()} is called before any user
1670 information enters the translators, i.e., no property operations
1671 (\set, \override, etc.) or events have been processed yet.
1673 @code{process_music ()} and @code{process_acknowledged ()} are called
1674 after all events in the current time step have been heard, or all
1675 grobs in the current time step have been acknowledged. The latter
1676 tends to be used exclusively with engravers which only acknowledge
1677 grobs, whereas the former is the default method for main processing
1680 @code{stop_translation_timestep ()} is called after all user
1681 information has been processed prior to beginning the translation for
1685 @node Preventing garbage collection for SCM member variables
1686 @subsection Preventing garbage collection for SCM member variables
1688 In certain cases, an engraver might need to ensure private Scheme
1689 variables (with type SCM) do not get swept away by Guile's garbage
1690 collector: for example, a cache of the previous key signature which
1691 must persist between timesteps. The method
1692 @code{virtual derived_mark () const} can be used in such cases:
1695 Engraver_name::derived_mark ()
1697 scm_gc_mark (private_scm_member_)
1702 @node Listening to music events
1703 @subsection Listening to music events
1705 External interfaces to the engraver are implemented by protected
1706 macros including one or more of the following:
1709 @item @code{DECLARE_TRANSLATOR_LISTENER (event_name)}
1710 @item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)}
1714 where @var{event_name} is the type of event required to provide the
1715 input the engraver needs and @var{Engraver_name} is the name of the
1718 Following declaration of a listener, the method is implemented as follows:
1721 IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)
1723 Engraver_name::listen_event_name (Stream event *event)
1725 ...body of listener method...
1730 @node Acknowledging grobs
1731 @subsection Acknowledging grobs
1733 Some engravers also need information from grobs as they are created
1734 and as they terminate. The mechanism and methods to obtain this
1735 information are set up by the macros:
1738 @item @code{DECLARE_ACKNOWLEDGER (grob_interface)}
1739 @item @code{DECLARE_END_ACKNOWLEDGER (grob_interface)}
1742 where @var{grob_interface} is an interface supported by the
1743 grob(s) which should be acknowledged. For example, the following
1744 code would declare acknowledgers for a @code{NoteHead} grob (via the
1745 @code{note-head-interface}) and any grobs which support the
1746 @code{side-position-interface}:
1749 DECLARE_ACKNOWLEDGER (note_head)
1750 DECLARE_ACKNOWLEDGER (side_position)
1753 The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific
1754 acknowledger which will be called whenever a spanner ends.
1756 Following declaration of an acknowledger, the method is coded as follows:
1760 Engraver_name::acknowledge_interface_name (Grob_info info)
1762 ...body of acknowledger method...
1766 Acknowledge functions are called in the order engravers are
1767 @code{\consist}-ed (the only exception is if you set
1768 @code{must-be-last} to @code{#t}).
1770 There will always be a call to @code{process-acknowledged ()} whenever
1771 grobs have been created, and @emph{reading} stuff from grobs should be
1772 delayed until then since other acknowledgers might @emph{write} stuff
1773 into a grob even after your acknowledger has been called. So the basic
1774 workflow is to use the various acknowledgers to @emph{record} the grobs
1775 you are interested in and @emph{write} stuff into them (or do read/write
1776 stuff that more or less is accumulative and/or really unrelated to other
1777 engravers), and then use the @code{process-acknowledged ()} hook for
1778 processing (including @emph{reading}) the grobs you had recorded.
1780 You can create new grobs in @code{process-acknowledged ()}. That will lead
1781 to a new cycle of @code{acknowledger ()} calls followed by a new cycle of
1782 @code{process-acknowledged ()} calls.
1784 Only when all those cycles are over is @code{stop-translator-timestep ()}
1785 called, and then creating grobs is no longer an option. You can still
1786 @q{process} parts of the grob there (if that means just reading out
1787 properties and possibly setting context properties based on them) but
1788 @code{stop-translation-timestep ()} is a cleanup hook, and other engravers
1789 might have already cleaned up stuff you might have wanted to use.
1790 Creating grobs in there is not possible since engravers and other code may
1791 no longer be in a state where they could process them, possibly causing
1795 @node Engraver declaration/documentation
1796 @subsection Engraver declaration/documentation
1798 An engraver must have a public macro
1801 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1805 where @code{Engraver_name} is the name of the engraver. This
1806 defines the common variables and methods used by every engraver.
1808 At the end of the engraver file, one or both of the following
1809 macros are generally called to document the engraver in the
1810 Internals Reference:
1813 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob_interface)}
1814 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1815 Engraver_creates, Engraver_reads, Engraver_writes)}
1819 where @code{Engraver_name} is the name of the engraver, @code{grob_interface}
1820 is the name of the interface that will be acknowledged,
1821 @code{Engraver_doc} is a docstring for the engraver,
1822 @code{Engraver_creates} is the set of grobs created by the engraver,
1823 @code{Engraver_reads} is the set of properties read by the engraver,
1824 and @code{Engraver_writes} is the set of properties written by
1827 The @code{ADD_ACKNOWLEDGER} and @code{ADD_TRANSLATOR} macros use a
1828 non-standard indentation system. Each interface, grob, read property,
1829 and write property is on its own line, and the closing parenthesis
1830 and semicolon for the macro all occupy a separate line beneath the final
1831 interface or write property. See existing engraver files for more
1835 @node Callback tutorial
1836 @section Callback tutorial
1838 TODO -- This is a placeholder for a tutorial on callback functions.
1841 @node Understanding pure properties
1842 @section Understanding pure properties
1845 * Purity in LilyPond::
1846 * Writing a pure function::
1847 * How purity is defined and stored::
1848 * Where purity is used::
1853 Pure properties are some of the most difficult properties to understand
1854 in LilyPond but, once understood, it is much easier to work with
1855 horizontal spacing. This document provides an overview of what it means
1856 for something to be @q{pure} in LilyPond, what this purity guarantees,
1857 and where pure properties are stored and used. It finishes by
1858 discussing a few case studies for the pure programmer to save you some
1859 time and to prevent you some major headaches.
1862 @node Purity in LilyPond
1863 @subsection Purity in LilyPond
1864 Pure properties in LilyPond are properties that do not have any
1866 That is, looking up a pure property should never result in calls to the
1867 following functions:
1869 @item @code{set_property}
1870 @item @code{set_object}
1871 @item @code{suicide}
1873 This means that, if the property is calculated via a callback, this callback
1874 must not only avoid the functions above but make sure that any functions
1875 it calls also avoid the functions above. Also, to date in LilyPond, a pure
1876 function will always return the same value before line breaking (or, more
1877 precisely, before any version of @code{break_into_pieces} is called). This
1878 convention makes it possible to cache pure functions and be more flexible
1879 about the order in which functions are called. For example; Stem #'length has
1880 a pure property that will @emph{never} trigger one of the functions listed
1881 above and will @emph{always} return the same value before line breaking,
1882 independent of where it is called. Sometimes, this will be the actual length
1883 of the Stem. But sometimes it will not. For example; stem that links up
1884 with a beam will need its end set to the Y position of the beam at the stem's
1885 X position. However, the beam's Y positions can only be known after the score
1886 is broken up in to several systems (a beam that has a shallow slope on a
1887 compressed line of music, for example, may have a steeper one on an
1888 uncompressed line). Thus, we only call the impure version of the properties
1889 once we are @emph{absolutely certain} that all of the parameters needed to
1890 calculate their final value have been calculated. The pure version provides a
1891 useful estimate of what this Stem length (or any property) will be, and
1892 the art of creating good pure properties is trying to get the estimation
1893 as close to the actual value as possible.
1895 Of course, like Gregory Peck and Tintin, some Grobs will have properties
1896 that will always be pure. For example, the height of a note-head in
1897 not-crazy music will never depend on line breaking or other parameters
1898 decided late in the typesetting process. Inversely, in rare cases,
1899 certain properties are difficult to estimate with pure values. For
1900 example, the height of a Hairpin at a certain cross-section of its
1901 horizontal span is difficult to know without knowing the horizontal
1902 distance that the hairpin spans, and LilyPond provides an
1903 over-estimation by reporting the pure height as the entire height of the
1906 Purity, like for those living in a convent, is more like a contract than
1907 an @emph{a priori}. If you write a pure-function, you are promising
1908 the user (and the developer who may have to clean up after you) that
1909 your function will not be dependent on factors that change at different
1910 stages of the compilation process (compilation of a score, not of
1913 One last oddity is that purity, in LilyPond, is currently limited
1914 exclusively to things that have to do with Y-extent and positioning.
1915 There is no concept of @q{pure X} as, by design, X is always the
1916 independent variable (i.e. from column X1 to column X2, what will be the
1917 Y height of a given grob). Furthermore, there is no purity for
1918 properties like color, text, and other things for which a meaningful notion
1919 of estimation is either not necessary or has not yet been found. For example,
1920 even if a color were susceptible to change at different points of the
1921 compilation process, it is not clear what a pure estimate of this color
1922 would be or how this pure color could be used. Thus, in this document and
1923 in the source, you will see purity discussed almost interchangeably with
1924 Y-axis positioning issues.
1927 @node Writing a pure function
1928 @subsection Writing a pure function
1929 Pure functions take, at a minimum, three arguments: the @var{grob}, the
1930 starting column at which the function is being evaluated (hereafter
1931 referred to as @var{start}), and the end column at which the grob is
1932 being evaluated (hereafter referred to as @var{end}). For items,
1933 @var{start} and @var{end} must be provided (meaning they are not optional)
1934 but will not have a meaningful impact on the result, as items only occupy
1935 one column and will thus yield a value or not (if they are not in the range
1936 from @var{start} to @var{end}). For spanners however, @var{start} and
1937 @var{end} are important, as we may can get a better pure estimation of a
1938 slice of the spanner than considering it on the whole. This is useful
1939 during line breaking, for example, when we want to estimate the Y-extent
1940 of a spanner broken at given starting and ending columns.
1943 @node How purity is defined and stored
1944 @subsection How purity is defined and stored
1945 Purity is defined in LilyPond with the creation of an unpure-pure container
1946 (unpure is not a word, but hey, neither was LilyPond until the 90s). For example:
1952 #(define (bar grob start end)
1955 \override Stem #'length = #(ly:make-unpure-pure-container foo bar)
1958 Note that items can only ever have two pure heights: their actual pure height
1959 if they are between @q{start} and @q{end}, or an empty interval if they are
1960 not. Thus, their pure property is cached to speed LilyPond up. Pure
1961 heights for spanners are generally not cached as they change depending
1962 on the start and end values. They are only cached in certain particular
1963 cases. Before writing a lot of caching code, make sure that it is a
1964 value that will be reused a lot.
1967 @node Where purity is used
1968 @subsection Where purity is used
1969 Pure Y values must be used in any functions that are called before
1970 line breaking. Examples of this can be seen in
1971 @code{Separation_items::boxes} to construct horizontal skylines and in
1972 @code{Note_spacing::stem_dir_correction} to correct for optical
1973 illusions in spacing. Pure properties are also used in the calculation
1974 of other pure properties. For example, the @code{Axis_group_interface}
1975 has pure functions that look up other pure functions.
1977 Purity is also implicitly used in any functions that should only ever
1978 return pure values. For example, extra-spacing-height is only ever used
1979 before line-breaking and thus should never use values that would only be
1980 available after line breaking. In this case, there is no need to create
1981 callbacks with pure equivalents because these functions, by design, need
1984 To know if a property will be called before and/or after line-breaking
1985 is sometimes tricky and can, like all things in coding, be found by
1986 using a debugger and/or adding @var{printf} statements to see where they
1987 are called in various circumstances.
1991 @subsection Case studies
1992 In each of these case studies, we expose a problem in pure properties, a
1993 solution, and the pros and cons of this solution.
1995 @subheading Time signatures
1996 A time signature needs to prevent accidentals from passing over or under
1997 it, but its extent does not necessarily extend to the Y-position of
1998 accidentals. LilyPond's horizontal spacing sometimes makes a line of
1999 music compact and, when doing so, allows certain columns to pass over
2000 each other if they will not collide. This type of passing over is not
2001 desirable with time signatures in traditional engraving. But how do we
2002 know if this passing over will happen before line breaking, as we are
2003 not sure what the X positions will be? We need a pure estimation of how
2004 much extra spacing height the time signatures would need to prevent this
2005 form of passing over without making this height so large as to
2006 overly-distort the Y-extent of an system, which could result in a very
2007 @q{loose} looking score with lots of horizontal space between columns.
2008 So, to approximate this extra spacing height, we use the Y-extent of a
2009 time signature's next-door-neighbor grobs via the pure-from-neighbor
2013 @item pros: By extending the extra spacing height of a time signature to
2014 that of its next-door-neighbors, we make sure that grobs to the right of
2015 it that could pass above or below it do not.
2017 @item cons: This over-estimation of the vertical height could prevent
2018 snug vertical spacing of systems, as the system will be registered as
2019 being taller at the point of the time signature than it actually is.
2020 This approach can be used for clefs and bar lines as well.
2024 As described above, Stems need pure height approximations when they are
2025 beamed, as we do not know the beam positions before line breaking. To
2026 estimate this pure height, we take all the stems in a beam and find
2027 their pure heights as if they were not beamed. Then, we find the union
2028 of all these pure heights and take the intersection between this
2029 interval (which is large) and an interval going from the note-head of a
2030 stem to infinity in the direction of the stem so that the interval stops
2034 @item pros: This is guaranteed to be at least as long as the beamed
2035 stem, as a beamed stem will never go over the ideal length of the
2036 extremal beam of a stem.
2038 @item cons: Certain stems will be estimated as being too long, which
2039 leads to the same problem of too-much-vertical-height as described
2045 @node Debugging tips
2046 @subsection Debugging tips
2047 A few questions to ask yourself when working with pure properties:
2050 @item Is the property really pure? Are you sure that its value could
2051 not be changed later in the compiling process due to other changes?
2053 @item Can the property be made to correspond even more exactly with the
2054 eventual impure property?
2056 @item For a spanner, is the pure property changing correctly depending
2057 on the starting and ending points of the spanner?
2059 @item For an Item, will the item's pure height need to act in horizontal
2060 spacing but not in vertical spacing? If so, use extra-spacing-height
2061 instead of pure height.
2066 @node LilyPond scoping
2067 @section LilyPond scoping
2069 The LilyPond language has a concept of scoping, i.e. you can do:
2075 (display (+ foo 2)))
2078 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
2079 nested scope inside the @file{.ly} file-level scope. @w{@code{foo = 1}}
2080 is translated in to a scheme variable definition.
2082 This implemented using modules, with each scope being an anonymous
2083 module that imports its enclosing scope's module.
2085 LilyPond's core, loaded from @file{.scm} files, is usually placed in the
2086 @code{lily} module, outside the @file{.ly} level. In the case of
2093 we want to reuse the built-in definitions, without changes effected in
2094 user-level @file{a.ly} leaking into the processing of @file{b.ly}.
2096 The user-accessible definition commands have to take care to avoid
2097 memory leaks that could occur when running multiple files. All
2098 information belonging to user-defined commands and markups is stored in
2099 a manner that allows it to be garbage-collected when the module is
2100 dispersed, either by being stored module-locally, or in weak hash
2104 @node Scheme->C interface
2105 @section Scheme->C interface
2107 Most of the C functions interfacing with Guile/Scheme used in LilyPond
2108 are described in the API Reference of the
2109 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
2110 GUILE Reference Manual}.
2112 The remaining functions are defined in @file{lily/lily-guile.cc},
2113 @file{lily/include/lily-guile.hh} and
2114 @file{lily/include/lily-guile-macros.hh}.
2115 Although their names are meaningful there's a few things you should know
2124 @subsection Comparison
2126 This is the trickiest part of the interface.
2128 Mixing Scheme values with C comparison operators won't produce any crash
2129 or warning when compiling but must be avoided:
2132 scm_string_p (scm_value) == SCM_BOOL_T
2135 As we can read in the reference, @code{scm_string_p} returns a Scheme
2136 value: either @code{#t} or @code{#f} which are written @code{SCM_BOOL_T}
2137 and @code{SCM_BOOL_F} in C. This will work, but it is not following
2138 to the API guidelines. For further information, read this discussion:
2141 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00646.html}
2144 There are functions in the Guile reference that returns C values
2145 instead of Scheme values. In our example, a function called
2146 @code{scm_is_string} (described after @code{string?} and @code{scm_string_p})
2147 returns the C value 0 or 1.
2149 So the best solution was simply:
2152 scm_is_string (scm_value)
2155 There a simple solution for almost every common comparison. Another example:
2156 we want to know if a Scheme value is a non-empty list. Instead of:
2159 (scm_is_true (scm_list_p (scm_value)) && scm_value != SCM_EOL)
2162 one can usually use:
2165 scm_is_pair (scm_value)
2168 since a list of at least one member is a pair. This test is
2169 cheap; @code{scm_list_p} is actually quite more complex since it makes
2170 sure that its argument is neither a `dotted list' where the last pair
2171 has a non-null @code{cdr}, nor a circular list. There are few
2172 situations where the complexity of those tests make sense.
2174 Unfortunately, there is not a @code{scm_is_[something]} function for
2175 everything. That's one of the reasons why LilyPond has its own Scheme
2176 interface. As a rule of thumb, tests that are cheap enough to be
2177 worth inlining tend to have such a C interface. So there is
2178 @code{scm_is_pair} but not @code{scm_is_list}, and @code{scm_is_eq}
2179 but not @code{scm_is_equal}.
2181 @subheading General definitions
2183 @subsubheading bool to_boolean (SCM b)
2185 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
2187 This should be used instead of @code{scm_is_true} and
2188 @code{scm_is_false} for properties since in LilyPond, unset properties
2189 are read as an empty list, and by convention unset Boolean properties
2190 default to false. Since both @code{scm_is_true} and
2191 @code{scm_is_false} only compare with @code{##f} in line with what
2192 Scheme's conditionals do, they are not really useful for checking the
2193 state of a Boolean property.
2195 @subsubheading bool ly_is_[something] (args)
2197 Behave the same as scm_is_[something] would do if it existed.
2199 @subsubheading bool is_[type] (SCM s)
2201 Test whether the type of @var{s} is [type].
2202 [type] is a LilyPond-only set of values (direction, axis...). More
2203 often than not, the code checks LilyPond specific C++-implemented
2206 @subsubheading [Type *] unsmob<Type> (SCM s)
2208 This tries converting a Scheme object to a pointer of the desired
2209 kind. If the Scheme object is of the wrong type, a pointer value
2210 of@w{ }@code{0} is returned, making this suitable for a Boolean test.
2213 @subsection Conversion
2215 @subheading General definitions
2217 @subsubheading bool to_boolean (SCM b)
2219 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
2221 This should be used instead of @code{scm_is_true} and @code{scm_is_false}
2222 for properties since empty lists are sometimes used to unset them.
2224 @subsubheading [C type] ly_scm2[C type] (SCM s)
2226 Behave the same as scm_to_[C type] would do if it existed.
2228 @subsubheading [C type] robust_scm2[C type] (SCM s, [C type] d)
2230 Behave the same as scm_to_[C type] would do if it existed.
2231 Return @var{d} if type verification fails.
2234 @node LilyPond miscellany
2235 @section LilyPond miscellany
2237 This is a place to dump information that may be of use to developers
2238 but doesn't yet have a proper home. Ideally, the length of this section
2239 would become zero as items are moved to other homes.
2243 * Spacing algorithms::
2244 * Info from Han-Wen email::
2245 * Music functions and GUILE debugging::
2246 * Articulations on EventChord::
2249 @node Spacing algorithms
2250 @subsection Spacing algorithms
2252 Here is information from an email exchange about spacing algorithms.
2254 On Thu, 2010-02-04 at 15:33 -0500, Boris Shingarov wrote:
2255 I am experimenting with some modifications to the line breaking code,
2256 and I am stuck trying to understand how some of it works. So far my
2257 understanding is that Simple_spacer operates on a vector of Grobs, and
2258 it is a well-known Constrained-QP problem (rods = constraints, springs
2259 = quadratic function to minimize). What I don't understand is, if the
2260 spacer operates at the level of Grobs, which are built at an earlier
2261 stage in the pipeline, how are the changes necessitated by differences
2262 in line breaking, taken into account? in other words, if I take the
2263 last measure of a line and place it on the next line, it is not just a
2264 matter of literally moving that graphic to where the start of the next
2265 line is, but I also need to draw a clef, key signature, and possibly
2266 other fundamental things -- but at that stage in the rendering
2267 pipeline, is it not too late??
2269 Joe Neeman answered:
2271 We create lots of extra grobs (eg. a BarNumber at every bar line) but
2272 most of them are not drawn. See the break-visibility property in
2275 Here is another e-mail exchange. Janek Warchoł asked for a starting point
2276 to fixing 1301 (change clef colliding with notes). Neil Puttock replied:
2278 The clef is on a loose column (it floats before the head), so the
2279 first place I'd look would be lily/spacing-loose-columns.cc (and
2280 possibly lily/spacing-determine-loose-columns.cc).
2281 I'd guess the problem is the way loose columns are spaced between
2282 other columns: in this snippet, the columns for the quaver and tuplet
2283 minim are so close together that the clef's column gets dumped on top
2284 of the quaver (since it's loose, it doesn't influence the spacing).
2286 @node Info from Han-Wen email
2287 @subsection Info from Han-Wen email
2289 In 2004, Douglas Linhardt decided to try starting a document that would
2290 explain LilyPond architecture and design principles. The material below
2291 is extracted from that email, which can be found at
2292 @uref{http://thread.gmane.org/gmane.comp.gnu.lilypond.devel/2992}.
2293 The headings reflect questions from Doug or comments from Han-Wen;
2294 the body text are Han-Wen's answers.
2296 @subheading Figuring out how things work.
2298 I must admit that when I want to know how a program works, I use grep
2299 and emacs and dive into the source code. The comments and the code
2300 itself are usually more revealing than technical documents.
2302 @subheading What's a grob, and how is one used?
2304 Graphical object - they are created from within engravers, either as
2305 Spanners (derived class) -slurs, beams- or Items (also a derived
2306 class) -notes, clefs, etc.
2308 There are two other derived classes System (derived from Spanner,
2309 containing a "line of music") and Paper_column (derived from Item, it
2310 contains all items that happen at the same moment). They are separate
2311 classes because they play a special role in the linebreaking process.
2313 @subheading What's a smob, and how is one used?
2315 A C(++) object that is encapsulated so it can be used as a Scheme
2316 object. See GUILE info, "19.3 Defining New Types (Smobs)"
2318 @subheading When is each C++ class constructed and used?
2325 In the parser.yy see the macro calls MAKE_MUSIC_BY_NAME().
2330 Constructed during "interpreting" phase.
2335 Executive branch of Contexts, plugins that create grobs, usually one
2336 engraver per grob type. Created together with context.
2346 These are not C++ classes per se. The idea of a Grob interface hasn't
2347 crystallized well. ATM, an interface is a symbol, with a bunch of grob
2348 properties. They are not objects that are created or destroyed.
2353 Objects that walk through different music classes, and deliver events
2354 in a synchronized way, so that notes that play together are processed
2355 at the same moment and (as a result) end up on the same horizontal position.
2357 Created during interpreting phase.
2359 BTW, the entry point for interpreting is ly:run-translator
2360 (ly_run_translator on the C++ side)
2364 @subheading Can you get to Context properties from a Music object?
2366 You can create music object with a Scheme function that reads context
2367 properties (the \applycontext syntax). However, that function is
2368 executed during Interpreting, so you can not really get Context
2369 properties from Music objects, since music objects are not directly
2370 connected to Contexts. That connection is made by the Music_iterators
2372 @subheading Can you get to Music properties from a Context object?
2374 Yes, if you are given the music object within a Context
2375 object. Normally, the music objects enter Contexts in synchronized
2376 fashion, and the synchronization is done by Music_iterators.
2378 @subheading What is the relationship between C++ classes and Scheme objects?
2380 Smobs are C++ objects in Scheme. Scheme objects (lists, functions) are
2381 manipulated from C++ as well using the GUILE C function interface
2384 @subheading How do Scheme procedures get called from C++ functions?
2386 scm_call_*, where * is an integer from 0 to 4.
2387 Also scm_c_eval_string (), scm_eval ()
2389 @subheading How do C++ functions get called from Scheme procedures?
2391 Export a C++ function to Scheme with LY_DEFINE.
2393 @subheading What is the flow of control in the program?
2395 Good question. Things used to be clear-cut, but we have Scheme
2396 and SMOBs now, which means that interactions do not follow a very
2397 rigid format anymore. See below for an overview, though.
2399 @subheading Does the parser make Scheme procedure calls or C++ function calls?
2401 Both. And the Scheme calls can call C++ and vice versa. It's nested,
2402 with the SCM datatype as lubrication between the interactions
2404 (I think the word "lubrication" describes the process better than the
2405 traditional word "glue")
2407 @subheading How do the front-end and back-end get started?
2409 Front-end: a file is parsed, the rest follows from that. Specifically,
2411 Parsing leads to a Music + Music_output_def object (see parser.yy,
2412 definition of toplevel_expression )
2414 A Music + Music_output_def object leads to a Global_context object (see
2415 ly_run_translator ())
2417 During interpreting, Global_context + Music leads to a bunch of
2418 Contexts (see Global_translator::run_iterator_on_me ()).
2420 After interpreting, Global_context contains a Score_context (which
2421 contains staves, lyrics etc.) as a child. Score_context::get_output ()
2422 spews a Music_output object (either a Paper_score object for notation
2423 or Performance object for MIDI).
2425 The Music_output object is the entry point for the backend (see
2426 ly_render_output ()).
2428 The main steps of the backend itself are in
2433 @file{paper-score.cc} , Paper_score::process_
2436 @file{system.cc} , System::get_lines()
2439 The step, where things go from grobs to output, is in
2440 System::get_line(): each grob delivers a Stencil (a Device
2441 independent output description), which is interpreted by our
2442 outputting backends (@file{scm/output-tex.scm} and
2443 @file{scm/output-ps.scm}) to produce TeX and PS.
2447 Interactions between grobs and putting things into .tex and .ps files
2448 have gotten a little more complex lately. Jan has implemented
2449 page-breaking, so now the backend also involves Paper_book,
2450 Paper_lines and other things. This area is still heavily in flux, and
2451 perhaps not something you should want to look at.
2453 @subheading How do the front-end and back-end communicate?
2455 There is no communication from backend to front-end. From front-end to
2456 backend is simply the program flow: music + definitions gives
2457 contexts, contexts yield output, after processing, output is written
2460 @subheading Where is the functionality associated with KEYWORDs?
2462 See @file{my-lily-lexer.cc} (keywords, there aren't that many)
2463 and @file{ly/*.ly} (most of the other backslashed @code{/\words} are identifiers)
2465 @subheading What Contexts/Properties/Music/etc. are available when they are processed?
2467 What do you mean exactly with this question?
2469 See @file{ly/engraver-init.ly} for contexts,
2470 see @file{scm/define-*.scm} for other objects.
2472 @subheading How do you decide if something is a Music, Context, or Grob property?
2473 Why is part-combine-status a Music property when it seems (IMO)
2474 to be related to the Staff context?
2476 The Music_iterators and Context communicate through two channels
2478 Music_iterators can set and read context properties, idem for
2479 Engravers and Contexts
2481 Music_iterators can send "synthetic" music events (which aren't in
2482 the input) to a context. These are caught by Engravers. This is
2483 mostly a one way communication channel.
2485 part-combine-status is part of such a synthetic event, used by
2486 Part_combine_iterator to communicate with Part_combine_engraver.
2489 @subheading Deciding between context and music properties
2491 I'm adding a property to affect how \autochange works. It seems to
2492 me that it should be a context property, but the Scheme autochange
2493 procedure has a Music argument. Does this mean I should use
2496 \autochange is one of these extra strange beasts: it requires
2497 look-ahead to decide when to change staves. This is achieved by
2498 running the interpreting step twice (see
2499 @file{scm/part-combiner.scm} , at the bottom), and
2500 storing the result of the first step (where to switch
2501 staves) in a Music property. Since you want to influence that
2502 where-to-switch list, your must affect the code in
2503 make-autochange-music (@file{scm/part-combiner.scm}).
2504 That code is called directly from the parser and there are no
2505 official "parsing properties" yet, so there is no generic way
2506 to tune \autochange. We would have to invent something new
2507 for this, or add a separate argument,
2510 \autochange #around-central-C ..music..
2514 where around-central-C is some function that is called from
2515 make-autochange-music.
2517 @subheading More on context and music properties
2519 From Neil Puttock, in response to a question about transposition:
2521 Context properties (using \set & \unset) are tied to engravers: they
2522 provide information relevant to the generation of graphical objects.
2524 Since transposition occurs at the music interpretation stage, it has
2525 no direct connection with engravers: the pitch of a note is fixed
2526 before a notehead is created. Consider the following minimal snippet:
2532 This generates (simplified) a NoteEvent, with its pitch and duration
2533 as event properties,
2539 (ly:make-duration 2 0 1 1)
2541 (ly:make-pitch 0 0 0)
2544 which the Note_heads_engraver hears. It passes this information on to
2545 the NoteHead grob it creates from the event, so the head's correct
2546 position and duration-log can be determined once it's ready for
2549 If we transpose the snippet,
2552 \transpose c d @{ c' @}
2555 the pitch is changed before it reaches the engraver (in fact, it
2556 happens just after the parsing stage with the creation of a
2557 TransposedMusic music object):
2563 (ly:make-duration 2 0 1 1)
2565 (ly:make-pitch 0 1 0)
2568 You can see an example of a music property relevant to transposition:
2572 \transpose c d @{ c'2 \withMusicProperty #'untransposable ##t c' @}
2575 -> the second c' remains untransposed.
2577 Take a look at @file{lily/music.cc} to see where the transposition takes place.
2580 @subheading How do I tell about the execution environment?
2582 I get lost figuring out what environment the code I'm looking at is in when it
2583 executes. I found both the C++ and Scheme autochange code. Then I was trying
2584 to figure out where the code got called from. I finally figured out that the
2585 Scheme procedure was called before the C++ iterator code, but it took me a
2586 while to figure that out, and I still didn't know who did the calling in the
2587 first place. I only know a little bit about Flex and Bison, so reading those
2588 files helped only a little bit.
2590 @emph{Han-Wen:} GDB can be of help here. Set a breakpoint in C++, and run. When you
2591 hit the breakpoint, do a backtrace. You can inspect Scheme objects
2592 along the way by doing
2595 p ly_display_scm(obj)
2598 this will display OBJ through GUILE.
2600 @node Music functions and GUILE debugging
2601 @subsection Music functions and GUILE debugging
2603 Ian Hulin was trying to do some debugging in music functions, and
2604 came up with the following question (edited and adapted to current
2608 I'm working on the Guile Debugger Stuff, and would like to try
2609 debugging a music function definition such as:
2613 #(define-music-function () ()
2614 #@{ \tag instrumental-part @{\mark \default@} #@} )
2617 It appears @code{conditionalMark} does not get set up as an
2618 equivalent of a Scheme
2621 (define conditionalMark = define-music-function () () ...
2625 although something gets defined because Scheme apparently recognizes
2628 #(set-break! conditionalMark)
2632 later on in the file without signalling any Guile errors.
2634 However the breakpoint trap is never encountered as
2635 @code{define-music-function} passed things on to
2636 @code{ly:make-music-function}, which is really C++ code
2637 @code{ly_make_music_function}, so Guile never finds out about the
2641 The answer in the mailing list archive at that time was less than
2642 helpful. The question already misidentifies the purpose of
2643 @code{ly:make-music-function} which is only called once at the
2644 time of @emph{defining} @code{conditionalMark} but is not involved
2645 in its later @emph{execution}.
2647 Here is the real deal:
2649 A music function is not the same as a GUILE function. It boxes
2650 both a proper Scheme function (with argument list and body from
2651 the @code{define-music-function} definition) along with a call
2652 signature representing the @emph{types} of both function and
2655 Those components can be reextracted using
2656 @code{ly:music-function-extract} and
2657 @code{ly:music-function-signature}, respectively.
2659 When LilyPond's parser encounters a music function call in its
2660 input, it reads, interprets, and verifies the arguments
2661 individually according to the call signature and @emph{then} calls
2662 the proper Scheme function.
2664 While it is actually possible these days to call a music function
2665 @emph{as if} it were a Scheme function itself, this pseudo-call
2666 uses its own wrapping code matching the argument list @emph{as a
2667 whole} to the call signature, substituting omitted optional
2668 arguments with defaults and verifying the result type.
2670 So putting a breakpoint on the music function itself will still
2671 not help with debugging uses of the function using LilyPond
2674 However, either calling mechanism ultimately calls the proper
2675 Scheme function stored as part of the music function, and that is
2676 where the breakpoint belongs:
2679 #(set-break! (ly:music-function-extract conditionalMark))
2682 will work for either calling mechanism.
2684 @node Articulations on EventChord
2685 @subsection Articulations on EventChord
2687 From David Kastrup's email
2688 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2012-02/msg00189.html}:
2690 LilyPond's typesetting does not act on music expressions and music
2691 events. It acts exclusively on stream events. It is the act of
2692 iterators to convert a music expression into a sequence of stream events
2693 played in time order.
2695 The EventChord iterator is pretty simple: it just takes its "elements"
2696 field when its time comes up, turns every member into a StreamEvent and
2697 plays that through the typesetting process. The parser currently
2698 appends all postevents belonging to a chord at the end of "elements",
2699 and thus they get played at the same point of time as the elements of
2700 the chord. Due to this design, you can add per-chord articulations or
2701 postevents or even assemble chords with a common stem by using parallel
2702 music providing additional notes/events: the typesetter does not see a
2703 chord structure or postevents belonging to a chord, it just sees a
2704 number of events occuring at the same point of time in a Voice context.
2706 So all one needs to do is let the EventChord iterator play articulations
2707 after elements, and then adding to articulations in EventChord is
2708 equivalent to adding them to elements (except in cases where the order