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/devnet/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 @node Programming without compiling
150 @section Programming without compiling
152 Much of the development work in LilyPond takes place by changing @file{*.ly} or
153 @file{*.scm} files. These changes can be made without compiling LilyPond. Such
154 changes are described in this section.
157 @subsection Modifying distribution files
159 Much of LilyPond is written in Scheme or LilyPond input files. These
160 files are interpreted when the program is run, rather than being compiled
161 when the program is built, and are present in all LilyPond distributions.
162 You will find @file{.ly} files in the @file{ly/} directory and the Scheme files in the
163 @file{scm/} directory. Both Scheme files and @file{.ly} files can be modified and
164 saved with any text editor. It's probably wise to make a backup copy of
165 your files before you modify them, although you can reinstall if the
166 files become corrupted.
168 Once you've modified the files, you can test the changes just by running
169 LilyPond on some input file. It's a good idea to create a file that
170 demonstrates the feature you're trying to add. This file will eventually
171 become a regression test and will be part of the LilyPond distribution.
173 @subsection Desired file formatting
175 Files that are part of the LilyPond distribution have Unix-style line
176 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
177 sure you use the necessary tools to ensure that Unix-style line endings are
178 preserved in the patches you create.
180 Tab characters should not be included in files for distribution. All
181 indentation should be done with spaces. Most editors have settings to
182 allow the setting of tab stops and ensuring that no tab characters are
183 included in the file.
185 Scheme files and LilyPond files should be written according to standard
186 style guidelines. Scheme file guidelines can be found at
187 @uref{http://community.schemewiki.org/?scheme-style}. Following these
188 guidelines will make your code easier to read. Both you and others that
189 work on your code will be glad you followed these guidelines.
191 For LilyPond files, you should follow the guidelines for LilyPond snippets
192 in the documentation. You can find these guidelines at
193 @ref{Texinfo introduction and usage policy}.
195 @node Finding functions
196 @section Finding functions
198 When making changes or fixing bugs in LilyPond, one of the initial
199 challenges is finding out where in the code tree the functions to
200 be modified live. With nearly 3000 files in the source tree,
201 trial-and-error searching is generally ineffective. This section
202 describes a process for finding interesting code.
204 @subsection Using the ROADMAP
206 The file ROADMAP is located in the main directory of the lilypond source.
207 ROADMAP lists all of the directories in the LilyPond source tree, along
208 with a brief description of the kind of files found in each directory.
209 This can be a very helpful tool for deciding which directories to search
210 when looking for a function.
213 @subsection Using grep to search
215 Having identified a likely subdirectory to search, the grep utility can
216 be used to search for a function name. The format of the grep command is
219 grep -i functionName subdirectory/*
222 This command will search all the contents of the directory subdirectory/
223 and display every line in any of the files that contains
224 functionName. The @option{-i} option makes @command{grep} ignore
225 case -- this can be very useful if you are not yet familiar with
226 our capitalization conventions.
228 The most likely directories to grep for function names are @file{scm/} for
229 scheme files, ly/ for lilypond input (@file{*.ly}) files, and @file{lily/} for C++
233 @subsection Using git grep to search
235 If you have used git to obtain the source, you have access to a
236 powerful tool to search for functions. The command:
239 git grep functionName
242 will search through all of the files that are present in the git
243 repository looking for functionName. It also presents the results
244 of the search using @code{less}, so the results are displayed one page
247 @subsection Searching on the git repository at Savannah
249 You can also use the equivalent of git grep on the Savannah server.
254 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
257 In the pulldown box that says commit, select grep.
260 Type functionName in the search box, and hit enter/return
264 This will initiate a search of the remote git repository.
270 This section describes style guidelines for LilyPond
277 * Naming conventions::
286 @subsection Languages
288 C++ and Python are preferred. Python code should use PEP 8.
292 @subsection Filenames
294 Definitions of classes that are only accessed via pointers (*) or
295 references (&) shall not be included as include files.
301 ".cc" Implementation files
302 ".icc" Inline definition files
303 ".tcc" non inline Template defs
307 (setq auto-mode-alist
308 (append '(("\\.make$" . makefile-mode)
309 ("\\.cc$" . c++-mode)
310 ("\\.icc$" . c++-mode)
311 ("\\.tcc$" . c++-mode)
312 ("\\.hh$" . c++-mode)
313 ("\\.pod$" . text-mode)
318 The class Class_name is coded in @q{class-name.*}
322 @subsection Indentation
324 Standard GNU coding style is used.
326 @subsubheading Indenting files with @code{fixcc.py} (recommended)
328 LilyPond provides a python script that will adjust the indentation
329 and spacing on a @code{.cc} or @code{.hh} file to very near the
333 scripts/auxiliar/fixcc.py FILENAME
336 This can be run on all files at once, but this is not recommended
337 for normal contributors or developers.
340 scripts/auxiliar/fixcc.py \
341 $(find flower lily -name '*cc' -o -name '*hh' | grep -v /out)
345 @subsubheading Indenting with emacs
347 The following hooks will produce indentation which is similar to
348 our official indentation as produced with @code{fixcc.py}.
351 (add-hook 'c++-mode-hook
354 (setq indent-tabs-mode nil))
357 If you like using font-lock, you can also add this to your
361 (setq font-lock-maximum-decoration t)
362 (setq c++-font-lock-keywords-3
364 c++-font-lock-keywords-3
365 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
370 @subheading Indenting with vim
372 Although emacs indentation is the GNU standard, acceptable
373 indentation can usually be accomplished with vim. Some hints for
385 filetype plugin indent on
387 set ignorecase smartcase
390 set statusline=%F%m%r%h%w\ %@{&ff@}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
393 " Remove trailing whitespace on write
394 autocmd BufWritePre * :%s/\s\+$//e
397 With this @file{.vimrc}, files can be reindented automatically by
398 highlighting the lines to be indented in visual mode (use V to
399 enter visual mode) and pressing @code{=}.
401 A @file{scheme.vim} file will help improve the indentation. This
402 one was suggested by Patrick McCarty. It should be saved in
403 @file{~/.vim/after/syntax/scheme.vim}.
406 " Additional Guile-specific 'forms'
407 syn keyword schemeSyntax define-public define*-public
408 syn keyword schemeSyntax define* lambda* let-keywords*
409 syn keyword schemeSyntax defmacro defmacro* define-macro
410 syn keyword schemeSyntax defmacro-public defmacro*-public
411 syn keyword schemeSyntax use-modules define-module
412 syn keyword schemeSyntax define-method define-class
414 " Additional LilyPond-specific 'forms'
415 syn keyword schemeSyntax define-markup-command define-markup-list-command
416 syn keyword schemeSyntax define-safe-public define-music-function
417 syn keyword schemeSyntax def-grace-function
419 " All of the above should influence indenting too
420 set lw+=define-public,define*-public
421 set lw+=define*,lambda*,let-keywords*
422 set lw+=defmacro,defmacro*,define-macro
423 set lw+=defmacro-public,defmacro*-public
424 set lw+=use-modules,define-module
425 set lw+=define-method,define-class
426 set lw+=define-markup-command,define-markup-list-command
427 set lw+=define-safe-public,define-music-function
428 set lw+=def-grace-function
430 " These forms should not influence indenting
434 " Try to highlight all ly: procedures
435 syn match schemeFunc "ly:[^) ]\+"
439 @node Naming conventions
440 @subsection Naming Conventions
442 Naming conventions have been established for LilyPond
445 @subheading Classes and Types
447 Classes begin with an uppercase letter, and words
448 in class names are separated with @code{_}:
456 Member variable names end with an underscore:
464 Macro names should be written in uppercase completely,
465 with words separated by @code{_}:
471 @subheading Variables
473 Variable names should be complete words, rather than abbreviations.
474 For example, it is preferred to use @code{thickness} rather than
475 @code{th} or @code{t}.
477 Multi-word variable names in C++ should have the words separated
478 by the underscore character (@q{_}):
481 cxx_multiword_variable
484 Multi-word variable names in Scheme should have the words separated
488 scheme-multiword-variable
492 @subsection Broken code
494 Do not write broken code. This includes hardwired dependencies,
495 hardwired constants, slow algorithms and obvious limitations. If
496 you can not avoid it, mark the place clearly, and add a comment
497 explaining shortcomings of the code.
499 Ideally, the comment marking the shortcoming would include
500 TODO, so that it is marked for future fixing.
502 We reject broken-in-advance on principle.
506 @subsection Code comments
508 Comments may not be needed if descriptive variable names are used
509 in the code and the logic is straightforward. However, if the
510 logic is difficult to follow, and particularly if non-obvious
511 code has been included to resolve a bug, a comment describing
512 the logic and/or the need for the non-obvious code should be included.
514 There are instances where the current code could be commented better.
515 If significant time is required to understand the code as part of
516 preparing a patch, it would be wise to add comments reflecting your
517 understanding to make future work easier.
520 @node Handling errors
521 @subsection Handling errors
523 As a general rule, you should always try to continue computations,
524 even if there is some kind of error. When the program stops, it
525 is often very hard for a user to pinpoint what part of the input
526 causes an error. Finding the culprit is much easier if there is
527 some viewable output.
529 So functions and methods do not return errorcodes, they never
530 crash, but report a programming_error and try to carry on.
532 Error and warning messages need to be localized.
536 @subsection Localization
538 This document provides some guidelines to help programmers write
540 messages. To help translations, user messages must follow
541 uniform conventions. Follow these rules when coding for LilyPond.
542 Hopefully, this can be replaced by general GNU guidelines in the
543 future. Even better would be to have an English (en_BR, en_AM)
544 guide helping programmers writing consistent messages for all GNU
547 Non-preferred messages are marked with `+'. By convention,
548 ungrammatical examples are marked with `*'. However, such ungrammatical
549 examples may still be preferred.
554 Every message to the user should be localized (and thus be marked
555 for localization). This includes warning and error messages.
558 Do not localize/gettextify:
562 `programming_error ()'s
565 `programming_warning ()'s
571 output strings (PostScript, TeX, etc.)
576 Messages to be localized must be encapsulated in `_ (STRING)' or
577 `_f (FORMAT, ...)'. E.g.:
580 warning (_ ("need music in a score"));
581 error (_f ("cannot open file: `%s'", file_name));
584 In some rare cases you may need to call `gettext ()' by hand. This
585 happens when you pre-define (a list of) string constants for later
586 use. In that case, you'll probably also need to mark these string
587 constants for translation, using `_i (STRING)'. The `_i' macro is
588 a no-op, it only serves as a marker for `xgettext'.
591 char const* messages[] = @{
592 _i ("enable debugging output"),
593 _i ("ignore lilypond version"),
600 puts (gettext (messages i));
604 See also @file{flower/getopt-long.cc} and @file{lily/main.cc}.
607 Do not use leading or trailing whitespace in messages. If you need
608 whitespace to be printed, prepend or append it to the translated
612 message ("Calculating line breaks..." + " ");
616 Error or warning messages displayed with a file name and line
617 number never start with a capital, eg,
620 foo.ly: 12: not a duration: 3
623 Messages containing a final verb, or a gerund (`-ing'-form) always
624 start with a capital. Other (simpler) messages start with a
630 Not declaring: `foo'.
634 Avoid abbreviations or short forms, use `cannot' and `do not'
635 rather than `can't' or `don't'
636 To avoid having a number of different messages for the same
637 situation, well will use quoting like this `"message: `%s'"' for all
638 strings. Numbers are not quoted:
641 _f ("cannot open file: `%s'", name_str)
642 _f ("cannot find character number: %d", i)
646 Think about translation issues. In a lot of cases, it is better to
647 translate a whole message. English grammar must not be imposed on the
648 translator. So, instead of
651 stem at + moment.str () + does not fit in beam
657 _f ("stem at %s does not fit in beam", moment.str ())
661 Split up multi-sentence messages, whenever possible. Instead of
664 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
665 warning (_f ("cannot find font `%s', loading default", font_name));
671 warning (_ ("out of tune:"));
672 warning (_f ("cannot find: `%s', "Key_engraver"));
673 warning (_f ("cannot find font: `%s', font_name));
674 warning (_f ("Loading default font"));
678 If you must have multiple-sentence messages, use full punctuation.
679 Use two spaces after end of sentence punctuation. No punctuation
680 (esp. period) is used at the end of simple messages.
683 _f ("Non-matching braces in text `%s', adding braces", text)
684 _ ("Debug output disabled. Compiled with NPRINT.")
685 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
689 Do not modularize too much; words frequently cannot be translated
690 without context. It is probably safe to treat most occurrences of
691 words like stem, beam, crescendo as separately translatable words.
694 When translating, it is preferable to put interesting information
695 at the end of the message, rather than embedded in the middle.
696 This especially applies to frequently used messages, even if this
697 would mean sacrificing a bit of eloquence. This holds for original
698 messages too, of course.
701 en: cannot open: `foo.ly'
702 + nl: kan `foo.ly' niet openen (1)
703 kan niet openen: `foo.ly'* (2)
704 niet te openen: `foo.ly'* (3)
708 The first nl message, although grammatically and stylistically
709 correct, is not friendly for parsing by humans (even if they speak
710 dutch). I guess we would prefer something like (2) or (3).
713 Do not run make po/po-update with GNU gettext < 0.10.35
718 @node Warnings Errors Progress and Debug Output
719 @section Warnings, Errors, Progress and Debug Output
721 @unnumberedsubsec Available log levels
723 LilyPond has several loglevels, which specify how verbose the output on
724 the console should be:
726 @item NONE: No output at all, even on failure
727 @item ERROR: Only error messages
728 @item WARN: Only error messages and warnings
729 @item BASIC_PROGRESS: Warnings, errors and basic progress (success, etc.)
730 @item PROGRESS: Warnings, errors and full progress messages
731 @item INFO: Warnings, errors, progress and more detailed information (default)
732 @item DEBUG: All messages, including full debug messages (very verbose!)
735 The loglevel can either be set with the environment variable
736 @code{LILYPOND_LOGLEVEL} or on the command line with the @option{--loglevel=...}
739 @unnumberedsubsec Functions for debug and log output
741 LilyPond has two different types of error and log functions:
745 If a warning or error is caused by an identified position in the input file,
746 e.g. by a grob or by a music expression, the functions of the @code{Input}
747 class provide logging functionality that prints the position of the message
748 in addition to the message.
751 If a message can not be associated with a particular position in an input file,
752 e.g. the output file cannot be written, then the functions in the
753 @code{flower/include/warn.hh} file will provide logging functionality that
754 only prints out the message, but no location.
758 There are also Scheme functions to access all of these logging functions from
759 scheme. In addition, the Grob class contains some convenience wrappers for
760 even easier access to these functions.
762 The message and debug functions in @code{warn.hh} also have an optional
763 argument @code{newline}, which specifies whether the message should always
764 start on a new line or continue a previous message.
765 By default, @code{progress_indication} does NOT start on a new line, but rather
766 continue the previous output. They also do not have a particular input
767 position associated, so there are no progress functions in the Input class.
768 All other functions by default start their output on a new line.
770 The error functions come in three different flavors: fatal error messages,
771 programming error messages and normal error messages. Errors written
772 by the @code{error ()} function will cause LilyPond to exit immediately,
773 errors by @code{Input::error ()} will continue the compilation, but
774 return a non-zero return value of the lilypond call (i.e. indicate an
775 unsuccessful program execution). All other errors will be printed on the
776 console, but not exit LilyPond or indicate an unsuccessful return code.
777 Their only differences to a warnings are the displayed text and that
778 they will be shown with loglevel @code{ERROR}.
780 If the Scheme option @code{warning-as-error} is set, any warning will be
781 treated as if @code{Input::error} was called.
784 @unnumberedsubsec All logging functions at a glance
786 @multitable @columnfractions 0.16 0.42 0.42
788 @tab C++, no location
789 @tab C++ from input location
792 @tab @code{error ()}, @code{programming_error (msg)}, @code{non_fatal_error (msg)}
793 @tab @code{Input::error (msg)}, @code{Input::programming_error (msg)}
796 @tab @code{warning (msg)}
797 @tab @code{Input::warning (msg)}
800 @tab @code{basic_progress (msg)}
804 @tab @code{progress_indication (msg)}
808 @tab @code{message (msg)}
809 @tab @code{Input::message (msg)}
812 @tab @code{debug_output (msg)}
813 @tab @code{Input::debug_output (msg)}
819 @tab Scheme, music expression
822 @tab @code{Grob::programming_error (msg)}
826 @tab @code{Grob::warning (msg)}
827 @tab @code{(ly:music-warning music msg)}
839 @tab @code{(ly:music-message music msg)}
848 @tab Scheme, no location
849 @tab Scheme, input location
853 @tab @code{(ly:error msg args)}, @code{(ly:programming-error msg args)}
856 @tab @code{(ly:warning msg args)}
857 @tab @code{(ly:input-warning input msg args)}
860 @tab @code{(ly:basic-progress msg args)}
864 @tab @code{(ly:progress msg args)}
868 @tab @code{(ly:message msg args)}
869 @tab @code{(ly:input-message input msg args)}
872 @tab @code{(ly:debug msg args)}
880 @node Debugging LilyPond
881 @section Debugging LilyPond
883 The most commonly used tool for debugging LilyPond is the GNU
884 debugger gdb. The gdb tool is used for investigating and debugging
885 core Lilypond code written in C++. Another tool is available for
886 debugging Scheme code using the Guile debugger. This section
887 describes how to use both gdb and the Guile Debugger.
890 * Debugging overview::
891 * Debugging C++ code::
892 * Debugging Scheme code::
895 @node Debugging overview
896 @subsection Debugging overview
898 Using a debugger simplifies troubleshooting in at least two ways.
900 First, breakpoints can be set to pause execution at any desired point.
901 Then, when execution has paused, debugger commands can be issued to
902 explore the values of various variables or to execute functions.
904 Second, the debugger can display a stack trace, which shows the
905 sequence in which functions have been called and the arguments
906 passed to the called functions.
908 @node Debugging C++ code
909 @subsection Debugging C++ code
911 The GNU debugger, gdb, is the principal tool for debugging C++ code.
913 @subheading Compiling LilyPond for use with gdb
915 In order to use gdb with LilyPond, it is necessary to compile
916 LilyPond with debugging information. This is accomplished by running
917 the following commands in the main LilyPond source directory.
920 ./configure --disable-optimising
924 This will create a version of LilyPond containing debugging
925 information that will allow the debugger to tie the source code
926 to the compiled code.
928 You should not do @var{make install} if you want to use a debugger
929 with LilyPond. The @var{make install} command will strip debugging
930 information from the LilyPond binary.
932 @subheading Typical gdb usage
934 Once you have compiled the Lilypond image with the necessary
935 debugging information it will have been written to a location in a
936 subfolder of your current working directory:
942 This is important as you will need to let gdb know where to find the
943 image containing the symbol tables. You can invoke gdb from the
944 command line using the following:
950 This loads the LilyPond symbol tables into gdb. Then, to run
951 LilyPond on @file{test.ly} under the debugger, enter the following:
960 As an alternative to running gdb at the command line you may try
961 a graphical interface to gdb such as ddd:
967 You can also use sets of standard gdb commands stored in a .gdbinit
968 file (see next section).
970 @subheading Typical .gdbinit files
972 The behavior of gdb can be readily customized through the use of a
973 @var{.gdbinit} file. A @var{.gdbinit} file is a file named
974 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
975 that is placed in a user's home directory.
977 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
978 for all errors and defines functions for displaying scheme objects
979 (ps), grobs (pgrob), and parsed music expressions (pmusic).
982 file lily/out/lilypond
984 b Grob::programming_error
987 print ly_display_scm($arg0)
990 print ly_display_scm($arg0->self_scm_)
991 print ly_display_scm($arg0->mutable_property_alist_)
992 print ly_display_scm($arg0->immutable_property_alist_)
993 print ly_display_scm($arg0->object_alist_)
996 print ly_display_scm($arg0->self_scm_)
997 print ly_display_scm($arg0->mutable_property_alist_)
998 print ly_display_scm($arg0->immutable_property_alist_)
1002 @node Debugging Scheme code
1003 @subsection Debugging Scheme code
1005 Scheme code can be developed using the Guile command line
1006 interpreter @code{top-repl}. You can either investigate
1007 interactively using just Guile or you can use the debugging
1008 tools available within Guile.
1010 @subheading Using Guile interactively with LilyPond
1012 In order to experiment with Scheme programming in the LilyPond
1013 environment, it is necessary to have a Guile interpreter that
1014 has all the LilyPond modules loaded. This requires the following
1017 First, define a Scheme symbol for the active module in the @file{.ly} file:
1020 #(module-define! (resolve-module '(guile-user))
1021 'lilypond-module (current-module))
1024 Now place a Scheme function in the @file{.ly} file that gives an
1025 interactive Guile prompt:
1031 When the @file{.ly} file is compiled, this causes the compilation to be
1032 interrupted and an interactive guile prompt to appear. Once the
1033 guile prompt appears, the LilyPond active module must be set as the
1034 current guile module:
1037 guile> (set-current-module lilypond-module)
1040 You can demonstrate these commands are operating properly by typing the name
1041 of a LilyPond public scheme function to check it has been defined:
1044 guile> fret-diagram-verbose-markup
1045 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
1048 If the LilyPond module has not been correctly loaded, an error
1049 message will be generated:
1052 guile> fret-diagram-verbose-markup
1053 ERROR: Unbound variable: fret-diagram-verbose-markup
1054 ABORT: (unbound-variable)
1057 Once the module is properly loaded, any valid LilyPond Scheme
1058 expression can be entered at the interactive prompt.
1060 After the investigation is complete, the interactive guile
1061 interpreter can be exited:
1067 The compilation of the @file{.ly} file will then continue.
1069 @subheading Using the Guile debugger
1071 To set breakpoints and/or enable tracing in Scheme functions, put
1074 \include "guile-debugger.ly"
1077 in your input file after any scheme procedures you have defined in
1078 that file. This will invoke the Guile command-line after having set
1079 up the environment for the debug command-line. When your input file
1080 is processed, a guile prompt will be displayed. You may now enter
1081 commands to set up breakpoints and enable tracing by the Guile debugger.
1083 @subheading Using breakpoints
1085 At the guile prompt, you can set breakpoints with
1086 the @code{set-break!} procedure:
1089 guile> (set-break! my-scheme-procedure)
1092 Once you have set the desired breakpoints, you exit the guile repl frame
1099 Then, when one of the scheme routines for which you have set
1100 breakpoints is entered, guile will interrupt execution in a debug
1101 frame. At this point you will have access to Guile debugging
1102 commands. For a listing of these commands, type:
1108 Alternatively you may code the breakpoints in your Lilypond source
1109 file using a command such as:
1112 #(set-break! my-scheme-procedure)
1115 immediately after the @code{\include} statement. In this case the
1116 breakpoint will be set straight after you enter the @code{(quit)}
1117 command at the guile prompt.
1119 Embedding breakpoint commands like this is particularly useful if
1120 you want to look at how the Scheme procedures in the @file{.scm}
1121 files supplied with LilyPond work. To do this, edit the file in
1122 the relevant directory to add this line near the top:
1125 (use-modules (scm guile-debugger))
1128 Now you can set a breakpoint after the procedure you are interested
1129 in has been declared. For example, if you are working on routines
1130 called by @var{print-book-with} in @file{lily-library.scm}:
1133 (define (print-book-with parser book process-procedure)
1134 (let* ((paper (ly:parser-lookup parser '$defaultpaper))
1135 (layout (ly:parser-lookup parser '$defaultlayout))
1136 (outfile-name (get-outfile-name parser)))
1137 (process-procedure book paper layout outfile-name)))
1139 (define-public (print-book-with-defaults parser book)
1140 (print-book-with parser book ly:book-process))
1142 (define-public (print-book-with-defaults-as-systems parser book)
1143 (print-book-with parser book ly:book-process-to-systems))
1147 At this point in the code you could add this to set a breakpoint at
1151 (set-break! print-book-with)
1154 @subheading Tracing procedure calls and evaluator steps
1156 Two forms of trace are available:
1159 (set-trace-call! my-scheme-procedure)
1165 (set-trace-subtree! my-scheme-procedure)
1168 @code{set-trace-call!} causes Scheme to log a line to the standard
1169 output to show when the procedure is called and when it exits.
1171 @code{set-trace-subtree!} traces every step the Scheme evaluator
1172 performs in evaluating the procedure.
1174 @node Tracing object relationships
1175 @section Tracing object relationships
1177 Understanding the LilyPond source often boils down to figuring out what
1178 is happening to the Grobs. Where (and why) are they being created,
1179 modified and destroyed? Tracing Lily through a debugger in order to
1180 identify these relationships can be time-consuming and tedious.
1182 In order to simplify this process, a facility has been added to
1183 display the grobs that are created and the properties that are set
1184 and modified. Although it can be complex to get set up, once set up
1185 it easily provides detailed information about the life of grobs
1186 in the form of a network graph.
1188 Each of the steps necessary to use the graphviz utility
1193 @item Installing graphviz
1195 In order to create the graph of the object relationships, it is
1196 first necessary to install Graphviz. Graphviz is available for a
1197 number of different platforms:
1200 @uref{http://www.graphviz.org/Download..php}
1203 @item Modifying config.make
1205 In order for the Graphviz tool to work, config.make must be modified.
1206 It is probably a good idea to first save a copy of config.make under
1207 a different name. Then, edit config.make by removing every occurrence
1208 of @option{-DNDEBUG}.
1210 @item Rebuilding LilyPond
1212 The executable code of LilyPond must be rebuilt from scratch:
1215 make -C lily clean && make -C lily
1218 @item Create a graphviz-compatible @file{.ly} file
1220 In order to use the graphviz utility, the @file{.ly} file must include
1221 @file{ly/graphviz-init.ly}, and should then specify the
1222 grobs and symbols that should be tracked. An example of this
1223 is found in @file{input/regression/graphviz.ly}.
1225 @item Run lilypond with output sent to a log file
1227 The Graphviz data is sent to stderr by lilypond, so it is
1228 necessary to redirect stderr to a logfile:
1231 lilypond graphviz.ly 2> graphviz.log
1234 @item Edit the logfile
1236 The logfile has standard lilypond output, as well as the Graphviz
1237 output data. Delete everything from the beginning of the file
1238 up to but not including the first occurrence of @code{digraph}.
1240 Also, delete the final lilypond message about success from the end
1243 @item Process the logfile with @code{dot}
1245 The directed graph is created from the log file with the program
1249 dot -Tpdf graphviz.log > graphviz.pdf
1254 The pdf file can then be viewed with any pdf viewer.
1256 When compiled without @option{-DNDEBUG}, lilypond may run slower
1257 than normal. The original configuration can be restored by either
1258 renaming the saved copy of @code{config.make} or rerunning
1259 @code{configure}. Then rebuild lilypond with
1262 make -C lily clean && make -C lily
1266 @node Adding or modifying features
1267 @section Adding or modifying features
1269 When a new feature is to be added to LilyPond, it is necessary to
1270 ensure that the feature is properly integrated to maintain
1271 its long-term support. This section describes the steps necessary
1272 for feature addition and modification.
1277 * Write regression tests::
1278 * Write convert-ly rule::
1279 * Automatically update documentation::
1280 * Manually update documentation::
1281 * Edit changes.tely::
1282 * Verify successful build::
1283 * Verify regression tests::
1284 * Post patch for comments::
1286 * Closing the issues::
1289 @node Write the code
1290 @subsection Write the code
1292 You should probably create a new git branch for writing the code, as that
1293 will separate it from the master branch and allow you to continue
1294 to work on small projects related to master.
1296 Please be sure to follow the rules for programming style discussed
1297 earlier in this chapter.
1300 @node Write regression tests
1301 @subsection Write regression tests
1303 In order to demonstrate that the code works properly, you will
1304 need to write one or more regression tests. These tests are
1305 typically @file{.ly} files that are found in @file{input/regression}.
1307 Regression tests should be as brief as possible to demonstrate the
1308 functionality of the code.
1310 Regression tests should generally cover one issue per test. Several
1311 short, single-issue regression tests are preferred to a single, long,
1312 multiple-issue regression test.
1314 Use existing regression tests as templates to demonstrate the type of
1315 header information that should be included in a regression test.
1318 @node Write convert-ly rule
1319 @subsection Write convert-ly rule
1321 If the modification changes the input syntax, a convert-ly rule
1322 should be written to automatically update input files from older
1325 convert-ly rules are found in python/convertrules.py
1327 If possible, the convert-ly rule should allow automatic updating
1328 of the file. In some cases, this will not be possible, so the
1329 rule will simply point out to the user that the feature needs
1332 @subsubheading Updating version numbers
1334 If a development release occurs between you writing your patch and
1335 having it approved+pushed, you will need to update the version
1336 numbers in your tree. This can be done with:
1339 scripts/auxiliar/update-patch-version old.version.number new.version.number
1342 It will change all files in git, so use with caution and examine
1346 @node Automatically update documentation
1347 @subsection Automatically update documentation
1349 @command{convert-ly} should be used to update the documentation,
1350 the snippets, and the regression tests. This not only makes the
1351 necessary syntax changes, it also tests the @command{convert-ly}
1354 The automatic updating is performed by moving to the top-level
1355 source directory, then running:
1358 scripts/auxiliar/update-with-convert-ly.sh
1361 If you did an out-of-tree build, pass in the relative path:
1364 BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh
1368 @node Manually update documentation
1369 @subsection Manually update documentation
1371 Where the convert-ly rule is not able to automatically update the inline
1372 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
1373 documentation must be manually updated. The inline snippets that require
1374 changing must be changed in the English version of the docs and all
1375 translated versions. If the inline code is not changed in the
1376 translated documentation, the old snippets will show up in the
1377 English version of the documentation.
1379 Where the convert-ly rule is not able to automatically update snippets
1380 in Documentation/snippets/, those snippets must be manually updated.
1381 Those snippets should be copied to Documentation/snippets/new. The
1382 comments at the top of the snippet describing its automatic generation
1383 should be removed. All translated texidoc strings should be removed.
1384 The comment @qq{% begin verbatim} should be removed. The syntax of
1385 the snippet should then be manually edited.
1387 Where snippets in Documentation/snippets are made obsolete, the snippet
1388 should be copied to Documentation/snippets/new. The comments and
1389 texidoc strings should be removed as described above. Then the body
1390 of the snippet should be changed to:
1394 This snippet is deprecated as of version X.Y.Z and
1395 will be removed from the documentation.
1400 where X.Y.Z is the version number for which the convert-ly rule was
1403 Update the snippet files by running:
1406 scripts/auxiliar/makelsr.py
1409 Where the convert-ly rule is not able to automatically update regression
1410 tests, the regression tests in input/regression should be manually
1413 Although it is not required, it is helpful if the developer
1414 can write relevant material for inclusion in the Notation
1415 Reference. If the developer does not feel qualified to write
1416 the documentation, a documentation editor will be able to
1417 write it from the regression tests. The text that is added to
1418 or removed from the documentation should be changed only in
1419 the English version.
1422 @node Edit changes.tely
1423 @subsection Edit changes.tely
1425 An entry should be added to Documentation/changes.tely to describe
1426 the feature changes to be implemented. This is especially important
1427 for changes that change input file syntax.
1429 Hints for changes.tely entries are given at the top of the file.
1431 New entries in changes.tely go at the top of the file.
1433 The changes.tely entry should be written to show how the new change
1434 improves LilyPond, if possible.
1437 @node Verify successful build
1438 @subsection Verify successful build
1440 When the changes have been made, successful completion must be
1448 When these commands complete without error, the patch is
1449 considered to function successfully.
1451 Developers on Windows who are unable to build LilyPond should
1452 get help from a Linux or OSX developer to do the make tests.
1455 @node Verify regression tests
1456 @subsection Verify regression tests
1458 In order to avoid breaking LilyPond, it is important to verify that
1459 the regression tests succeed, and that no unwanted changes are
1460 introduced into the output. This process is described in
1461 @ref{Regtest comparison}.
1463 @subheading Typical developer's edit/compile/test cycle
1465 TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
1466 @code{test-baseline}, @code{check}, @code{clean},
1467 @code{test-redo}? Neil Puttock says it is useful for
1468 everything but @code{clean}, which is disk-limited.
1469 Need to check formally.
1478 make [-j@var{X} CPU_COUNT=@var{X}] check
1482 Edit/compile/test cycle:
1485 @emph{## edit source files, then...}
1487 make clean @emph{## only if needed (see below)}
1488 make [-j@var{X}] @emph{## only if needed (see below)}
1489 make test-redo @emph{## redo files differing from baseline}
1490 make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?}
1501 If you modify any source files that have to be compiled (such as
1502 @file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
1503 then you must run @command{make} before @command{make test-redo},
1504 so @command{make} can compile the modified files and relink all
1505 the object files. If you only modify files which are interpreted,
1506 like those in the @file{scm/} and @file{ly/} directories, then
1507 @command{make} is not needed before @command{make test-redo}.
1509 TODO: Fix the following paragraph. You can do @command{rm mf/out/*}
1510 instead of make clean, and you can probably do
1511 @command{make -C mf/ clean} as well, but I haven't checked it -- cds
1513 Also, if you modify any font definitions in the @file{mf/}
1514 directory then you must run @command{make clean} and
1515 @command{make} before running @command{make test-redo}. This will
1516 recompile everything, whether modified or not, and takes a lot
1519 Running @command{make@tie{}check} will leave an HTML page
1520 @file{out/test-results/index.html}. This page shows all the
1521 important differences that your change introduced, whether in the
1522 layout, MIDI, performance or error reporting.
1527 @node Post patch for comments
1528 @subsection Post patch for comments
1530 See @ref{Uploading a patch for review}.
1534 @subsection Push patch
1536 Once all the comments have been addressed, the patch can be pushed.
1538 If the author has push privileges, the author will push the patch.
1539 Otherwise, a developer with push privileges will push the patch.
1542 @node Closing the issues
1543 @subsection Closing the issues
1545 Once the patch has been pushed, all the relevant issues should be
1548 On Rietveld, the author should log in and close the issue either by
1549 using the @q{Edit Issue} link, or by clicking the circled x icon
1550 to the left of the issue name.
1552 If the changes were in response to a feature request on the Google
1553 issue tracker for LilyPond, the author should change the status to
1554 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was
1555 fixed in version x.y.z. If
1556 the author does not have privileges to change the status, an email
1557 should be sent to bug-lilypond requesting the BugMeister to change
1561 @node Iterator tutorial
1562 @section Iterator tutorial
1564 TODO -- this is a placeholder for a tutorial on iterators
1566 Iterators are routines written in C++ that process music expressions
1567 and sent the music events to the appropriate engravers and/or
1570 See a short example discussing iterators and their duties in
1571 @ref{Articulations on EventChord}.
1574 @node Engraver tutorial
1575 @section Engraver tutorial
1577 Engravers are C++ classes that catch music events and
1578 create the appropriate grobs for display on the page. Though the
1579 majority of engravers are responsible for the creation of a single grob,
1580 in some cases (e.g. @code{New_fingering_engraver}), several different grobs
1583 Engravers listen for events and acknowledge grobs. Events are passed to
1584 the engraver in time-step order during the iteration phase. Grobs are
1585 made available to the engraver when they are created by other engravers
1586 during the iteration phase.
1590 * Useful methods for information processing::
1591 * Translation process::
1592 * Preventing garbage collection for SCM member variables::
1593 * Listening to music events::
1594 * Acknowledging grobs::
1595 * Engraver declaration/documentation::
1598 @node Useful methods for information processing
1599 @subsection Useful methods for information processing
1601 An engraver inherits the following public methods from the Translator
1602 base class, which can be used to process listened events and acknowledged
1606 @item @code{virtual void initialize ()}
1607 @item @code{void start_translation_timestep ()}
1608 @item @code{void process_music ()}
1609 @item @code{void process_acknowledged ()}
1610 @item @code{void stop_translation_timestep ()}
1611 @item @code{virtual void finalize ()}
1614 These methods are listed in order of translation time, with
1615 @code{initialize ()} and @code{finalize ()} bookending the whole
1616 process. @code{initialize ()} can be used for one-time initialization
1617 of context properties before translation starts, whereas
1618 @code{finalize ()} is often used to tie up loose ends at the end of
1619 translation: for example, an unterminated spanner might be completed
1620 automatically or reported with a warning message.
1623 @node Translation process
1624 @subsection Translation process
1626 At each timestep in the music, translation proceeds by calling the
1627 following methods in turn:
1629 @code{start_translation_timestep ()} is called before any user
1630 information enters the translators, i.e., no property operations
1631 (\set, \override, etc.) or events have been processed yet.
1633 @code{process_music ()} and @code{process_acknowledged ()} are called
1634 after all events in the current time step have been heard, or all
1635 grobs in the current time step have been acknowledged. The latter
1636 tends to be used exclusively with engravers which only acknowledge
1637 grobs, whereas the former is the default method for main processing
1640 @code{stop_translation_timestep ()} is called after all user
1641 information has been processed prior to beginning the translation for
1645 @node Preventing garbage collection for SCM member variables
1646 @subsection Preventing garbage collection for SCM member variables
1648 In certain cases, an engraver might need to ensure private Scheme
1649 variables (with type SCM) do not get swept away by Guile's garbage
1650 collector: for example, a cache of the previous key signature which
1651 must persist between timesteps. The method
1652 @code{virtual derived_mark () const} can be used in such cases:
1655 Engraver_name::derived_mark ()
1657 scm_gc_mark (private_scm_member_)
1662 @node Listening to music events
1663 @subsection Listening to music events
1665 External interfaces to the engraver are implemented by protected
1666 macros including one or more of the following:
1669 @item @code{DECLARE_TRANSLATOR_LISTENER (event_name)}
1670 @item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)}
1674 where @var{event_name} is the type of event required to provide the
1675 input the engraver needs and @var{Engraver_name} is the name of the
1678 Following declaration of a listener, the method is implemented as follows:
1681 IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)
1683 Engraver_name::listen_event_name (Stream event *event)
1685 ...body of listener method...
1690 @node Acknowledging grobs
1691 @subsection Acknowledging grobs
1693 Some engravers also need information from grobs as they are created
1694 and as they terminate. The mechanism and methods to obtain this
1695 information are set up by the macros:
1698 @item @code{DECLARE_ACKNOWLEDGER (grob_interface)}
1699 @item @code{DECLARE_END_ACKNOWLEDGER (grob_interface)}
1702 where @var{grob_interface} is an interface supported by the
1703 grob(s) which should be acknowledged. For example, the following
1704 code would declare acknowledgers for a @code{NoteHead} grob (via the
1705 @code{note-head-interface}) and any grobs which support the
1706 @code{side-position-interface}:
1709 @code{DECLARE_ACKNOWLEDGER (note_head)}
1710 @code{DECLARE_ACKNOWLEDGER (side_position)}
1713 The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific
1714 acknowledger which will be called whenever a spanner ends.
1716 Following declaration of an acknowledger, the method is coded as follows:
1720 Engraver_name::acknowledge_interface_name (Grob_info info)
1722 ...body of acknowledger method...
1726 Acknowledge functions are called in the order engravers are
1727 @code{\consist}-ed (the only exception is if you set
1728 @code{must-be-last} to @code{#t}).
1730 If useful things are to be done to the acknowledged grobs, this
1731 should be deferred until all the acknowledging has finished, i.e.,
1732 store the acknowledged grobs and process the information in a
1733 @code{process-acknowledged ()} or @code{stop-translation-timestep ()}
1737 @node Engraver declaration/documentation
1738 @subsection Engraver declaration/documentation
1740 An engraver must have a public macro
1743 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1747 where @code{Engraver_name} is the name of the engraver. This
1748 defines the common variables and methods used by every engraver.
1750 At the end of the engraver file, one or both of the following
1751 macros are generally called to document the engraver in the
1752 Internals Reference:
1755 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob_interface)}
1756 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1757 Engraver_creates, Engraver_reads, Engraver_writes)}
1761 where @code{Engraver_name} is the name of the engraver, @code{grob_interface}
1762 is the name of the interface that will be acknowledged,
1763 @code{Engraver_doc} is a docstring for the engraver,
1764 @code{Engraver_creates} is the set of grobs created by the engraver,
1765 @code{Engraver_reads} is the set of properties read by the engraver,
1766 and @code{Engraver_writes} is the set of properties written by
1769 The @code{ADD_ACKNOWLEDGER} and @code{ADD_TRANSLATOR} macros use a
1770 non-standard indentation system. Each interface, grob, read property,
1771 and write property is on its own line, and the closing parenthesis
1772 and semicolon for the macro all occupy a separate line beneath the final
1773 interface or write property. See existing engraver files for more
1777 @node Callback tutorial
1778 @section Callback tutorial
1780 TODO -- This is a placeholder for a tutorial on callback functions.
1783 @node Understanding pure properties
1784 @section Understanding pure properties
1787 * Purity in LilyPond::
1788 * Writing a pure function::
1789 * How purity is defined and stored::
1790 * Where purity is used::
1795 Pure properties are some of the most difficult properties to understand
1796 in LilyPond but, once understood, it is much easier to work with
1797 horizontal spacing. This document provides an overview of what it means
1798 for something to be @q{pure} in LilyPond, what this purity guarantees,
1799 and where pure properties are stored and used. It finishes by
1800 discussing a few case studies for the pure programmer to save you some
1801 time and to prevent you some major headaches.
1804 @node Purity in LilyPond
1805 @subsection Purity in LilyPond
1806 Pure properties in LilyPond that do not have any @q{side effects}.
1807 That is, looking up a pure property should never result in calls to the
1808 following functions:
1810 @item @code{set_property}
1811 @item @code{set_object}
1812 @item @code{suicide}
1814 This means that, if the property is calculated via a callback, this callback
1815 must not only avoid the functions above but make sure that any functions
1816 it calls also avoid the functions above. Also, to date in LilyPond, a pure
1817 function will always return the same value before line breaking (or, more
1818 precisely, before any version of @code{break_into_pieces} is called). This
1819 convention makes it possible to cache pure functions and be more flexible
1820 about the order in which functions are called. For example; Stem #'length has
1821 a pure property that will @emph{never} trigger one of the functions listed
1822 above and will @emph{always} return the same value before line breaking,
1823 independent of where it is called. Sometimes, this will be the actual length
1824 of the Stem. But sometimes it will not. For example; stem that links up
1825 with a beam will need its end set to the Y position of the beam at the stem's
1826 X position. However, the beam's Y positions can only be known after the score
1827 is broken up in to several systems (a beam that has a shallow slope on a
1828 compressed line of music, for example, may have a steeper one on an
1829 uncompressed line). Thus, we only call the impure version of the properties
1830 once we are @emph{absolutely certain} that all of the parameters needed to
1831 calculate their final value have been calculated. The pure version provides a
1832 useful estimate of what this Stem length (or any property) will be, and
1833 the art of creating good pure properties is trying to get the estimation
1834 as close to the actual value as possible.
1836 Of course, like Gregory Peck and Tintin, some Grobs will have properties
1837 that will always be pure. For example, the height of a note-head in
1838 not-crazy music will never depend on line breaking or other parameters
1839 decided late in the typesetting process. Inversely, in rare cases,
1840 certain properties are difficult to estimate with pure values. For
1841 example, the height of a Hairpin at a certain cross-section of its
1842 horizontal span is difficult to know without knowing the horizontal
1843 distance that the hairpin spans, and LilyPond provides an
1844 over-estimation by reporting the pure height as the entire height of the
1847 Purity, like for those living in a convent, is more like a contract than
1848 an @emph{a priori}. If you write a pure-function, you are promising
1849 the user (and the developer who may have to clean up after you) that
1850 your function will not be dependent on factors that change at different
1851 stages of the compilation process (compilation of a score, not of
1854 One last oddity is that purity, in LilyPond, is currently limited
1855 exclusively to things that have to do with Y-extent and positioning.
1856 There is no concept of @q{pure X} as, by design, X is always the
1857 independent variable (i.e. from column X1 to column X2, what will be the
1858 Y height of a given grob). Furthermore, there is no purity for
1859 properties like color, text, and other things for which a meaningful notion
1860 of estimation is either not necessary or has not yet been found. For example,
1861 even if a color were susceptible to change at different points of the
1862 compilation process, it is not clear what a pure estimate of this color
1863 would be or how this pure color could be used. Thus, in this document and
1864 in the source, you will see purity discussed almost interchangeably with
1865 Y-axis positioning issues.
1868 @node Writing a pure function
1869 @subsection Writing a pure function
1870 Pure functions take, at a minimum, three arguments: the @var{grob}, the
1871 starting column at which the function is being evaluated (hereafter
1872 referred to as @var{start}), and the end column at which the grob is
1873 being evaluated (hereafter referred to as @var{end}). For items,
1874 @var{start} and @var{end} must be provided (meaning they are not optional)
1875 but will not have a meaningful impact on the result, as items only occupy
1876 one column and will thus yield a value or not (if they are not in the range
1877 from @var{start} to @var{end}). For spanners however, @var{start} and
1878 @var{end} are important, as we may can get a better pure estimation of a
1879 slice of the spanner than considering it on the whole. This is useful
1880 during line breaking, for example, when we want to estimate the Y-extent
1881 of a spanner broken at given starting and ending columns.
1883 If the pure function you're writing takes more than three arguments
1884 (say, for example, a chained offset callback), this is not a problem:
1885 just make sure that the grob is the first argument and that start and
1886 end are the last two arguments.
1889 @node How purity is defined and stored
1890 @subsection How purity is defined and stored
1891 Purity can currently be defined two different ways in LilyPond that
1892 correspond to two types of scenarios. In one scenario, we know that a
1893 callback is pure, but we are not necessarily certain what properties
1894 will use this callback. In another, we want a property to be pure, but
1895 we don't want to guarantee that its callback function will be pure in
1898 In the first scenario, we register the callback in define-grobs.scm in
1899 one of four places depending on what the function does.
1902 @item @code{pure-print-functions}: If finding a print function's vertical
1903 extent does not have any @q{side effects} we register it here. We then
1904 don't have to set the pure Y-extent property, which will be taken from the
1907 @item @code{pure-print-to-height-conversions}: If a stencil can
1908 eventually be used to glean a grob's Y-extent but is not pure (meaning
1909 it will have a different height at different stages of the compilation
1910 process), we add it to this list along with a function for the pure
1913 @item @code{pure-conversions-alist}: This list contains pairs of
1914 functions and their pure equivalents. It is onto but not one-to-one.
1916 @item @code{pure-functions}: Like pure-print-functions in that they work
1917 for both pure and impure values, but they do not return a stencil.
1920 At all stages of the compilation process, when LilyPond wants the pure
1921 version of a property, it will consult these lists and see if it can get
1922 this property for a given Grob. Note that you do @emph{not} need to
1923 register the pure property in the grob itself. For example, there is no
1924 property @q{pure-Y-extent}. Rather, by registering these functions as
1925 defined above, every time LilyPond needs a pure property, it will check
1926 to see if a Grob contains one of these functions and, if so, will use
1927 its value. If LilyPond cannot get a pure function, it will return a
1928 value of @code{##f} for the property.
1930 LilyPond is smart enough to know if a series of chained functions are
1931 pure. For example, if a Y-offset property has four chained functions
1932 and all of them have pure equivalents, LilyPond will read the four pure
1933 equivalents when calculating the pure property. However, if even one is
1934 impure, LilyPond will not return a pure property for the offset (instead
1935 returning something like @code{#f} or @code{'()}) and will likely wreak
1936 havoc on your score.
1938 In the second scenario, we create an unpure-pure-container (unpure is
1939 not a word, but hey, neither was Lilypond until the 90s). For example:
1945 #(define (bar grob start end)
1948 \override Stem #'length = #(ly:make-unpure-pure-container foo bar)
1951 This is useful if we want to:
1954 @item create overrides that have pure alternatives (should not be used
1955 in development, but useful for users)
1957 @item use return values that are not functions (i.e. pairs or booleans)
1958 for either pure or unpure values.
1960 @item allow a function to be considered pure in a limited amount of
1961 circumstances. This is useful if we are sure that, when associated with
1962 one grob a function will be pure but not necessarily with another grob
1963 that has different callbacks.
1966 Items can only ever have two pure heights: their actual pure height if
1967 they are between @q{start} and @q{end}, or an empty interval if they are
1968 not. Thus, their pure property is cached to speed LilyPond up. Pure
1969 heights for spanners are generally not cached as they change depending
1970 on the start and end values. They are only cached in certain particular
1971 cases. Before writing a lot of caching code, make sure that it is a
1972 value that will be reused a lot.
1975 @node Where purity is used
1976 @subsection Where purity is used
1977 Pure Y values must be used in any functions that are called before
1978 line breaking. Examples of this can be seen in
1979 @code{Separation_items::boxes} to construct horizontal skylines and in
1980 @code{Note_spacing::stem_dir_correction} to correct for optical
1981 illusions in spacing. Pure properties are also used in the calculation
1982 of other pure properties. For example, the @code{Axis_group_interface}
1983 has pure functions that look up other pure functions.
1985 Purity is also implicitly used in any functions that should only ever
1986 return pure values. For example, extra-spacing-height is only ever used
1987 before line-breaking and thus should never use values that would only be
1988 available after line breaking. In this case, there is no need to create
1989 callbacks with pure equivalents because these functions, by design, need
1992 To know if a property will be called before and/or after line-breaking
1993 is sometimes tricky and can, like all things in coding, be found by
1994 using a debugger and/or adding @var{printf} statements to see where they
1995 are called in various circumstances.
1999 @subsection Case studies
2000 In each of these case studies, we expose a problem in pure properties, a
2001 solution, and the pros and cons of this solution.
2003 @subheading Time signatures
2004 A time signature needs to prevent accidentals from passing over or under
2005 it, but its extent does not necessarily extend to the Y-position of
2006 accidentals. LilyPond's horizontal spacing sometimes makes a line of
2007 music compact and, when doing so, allows certain columns to pass over
2008 each other if they will not collide. This type of passing over is not
2009 desirable with time signatures in traditional engraving. But how do we
2010 know if this passing over will happen before line breaking, as we are
2011 not sure what the X positions will be? We need a pure estimation of how
2012 much extra spacing height the time signatures would need to prevent this
2013 form of passing over without making this height so large as to
2014 overly-distort the Y-extent of an system, which could result in a very
2015 @q{loose} looking score with lots of horizontal space between columns.
2016 So, to approximate this extra spacing height, we use the Y-extent of a
2017 time signature's next-door-neighbor grobs via the pure-from-neighbor
2021 @item pros: By extending the extra spacing height of a time signature to
2022 that of its next-door-neighbors, we make sure that grobs to the right of
2023 it that could pass above or below it do not.
2025 @item cons: This over-estimation of the vertical height could prevent
2026 snug vertical spacing of systems, as the system will be registered as
2027 being taller at the point of the time signature than it actually is.
2028 This approach can be used for clefs and bar lines as well.
2032 As described above, Stems need pure height approximations when they are
2033 beamed, as we do not know the beam positions before line breaking. To
2034 estimate this pure height, we take all the stems in a beam and find
2035 their pure heights as if they were not beamed. Then, we find the union
2036 of all these pure heights and take the intersection between this
2037 interval (which is large) and an interval going from the note-head of a
2038 stem to infinity in the direction of the stem so that the interval stops
2042 @item pros: This is guaranteed to be at least as long as the beamed
2043 stem, as a beamed stem will never go over the ideal length of the
2044 extremal beam of a stem.
2046 @item cons: Certain stems will be estimated as being too long, which
2047 leads to the same problem of too-much-vertical-height as described
2053 @node Debugging tips
2054 @subsection Debugging tips
2055 A few questions to ask yourself when working with pure properties:
2058 @item Is the property really pure? Are you sure that its value could
2059 not be changed later in the compiling process due to other changes?
2061 @item Can the property be made to correspond even more exactly with the
2062 eventual impure property?
2064 @item For a spanner, is the pure property changing correctly depending
2065 on the starting and ending points of the spanner?
2067 @item For an Item, will the item's pure height need to act in horizontal
2068 spacing but not in vertical spacing? If so, use extra-spacing-height
2069 instead of pure height.
2074 @node LilyPond scoping
2075 @section LilyPond scoping
2077 The Lilypond language has a concept of scoping, i.e. you can do:
2083 (display (+ foo 2)))
2086 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
2087 nested scope inside the @file{.ly} file-level scope. @w{@code{foo = 1}}
2088 is translated in to a scheme variable definition.
2090 This implemented using modules, with each scope being an anonymous
2091 module that imports its enclosing scope's module.
2093 Lilypond's core, loaded from @file{.scm} files, is usually placed in the
2094 @code{lily} module, outside the @file{.ly} level. In the case of
2101 we want to reuse the built-in definitions, without changes effected in
2102 user-level @file{a.ly} leaking into the processing of @file{b.ly}.
2104 The user-accessible definition commands have to take care to avoid
2105 memory leaks that could occur when running multiple files. All
2106 information belonging to user-defined commands and markups is stored in
2107 a manner that allows it to be garbage-collected when the module is
2108 dispersed, either by being stored module-locally, or in weak hash
2112 @node Scheme->C interface
2113 @section Scheme->C interface
2115 Most of the C functions interfacing with Guile/Scheme used in LilyPond
2116 are described in the API Reference of the
2117 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
2118 GUILE Reference Manual}.
2120 The remaining functions are defined in @file{lily/lily-guile.cc},
2121 @file{lily/include/lily-guile.hh} and
2122 @file{lily/include/lily-guile-macros.hh}.
2123 Although their names are meaningful there's a few things you should know
2132 @subsection Comparison
2134 This is the trickiest part of the interface.
2136 Mixing Scheme values with C comparison operators won't produce any crash
2137 or warning when compiling but must be avoided:
2140 scm_string_p (scm_value) == SCM_BOOL_T
2143 As we can read in the reference, @code{scm_string_p} returns a Scheme
2144 value: either @code{#t} or @code{#f} which are written @code{SCM_BOOL_T}
2145 and @code{SCM_BOOL_F} in C. This will work, but it is not following
2146 to the API guidelines. For further information, read this discussion:
2149 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00646.html}
2152 There are functions in the Guile reference that returns C values
2153 instead of Scheme values. In our example, a function called
2154 @code{scm_is_string} (described after @code{string?} and @code{scm_string_p})
2155 returns the C value 0 or 1.
2157 So the best solution was simply:
2160 scm_is_string (scm_value)
2163 There a simple solution for almost every common comparison. Another example:
2164 we want to know if a Scheme value is a non-empty list. Instead of:
2167 (scm_is_true (scm_list_p (scm_value)) && scm_value != SCM_EOL)
2170 one can usually use:
2173 scm_is_pair (scm_value)
2176 since a list of at least one member is a pair. This test is
2177 cheap; @code{scm_list_p} is actually quite more complex since it makes
2178 sure that its argument is neither a `dotted list' where the last pair
2179 has a non-null @code{cdr}, nor a circular list. There are few
2180 situations where the complexity of those tests make sense.
2182 Unfortunately, there is not a @code{scm_is_[something]} function for
2183 everything. That's one of the reasons why LilyPond has its own Scheme
2184 interface. As a rule of thumb, tests that are cheap enough to be
2185 worth inlining tend to have such a C interface. So there is
2186 @code{scm_is_pair} but not @code{scm_is_list}, and @code{scm_is_eq}
2187 but not @code{scm_is_equal}.
2189 @subheading General definitions
2191 @subsubheading bool to_boolean (SCM b)
2193 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
2195 This should be used instead of @code{scm_is_true} and
2196 @code{scm_is_false} for properties since in Lilypond, unset properties
2197 are read as an empty list, and by convention unset Boolean properties
2198 default to false. Since both @code{scm_is_true} and
2199 @code{scm_is_false} only compare with @code{##f} in line with what
2200 Scheme's conditionals do, they are not really useful for checking the
2201 state of a Boolean property.
2203 @subsubheading bool ly_is_[something] (args)
2205 Behave the same as scm_is_[something] would do if it existed.
2207 @subsubheading bool is_[type] (SCM s)
2209 Test whether the type of @var{s} is [type].
2210 [type] is a LilyPond-only set of values (direction, axis...). More
2211 often than not, the code checks Lilypond specific C++-implemented
2214 @subsubheading [type *] unsmob_[type] (SCM s)
2216 This tries converting a Scheme object to a pointer of the desired
2217 kind. If the Scheme object is of the wrong type, a pointer value
2218 of@w{ }@code{0} is returned, making this suitable for a Boolean test.
2221 @subsection Conversion
2223 @subheading General definitions
2225 @subsubheading bool to_boolean (SCM b)
2227 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
2229 This should be used instead of @code{scm_is_true} and @code{scm_is_false}
2230 for properties since empty lists are sometimes used to unset them.
2232 @subsubheading [C type] ly_scm2[C type] (SCM s)
2234 Behave the same as scm_to_[C type] would do if it existed.
2236 @subsubheading [C type] robust_scm2[C type] (SCM s, [C type] d)
2238 Behave the same as scm_to_[C type] would do if it existed.
2239 Return @var{d} if type verification fails.
2242 @node LilyPond miscellany
2243 @section LilyPond miscellany
2245 This is a place to dump information that may be of use to developers
2246 but doesn't yet have a proper home. Ideally, the length of this section
2247 would become zero as items are moved to other homes.
2251 * Spacing algorithms::
2252 * Info from Han-Wen email::
2253 * Music functions and GUILE debugging::
2254 * Articulations on EventChord::
2257 @node Spacing algorithms
2258 @subsection Spacing algorithms
2260 Here is information from an email exchange about spacing algorithms.
2262 On Thu, 2010-02-04 at 15:33 -0500, Boris Shingarov wrote:
2263 I am experimenting with some modifications to the line breaking code,
2264 and I am stuck trying to understand how some of it works. So far my
2265 understanding is that Simple_spacer operates on a vector of Grobs, and
2266 it is a well-known Constrained-QP problem (rods = constraints, springs
2267 = quadratic function to minimize). What I don't understand is, if the
2268 spacer operates at the level of Grobs, which are built at an earlier
2269 stage in the pipeline, how are the changes necessitated by differences
2270 in line breaking, taken into account? in other words, if I take the
2271 last measure of a line and place it on the next line, it is not just a
2272 matter of literally moving that graphic to where the start of the next
2273 line is, but I also need to draw a clef, key signature, and possibly
2274 other fundamental things -- but at that stage in the rendering
2275 pipeline, is it not too late??
2277 Joe Neeman answered:
2279 We create lots of extra grobs (eg. a BarNumber at every bar line) but
2280 most of them are not drawn. See the break-visibility property in
2283 Here is another e-mail exchange. Janek Warchoł asked for a starting point
2284 to fixing 1301 (change clef colliding with notes). Neil Puttock replied:
2286 The clef is on a loose column (it floats before the head), so the
2287 first place I'd look would be lily/spacing-loose-columns.cc (and
2288 possibly lily/spacing-determine-loose-columns.cc).
2289 I'd guess the problem is the way loose columns are spaced between
2290 other columns: in this snippet, the columns for the quaver and tuplet
2291 minim are so close together that the clef's column gets dumped on top
2292 of the quaver (since it's loose, it doesn't influence the spacing).
2294 @node Info from Han-Wen email
2295 @subsection Info from Han-Wen email
2297 In 2004, Douglas Linhardt decided to try starting a document that would
2298 explain LilyPond architecture and design principles. The material below
2299 is extracted from that email, which can be found at
2300 @uref{http://thread.gmane.org/gmane.comp.gnu.lilypond.devel/2992}.
2301 The headings reflect questions from Doug or comments from Han-Wen;
2302 the body text are Han-Wen's answers.
2304 @subheading Figuring out how things work.
2306 I must admit that when I want to know how a program works, I use grep
2307 and emacs and dive into the source code. The comments and the code
2308 itself are usually more revealing than technical documents.
2310 @subheading What's a grob, and how is one used?
2312 Graphical object - they are created from within engravers, either as
2313 Spanners (derived class) -slurs, beams- or Items (also a derived
2314 class) -notes, clefs, etc.
2316 There are two other derived classes System (derived from Spanner,
2317 containing a "line of music") and Paper_column (derived from Item, it
2318 contains all items that happen at the same moment). They are separate
2319 classes because they play a special role in the linebreaking process.
2321 @subheading What's a smob, and how is one used?
2323 A C(++) object that is encapsulated so it can be used as a Scheme
2324 object. See GUILE info, "19.3 Defining New Types (Smobs)"
2326 @@subheading When is each C++ class constructed and used
2333 In the parser.yy see the macro calls MAKE_MUSIC_BY_NAME().
2338 Constructed during "interpreting" phase.
2343 Executive branch of Contexts, plugins that create grobs, usually one
2344 engraver per grob type. Created together with context.
2354 These are not C++ classes per se. The idea of a Grob interface hasn't
2355 crystallized well. ATM, an interface is a symbol, with a bunch of grob
2356 properties. They are not objects that are created or destroyed.
2361 Objects that walk through different music classes, and deliver events
2362 in a synchronized way, so that notes that play together are processed
2363 at the same moment and (as a result) end up on the same horizontal position.
2365 Created during interpreting phase.
2367 BTW, the entry point for interpreting is ly:run-translator
2368 (ly_run_translator on the C++ side)
2372 @subheading Can you get to Context properties from a Music object?
2374 You can create music object with a Scheme function that reads context
2375 properties (the \applycontext syntax). However, that function is
2376 executed during Interpreting, so you can not really get Context
2377 properties from Music objects, since music objects are not directly
2378 connected to Contexts. That connection is made by the Music_iterators
2380 @subheading Can you get to Music properties from a Context object?
2382 Yes, if you are given the music object within a Context
2383 object. Normally, the music objects enter Contexts in synchronized
2384 fashion, and the synchronization is done by Music_iterators.
2386 @subheading What is the relationship between C++ classes and Scheme objects?
2388 Smobs are C++ objects in Scheme. Scheme objects (lists, functions) are
2389 manipulated from C++ as well using the GUILE C function interface
2392 @subheading How do Scheme procedures get called from C++ functions?
2394 scm_call_*, where * is an integer from 0 to 4.
2395 Also scm_c_eval_string (), scm_eval ()
2397 @subheading How do C++ functions get called from Scheme procedures?
2399 Export a C++ function to Scheme with LY_DEFINE.
2401 @subheading What is the flow of control in the program?
2403 Good question. Things used to be clear-cut, but we have Scheme
2404 and SMOBs now, which means that interactions do not follow a very
2405 rigid format anymore. See below for an overview, though.
2407 @subheading Does the parser make Scheme procedure calls or C++ function calls?
2409 Both. And the Scheme calls can call C++ and vice versa. It's nested,
2410 with the SCM datatype as lubrication between the interactions
2412 (I think the word "lubrication" describes the process better than the
2413 traditional word "glue")
2415 @subheading How do the front-end and back-end get started?
2417 Front-end: a file is parsed, the rest follows from that. Specifically,
2419 Parsing leads to a Music + Music_output_def object (see parser.yy,
2420 definition of toplevel_expression )
2422 A Music + Music_output_def object leads to a Global_context object (see
2423 ly_run_translator ())
2425 During interpreting, Global_context + Music leads to a bunch of
2426 Contexts (see Global_translator::run_iterator_on_me ()).
2428 After interpreting, Global_context contains a Score_context (which
2429 contains staves, lyrics etc.) as a child. Score_context::get_output ()
2430 spews a Music_output object (either a Paper_score object for notation
2431 or Performance object for MIDI).
2433 The Music_output object is the entry point for the backend (see
2434 ly_render_output ()).
2436 The main steps of the backend itself are in
2441 @file{paper-score.cc} , Paper_score::process_
2444 @file{system.cc} , System::get_lines()
2447 The step, where things go from grobs to output, is in
2448 System::get_line(): each grob delivers a Stencil (a Device
2449 independent output description), which is interpreted by our
2450 outputting backends (@file{scm/output-tex.scm} and
2451 @file{scm/output-ps.scm}) to produce TeX and PS.
2455 Interactions between grobs and putting things into .tex and .ps files
2456 have gotten a little more complex lately. Jan has implemented
2457 page-breaking, so now the backend also involves Paper_book,
2458 Paper_lines and other things. This area is still heavily in flux, and
2459 perhaps not something you should want to look at.
2461 @subheading How do the front-end and back-end communicate?
2463 There is no communication from backend to front-end. From front-end to
2464 backend is simply the program flow: music + definitions gives
2465 contexts, contexts yield output, after processing, output is written
2468 @subheading Where is the functionality associated with KEYWORDs?
2470 See @file{my-lily-lexer.cc} (keywords, there aren't that many)
2471 and @file{ly/*.ly} (most of the other backslashed @code{/\words} are identifiers)
2473 @subheading What Contexts/Properties/Music/etc. are available when they are processed?
2475 What do you mean exactly with this question?
2477 See @file{ly/engraver-init.ly} for contexts,
2478 see @file{scm/define-*.scm} for other objects.
2480 @subheading How do you decide if something is a Music, Context, or Grob property?
2481 Why is part-combine-status a Music property when it seems (IMO)
2482 to be related to the Staff context?
2484 The Music_iterators and Context communicate through two channels
2486 Music_iterators can set and read context properties, idem for
2487 Engravers and Contexts
2489 Music_iterators can send "synthetic" music events (which aren't in
2490 the input) to a context. These are caught by Engravers. This is
2491 mostly a one way communication channel.
2493 part-combine-status is part of such a synthetic event, used by
2494 Part_combine_iterator to communicate with Part_combine_engraver.
2497 @subheading Deciding between context and music properties
2499 I'm adding a property to affect how \autochange works. It seems to
2500 me that it should be a context property, but the Scheme autochange
2501 procedure has a Music argument. Does this mean I should use
2504 \autochange is one of these extra strange beasts: it requires
2505 look-ahead to decide when to change staves. This is achieved by
2506 running the interpreting step twice (see
2507 @file{scm/part-combiner.scm} , at the bottom), and
2508 storing the result of the first step (where to switch
2509 staves) in a Music property. Since you want to influence that
2510 where-to-switch list, your must affect the code in
2511 make-autochange-music (@file{scm/part-combiner.scm}).
2512 That code is called directly from the parser and there are no
2513 official "parsing properties" yet, so there is no generic way
2514 to tune \autochange. We would have to invent something new
2515 for this, or add a separate argument,
2518 \autochange #around-central-C ..music..
2522 where around-central-C is some function that is called from
2523 make-autochange-music.
2525 @subheading More on context and music properties
2527 From Neil Puttock, in response to a question about transposition:
2529 Context properties (using \set & \unset) are tied to engravers: they
2530 provide information relevant to the generation of graphical objects.
2532 Since transposition occurs at the music interpretation stage, it has
2533 no direct connection with engravers: the pitch of a note is fixed
2534 before a notehead is created. Consider the following minimal snippet:
2540 This generates (simplified) a NoteEvent, with its pitch and duration
2541 as event properties,
2547 (ly:make-duration 2 0 1 1)
2549 (ly:make-pitch 0 0 0)
2552 which the Note_heads_engraver hears. It passes this information on to
2553 the NoteHead grob it creates from the event, so the head's correct
2554 position and duration-log can be determined once it's ready for
2557 If we transpose the snippet,
2560 \transpose c d @{ c' @}
2563 the pitch is changed before it reaches the engraver (in fact, it
2564 happens just after the parsing stage with the creation of a
2565 TransposedMusic music object):
2571 (ly:make-duration 2 0 1 1)
2573 (ly:make-pitch 0 1 0)
2576 You can see an example of a music property relevant to transposition:
2580 \transpose c d @{ c'2 \withMusicProperty #'untransposable ##t c' @}
2583 -> the second c' remains untransposed.
2585 Take a look at @file{lily/music.cc} to see where the transposition takes place.
2588 @subheading How do I tell about the execution environment?
2590 I get lost figuring out what environment the code I'm looking at is in when it
2591 executes. I found both the C++ and Scheme autochange code. Then I was trying
2592 to figure out where the code got called from. I finally figured out that the
2593 Scheme procedure was called before the C++ iterator code, but it took me a
2594 while to figure that out, and I still didn't know who did the calling in the
2595 first place. I only know a little bit about Flex and Bison, so reading those
2596 files helped only a little bit.
2598 @emph{Han-Wen:} GDB can be of help here. Set a breakpoint in C++, and run. When you
2599 hit the breakpoint, do a backtrace. You can inspect Scheme objects
2600 along the way by doing
2603 p ly_display_scm(obj)
2606 this will display OBJ through GUILE.
2608 @node Music functions and GUILE debugging
2609 @subsection Music functions and GUILE debugging
2611 Ian Hulin was trying to do some debugging in music functions, and
2612 came up with the following question
2615 I'm working on the Guile Debugger Stuff, and would like to try
2616 debugging a music function definition such as:
2619 conditionalMark = #(define-music-function (parser location) ()
2620 #@{ \tag #'instrumental-part @{\mark \default@} #@} )
2623 It appears conditionalMark does not get set up as an
2624 equivalent of a Scheme
2627 (define conditionalMark = define-music-function(parser location () ...
2631 although something gets defined because Scheme apparently recognizes
2634 #(set-break! conditionalMark)
2638 later on in the file without signalling any Guile errors.
2640 However the breakpoint trap is never encountered as
2641 define-music-function passed things on to ly:make-music-function,
2642 which is really C++ code ly_make_music_function, so Guile never
2643 finds out about the breakpoint.
2645 Han-Wen answered as follows:
2647 You can see the definition by doing
2650 #(display conditionalMark)
2654 inside the @file{.ly} file.
2656 The breakpoint failing may have to do with the call sequence. See
2657 @file{parser.yy}, run_music_function(). The function is called directly from
2658 C++, without going through the GUILE evaluator, so I think that is why
2659 there is no debugger trap.
2661 @node Articulations on EventChord
2662 @subsection Articulations on EventChord
2664 From David Kastrup's email
2665 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2012-02/msg00189.html}:
2667 LilyPond's typesetting does not act on music expressions and music
2668 events. It acts exclusively on stream events. It is the act of
2669 iterators to convert a music expression into a sequence of stream events
2670 played in time order.
2672 The EventChord iterator is pretty simple: it just takes its "elements"
2673 field when its time comes up, turns every member into a StreamEvent and
2674 plays that through the typesetting process. The parser currently
2675 appends all postevents belonging to a chord at the end of "elements",
2676 and thus they get played at the same point of time as the elements of
2677 the chord. Due to this design, you can add per-chord articulations or
2678 postevents or even assemble chords with a common stem by using parallel
2679 music providing additional notes/events: the typesetter does not see a
2680 chord structure or postevents belonging to a chord, it just sees a
2681 number of events occuring at the same point of time in a Voice context.
2683 So all one needs to do is let the EventChord iterator play articulations
2684 after elements, and then adding to articulations in EventChord is
2685 equivalent to adding them to elements (except in cases where the order