1 @c -*- coding: us-ascii; mode: texinfo; -*-
3 @chapter Programming work
6 * Overview of LilyPond architecture::
7 * LilyPond programming languages::
8 * Programming without compiling::
11 * Debugging LilyPond::
12 * Adding or modifying features::
19 @node Overview of LilyPond architecture
20 @section Overview of LilyPond architecture
22 LilyPond processes the input file into graphical and musical output in a
23 number of stages. This process, along with the types of routines that
24 accomplish the various stages of the process, is described in this section. A
25 more complete description of the LilyPond architecture and internal program
26 execution is found in Erik Sandberg's
27 @uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
31 The first stage of LilyPond processing is @emph{parsing}. In the parsing
32 process, music expressions in LilyPond input format are converted to music
33 expressions in Scheme format. In Scheme format, a music expression is a list
34 in tree form, with nodes that indicate the relationships between various music
35 events. The LilyPond parser is written in Bison.
37 The second stage of LilyPond processing is @emph{iterating}. Iterating
38 assigns each music event to a context, which is the environment in which the
39 music will be finally engraved. The context is responsible for all further
40 processing of the music. It is during the iteration stage that contexts are
41 created as necessary to ensure that every note has a Voice type context (e.g.
42 Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
43 GregorianTranscriptionVoice), that the Voice type contexts exist in
44 appropriate Staff type contexts, and that parallel Staff type contexts exist
45 in StaffGroup type contexts. In addition, during the iteration stage each
46 music event is assigned a moment, or a time in the music when the event
49 Each type of music event has an associated iterator. Iterators are defined in
50 *-iterator.cc. During iteration, an
51 event's iterator is called to deliver that music event to the appropriate
54 The final stage of LilyPond processing is @emph{translation}. During
55 translation, music events are prepared for graphical or midi output. The
56 translation step is accomplished by translators or engravers (the distinction
59 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a
60 C++ class of Engraver type is created. The Engraver is also declared as a
61 translator. Much of the work of translating is handled by Scheme functions,
62 which is one of the keys to LilyPond's exceptional flexibility.
64 @sourceimage{architecture-diagram,,,png}
67 @node LilyPond programming languages
68 @section LilyPond programming languages
70 Programming in LilyPond is done in a variety of programming languages. Each
71 language is used for a specific purpose or purposes. This section describes
72 the languages used and provides links to reference manuals and tutorials for
73 the relevant language.
77 The core functionality of LilyPond is implemented in C++.
79 C++ is so ubiquitous that it is difficult to identify either a reference
80 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
81 time to learn the language before attempting to modify the C++ code.
83 The C++ code calls Scheme/GUILE through the GUILE interface, which is
85 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
90 The LilyPond parser is implemented in Bison, a GNU parser generator. The
91 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
92 gnu.org}. The manual (which includes both a reference and tutorial) is
93 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
98 GNU Make is used to control the compiling process and to build the
99 documentation and the website. GNU Make documentation is available at
100 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
102 @subsection GUILE or Scheme
104 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
105 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
106 GUILE Reference Manual} is available online.
108 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
109 Interpretation of Computer Programs}, a popular textbook used to teach
110 programming in Scheme is available in its entirety online.
112 An introduction to Guile/Scheme as used in LilyPond can be found in the
113 Learning Manual, see @rlearning{Scheme tutorial}.
117 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
118 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
119 METAFONT tutorial page}.
121 @subsection PostScript
123 PostScript is used to generate graphical output. A brief PostScript tutorial
124 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
125 available online}. The
126 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
127 Reference} is available online in PDF format.
131 Python is used for XML2ly and is used for buillding the documentation and the
134 Python documentation is available at @uref{http://www.python.org/doc/,
137 @node Programming without compiling
138 @section Programming without compiling
140 Much of the development work in LilyPond takes place by changing *.ly or
141 *.scm files. These changes can be made without compiling LilyPond. Such
142 changes are described in this section.
145 @subsection Modifying distribution files
147 Much of LilyPond is written in Scheme or LilyPond input files. These
148 files are interpreted when the program is run, rather than being compiled
149 when the program is built, and are present in all LilyPond distributions.
150 You will find .ly files in the ly/ directory and the Scheme files in the
151 scm/ directory. Both Scheme files and .ly files can be modified and
152 saved with any text editor. It's probably wise to make a backup copy of
153 your files before you modify them, although you can reinstall if the
154 files become corrupted.
156 Once you've modified the files, you can test the changes just by running
157 LilyPond on some input file. It's a good idea to create a file that
158 demonstrates the feature you're trying to add. This file will eventually
159 become a regression test and will be part of the LilyPond distribution.
161 @subsection Desired file formatting
163 Files that are part of the LilyPond distribution have Unix-style line
164 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
165 sure you use the necessary tools to ensure that Unix-style line endings are
166 preserved in the patches you create.
168 Tab characters should not be included in files for distribution. All
169 indentation should be done with spaces. Most editors have settings to
170 allow the setting of tab stops and ensuring that no tab characters are
171 included in the file.
173 Scheme files and LilyPond files should be written according to standard
174 style guidelines. Scheme file guidelines can be found at
175 @uref{http://community.schemewiki.org/?scheme-style}. Following these
176 guidelines will make your code easier to read. Both you and others that
177 work on your code will be glad you followed these guidelines.
179 For LilyPond files, you should follow the guidelines for LilyPond snippets
180 in the documentation. You can find these guidelines at
181 @ref{Texinfo introduction and usage policy}.
183 @node Finding functions
184 @section Finding functions
186 When making changes or fixing bugs in LilyPond, one of the initial
187 challenges is finding out where in the code tree the functions to
188 be modified live. With nearly 3000 files in the source tree,
189 trial-and-error searching is generally ineffective. This section
190 describes a process for finding interesting code.
192 @subsection Using the ROADMAP
194 The file ROADMAP is located in the main directory of the lilypond source.
195 ROADMAP lists all of the directories in the LilPond source tree, along
196 with a brief description of the kind of files found in each directory.
197 This can be a very helpful tool for deciding which directories to search
198 when looking for a function.
201 @subsection Using grep to search
203 Having identified a likely subdirectory to search, the grep utility can
204 be used to search for a function name. The format of the grep command is
207 grep -i functionName subdirectory/*
210 This command will search all the contents of the directory subdirectory/
211 and display every line in any of the files that contains
212 functionName. The @code{-i} option makes @command{grep} ignore
213 case -- this can be very useful if you are not yet familiar with
214 our capitalization conventions.
216 The most likely directories to grep for function names are scm/ for
217 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
221 @subsection Using git grep to search
223 If you have used git to obtain the source, you have access to a
224 powerful tool to search for functions. The command:
227 git grep functionName
230 will search through all of the files that are present in the git
231 repository looking for functionName. It also presents the results
232 of the search using @code{less}, so the results are displayed one page
235 @subsection Searching on the git repository at Savannah
237 You can also use the equivalent of git grep on the Savannah server.
242 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
245 In the pulldown box that says commit, select grep.
248 Type functionName in the search box, and hit enter/return
252 This will initiate a search of the remote git repository.
261 @subsection Handling errors
263 As a general rule, you should always try to continue computations,
264 even if there is some kind of error. When the program stops, it
265 is often very hard for a user to pinpoint what part of the input
266 causes an error. Finding the culprit is much easier if there is
267 some viewable output.
269 So functions and methods do not return errorcodes, they never
270 crash, but report a programming_error and try to carry on.
272 @subsection Languages
274 C++ and Python are preferred. Python code should use PEP 8.
276 @subsection Filenames
278 Definitions of classes that are only accessed via pointers (*) or
279 references (&) shall not be included as include files.
285 ".cc" Implementation files
286 ".icc" Inline definition files
287 ".tcc" non inline Template defs
291 (setq auto-mode-alist
292 (append '(("\\.make$" . makefile-mode)
293 ("\\.cc$" . c++-mode)
294 ("\\.icc$" . c++-mode)
295 ("\\.tcc$" . c++-mode)
296 ("\\.hh$" . c++-mode)
297 ("\\.pod$" . text-mode)
302 The class Class_name is coded in @q{class-name.*}
304 @subsection Indentation
306 Standard GNU coding style is used. In emacs:
309 (add-hook 'c++-mode-hook
310 '(lambda() (c-set-style "gnu")
314 If you like using font-lock, you can also add this to your
318 (setq font-lock-maximum-decoration t)
319 (setq c++-font-lock-keywords-3
321 c++-font-lock-keywords-3
322 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
326 Some source files may not currently have proper indenting. If this
327 is the case, it is desirable to fix the improper indenting when the
328 file is modified, with the hope of continually improving the code.
330 @subsection Indenting files with emacs in script mode
332 @c email to wl@gnu.org when I get here.
334 @warning{this is pending some confirmation on -devel. July 2009 -gp}
336 Command-line script to format stuff with emacs:
340 emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
343 (that's all on one line)
345 Save it as a shell script, then run on the file(s) you modified.
347 @subsection Indenting with vim
349 Although emacs indentation is the LilyPond standard, acceptable
350 indentation can usually be accomplished with vim. Some hints for
362 filetype plugin indent on
364 set ignorecase smartcase
367 set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
370 " Remove trailing whitespace on write
371 autocmd BufWritePre * :%s/\s\+$//e
374 With this .vimrc, files can be reindented automatically by highlihting
375 the lines to be indented in visual mode (use V to enter visual mode)
378 A scheme.vim file will help improve the indentation. This one
379 was suggested by Patrick McCarty. It should be saved in
380 ~/.vim/after/syntax/scheme.vim.
383 " Additional Guile-specific 'forms'
384 syn keyword schemeSyntax define-public define* define-safe-public
385 syn keyword schemeSyntax use-modules define-module
386 syn keyword schemeSyntax defmacro-public define-macro
387 syn keyword schemeSyntax define-builtin-markup-command
388 syn keyword schemeSyntax define-markup-command
389 syn keyword schemeSyntax define-builtin-markup-list-command
390 syn keyword schemeSyntax let-keywords* lambda* define*-public
391 syn keyword schemeSyntax defmacro* defmacro*-public
393 " All of the above should influence indenting too
394 set lw+=define-public,define*,define-safe-public,use-modules,define-module
395 set lw+=defmacro-public,define-macro,define-builtin-markup-command
396 set lw+=define-markup-command,define-builtin-markup-list-command
397 set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public
399 " These forms should not influence indenting
403 " Try to highlight all ly: procedures
404 syn match schemeFunc "ly:[^) ]\+"
407 @subsection Classes and Types
416 Member variable names end with an underscore:
425 Macro names should be written in uppercase completely.
428 @subsection Broken code
430 Do not write broken code. This includes hardwired dependencies,
431 hardwired constants, slow algorithms and obvious limitations. If
432 you can not avoid it, mark the place clearly, and add a comment
433 explaining shortcomings of the code.
435 We reject broken-in-advance on principle.
439 Variable names should be complete words, rather than abbreviations.
440 For example, it is preferred to use @code{thickness} rather than
441 @code{th} or @code{t}.
443 Multi-word variable names in C++ should have the words separated
444 by the underscore character (@q{_}).
446 Multi-word variable names in Scheme should have the words separated
451 Comments may not be needed if descriptive variable names are used
452 in the code and the logic is straightforward. However, if the
453 logic is difficult to follow, and particularly if non-obvious
454 code has been included to resolve a bug, a comment describing
455 the logic and/or the need for the non-obvious code should be included.
457 There are instances where the current code could be commented better.
458 If significant time is required to understand the code as part of
459 preparing a patch, it would be wise to add comments reflecting your
460 understanding to make future work easier.
464 Messages need to follow Localization.
467 @subsection Localization
469 This document provides some guidelines for programmers write user
470 messages. To help translations, user messages must follow
471 uniform conventions. Follow these rules when coding for LilyPond.
472 Hopefully, this can be replaced by general GNU guidelines in the
473 future. Even better would be to have an English (en_BR, en_AM)
474 guide helping programmers writing consistent messages for all GNU
477 Non-preferred messages are marked with `+'. By convention,
478 ungrammatical examples are marked with `*'. However, such ungrammatical
479 examples may still be preferred.
484 Every message to the user should be localized (and thus be marked
485 for localization). This includes warning and error messages.
488 Do not localize/gettextify:
492 `programming_error ()'s
495 `programming_warning ()'s
501 output strings (PostScript, TeX, etc.)
506 Messages to be localized must be encapsulated in `_ (STRING)' or
507 `_f (FORMAT, ...)'. E.g.:
510 warning (_ ("need music in a score"));
511 error (_f ("cannot open file: `%s'", file_name));
514 In some rare cases you may need to call `gettext ()' by hand. This
515 happens when you pre-define (a list of) string constants for later
516 use. In that case, you'll probably also need to mark these string
517 constants for translation, using `_i (STRING)'. The `_i' macro is
518 a no-op, it only serves as a marker for `xgettext'.
521 char const* messages[] = @{
522 _i ("enable debugging output"),
523 _i ("ignore lilypond version"),
530 puts (gettext (messages i));
534 See also `flower/getopt-long.cc' and `lily/main.cc'.
537 Do not use leading or trailing whitespace in messages. If you need
538 whitespace to be printed, prepend or append it to the translated
542 message ("Calculating line breaks..." + " ");
546 Error or warning messages displayed with a file name and line
547 number never start with a capital, eg,
550 foo.ly: 12: not a duration: 3
553 Messages containing a final verb, or a gerund (`-ing'-form) always
554 start with a capital. Other (simpler) messages start with a
560 Not declaring: `foo'.
564 Avoid abbreviations or short forms, use `cannot' and `do not'
565 rather than `can't' or `don't'
566 To avoid having a number of different messages for the same
567 situation, well will use quoting like this `"message: `%s'"' for all
568 strings. Numbers are not quoted:
571 _f ("cannot open file: `%s'", name_str)
572 _f ("cannot find character number: %d", i)
576 Think about translation issues. In a lot of cases, it is better to
577 translate a whole message. The english grammar must not be imposed
578 on the translator. So, instead of
581 stem at + moment.str () + does not fit in beam
587 _f ("stem at %s does not fit in beam", moment.str ())
591 Split up multi-sentence messages, whenever possible. Instead of
594 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
595 warning (_f ("cannot find font `%s', loading default", font_name));
601 warning (_ ("out of tune:"));
602 warning (_f ("cannot find: `%s', "Key_engraver"));
603 warning (_f ("cannot find font: `%s', font_name));
604 warning (_f ("Loading default font"));
608 If you must have multiple-sentence messages, use full punctuation.
609 Use two spaces after end of sentence punctuation. No punctuation
610 (esp. period) is used at the end of simple messages.
613 _f ("Non-matching braces in text `%s', adding braces", text)
614 _ ("Debug output disabled. Compiled with NPRINT.")
615 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
619 Do not modularize too much; words frequently cannot be translated
620 without context. It is probably safe to treat most occurences of
621 words like stem, beam, crescendo as separately translatable words.
624 When translating, it is preferable to put interesting information
625 at the end of the message, rather than embedded in the middle.
626 This especially applies to frequently used messages, even if this
627 would mean sacrificing a bit of eloquency. This holds for original
628 messages too, of course.
631 en: cannot open: `foo.ly'
632 + nl: kan `foo.ly' niet openen (1)
633 kan niet openen: `foo.ly'* (2)
634 niet te openen: `foo.ly'* (3)
638 The first nl message, although grammatically and stylistically
639 correct, is not friendly for parsing by humans (even if they speak
640 dutch). I guess we would prefer something like (2) or (3).
643 Do not run make po/po-update with GNU gettext < 0.10.35
649 @node Debugging LilyPond
650 @section Debugging LilyPond
652 The most commonly used tool for debugging LilyPond is the GNU debugger
653 gdb. Use of gdb is described in this section.
655 @subsection Debugging overview
657 Using a debugger simplifies troubleshooting in at least two ways.
659 First, breakpoints can be set to pause execution at any desired point.
660 Then, when execution has paused, debugger commands can be issued to
661 explore the values of various variables or to execute functions.
663 Second, the debugger allows the display of a stack trace, which shows
664 the sequence in which functions are called and the arguments to the
665 various function calls.
668 @subsection Compiling with debugging information
670 In order to use a debugger with LilyPond, it is necessary to compile
671 LilyPond with debugging information. This is accomplished by running
672 the following commands in the main LilyPond source directory.
675 ./configure --disable-optimising
680 This will create a version of LilyPond that contains the debugging
681 information that will allow the debugger to tie the source code
682 to the compiled code.
684 You should not do @var{make install} if you want to use a debugger
685 with LilyPond. @var{make install} will strip the debugging information
686 from the LilyPond binary.
688 To set breakpoints in Scheme functions, put
691 \include "guile-debugger.ly"
694 in your input file after any scheme procedures you have defined in
695 that file. When your input file is processed, a guile prompt
696 will be displayed. At the guile prompt, you can set breakpoints with
697 the @code{break!} procedure:
700 guile> (break! my-scheme-procedure)
703 Once you have set the desired breakpoints, you exit the guile repl frame
710 When one of the scheme routines for which you have set breakpoints is
711 entered, guile will interrupt execution in a debug frame. At this point,
712 you will have access to guile debugging commands. For a listing of these
719 @subsection Typical gdb usage
721 @subsection Typical .gdbinit files
723 The behavior of gdb can be readily customized through the use of
724 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
725 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
726 that is placed in a user's home directory.
728 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
729 for all errors and defines functions for displaying scheme objects
730 (ps), grobs (pgrob), and parsed music expressions (pmusic).
733 file lily/out/lilypond
735 b Grob::programming_error
738 print ly_display_scm($arg0)
741 print ly_display_scm($arg0->self_scm_)
742 print ly_display_scm($arg0->mutable_property_alist_)
743 print ly_display_scm($arg0->immutable_property_alist_)
744 print ly_display_scm($arg0->object_alist_)
747 print ly_display_scm($arg0->self_scm_)
748 print ly_display_scm($arg0->mutable_property_alist_)
749 print ly_display_scm($arg0->immutable_property_alist_)
753 @subsection Using Guile interactively with LilyPond
755 In order to experiment with Scheme programming in the LilyPond
756 environment, it is convenient to have a Guile interpreter that
757 has all the LilyPond modules loaded. This requires the following
760 First, define a Scheme symbol for the active module
764 #(module-define! (resolve-module '(guile-user))
765 'lilypond-module (current-module))
768 Second, place a Scheme function in the .ly file that gives an interactive Guile
775 When the .ly file is compiled, this causes the compilation to be interrupted
776 and an interactive guile prompt to appear. When the guile prompt appears,
777 the LilyPond active module must be set as the current guile module:
780 guile> (set-current-module lilypond-module)
783 Proper operation of these commands can be demonstrated by typing the name
784 of a LilyPond public scheme function to see if it's properly defined:
787 guile> fret-diagram-verbose-markup
788 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
791 If the LilyPond module has not been correctly loaded, an error
792 message will be generated:
795 guile> fret-diagram-verbose-markup
796 ERROR: Unbound variable: fret-diagram-verbose-markup
797 ABORT: (unbound-variable)
800 Once the module is properly loaded, any valid LilyPond Scheme expression
801 can be entered at the interactive prompt.
803 After the investigation is complete, the interactive guile interpreter
810 The compilation of the .ly file will then continue.
812 @node Adding or modifying features
813 @section Adding or modifying features
815 When a new feature is to be added to LilyPond, it is necessary to
816 ensure that the feature is properly integrated to maintain
817 its long-term support. This section describes the steps necessary
818 for feature addition and modification.
820 @subsection Write the code
822 You should probably create a new git branch for writing the code, as that
823 will separate it from the master branch and allow you to continue
824 to work on small projects related to master.
826 Please be sure to follow the rules for programming style discussed
827 earlier in this chapter.
829 @subsection Write regression tests
831 In order to demonstrate that the code works properly, you will
832 need to write one or more regression tests. These tests are
833 typically .ly files that are found in input/regression.
835 Regression tests should be as brief as possible to demonstrate the
836 functionality of the code.
838 Regression tests should generally cover one issue per test. Several
839 short, single-issue regression tests are preferred to a single, long,
840 multiple-issue regression test.
842 Use existing regression tests as templates to demonstrate the type of
843 header information that should be included in a regression test.
845 @subsection Write convert-ly rule
847 If the modification changes the input syntax, a convert-ly rule
848 should be written to automatically update input files from older
851 convert-ly rules are found in python/convertrules.py
853 If possible, the convert-ly rule should allow automatic updating
854 of the file. In some cases, this will not be possible, so the
855 rule will simply point out to the user that the feature needs
858 @subsection Automatically update documentation, snippets, and regtests
860 convert-ly should be used to update the documentation, the snippets,
861 and the regression tests. This not only makes the necessary syntax
862 changes, it also tests the convert-ly rules.
864 The automatic updating is a three step process. First, be sure you
865 are in the top-level source directory. Then, for the
869 find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
873 where @var{X.Y.Z} is the version number of the last released development
876 Next, for the snippets, do:
879 find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
882 Finally, for the regression tests, do:
885 find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
889 @subsection Manually update documentation, snippets, and regtests
891 Where the convert-ly rule is not able to automatically update the inline
892 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
893 documentation must be manually updated. The inline snippets that require
894 changing must be changed in the English version of the docs and all
895 translated versions. If the inline code is not changed in the
896 translated documentation, the old snippets will show up in the
897 English version of the documentation.
899 Where the convert-ly rule is not able to automatically update snippets
900 in Documentation/snippets/, those snippets must be manually updated.
901 Those snippets should be copied to Documentation/snippets/new. The
902 comments at the top of the snippet describing its automatice generation
903 should be removed. All translated texidoc strings should be removed.
904 The comment @qq{% begin verbatim} should be removed. The syntax of
905 the snippet should then be manually edited.
907 Where snippets in Documentation/snippets are made obsolete, the snippet
908 should be copied to Documentation/snippets/new. The comments and
909 texidoc strings should be removed as described above. Then the body
910 of the snippet should be changed to:
914 "This snippet is deprecated as of version X.Y.Z and
915 will be removed from the documentation."
920 where X.Y.Z is the version number for which the convert-ly rule was
923 Update the snippet files by running:
926 scripts\auxiliar\makelsr.py
929 Where the convert-ly rule is not able to automatically update regression
930 tests, the regression tests in input/regression should be manually
933 Although it is not required, it is helpful if the developer
934 can write relevant material for inclusion in the Notation
935 Reference. If the developer does not feel qualified to write
936 the documentation, a documentation editor will be able to
937 write it from the regression tests. The text that is added to
938 or removed from the documentation should be changed only in
941 @subsection Edit changes.tely
943 An entry should be added to Documentation/changes.tely to describe
944 the feature changes to be implemented. This is especially important
945 for changes that change input file syntax.
947 Hints for changes.tely entries are given at the top changes.tely.
949 New entries in changes.tely go at the top of the file.
951 The changes.tely entry should be written to show how the new change
952 improves LilyPond, if possible.
954 @subsection Verify successful build
956 When the changes have been made, successful completion must be
964 When these commands complete without error, the patch is
965 considered to function successfully.
967 Developers on Windows who are unable to build LilyPond should
968 get help from a Linux or OSX developer to do the make tests.
970 @subsection Verify regression test
972 In order to avoid breaking LilyPond, it is important to verify that
973 the regression tests all succeed. This process is described in
974 @ref{Regression tests}.
976 @subsection Post patch for comments
978 For any change other than a minor change, a patch set should be
979 posted on Rietveld for comment. This requires the use of an
980 external package, git-cl, and an email account on Google.
982 git-cl is installed by:
985 git clone git://neugierig.org/git-cl.git
988 Then, add the git-cl directory to your PATH, or create a
989 symbolic link to the git-cl and upload.py in one of your
990 PATH directories (like usr/bin). git-cl is then
991 configured by entering the command
998 in the LilyPond git directory and answering the questions that
999 are asked. If you do not understand the question answer with just
1002 The patch set is posted to Rietveld as follows. Ensure your changes
1003 are committed in a separate branch, which should differ from the
1004 reference branch to be used by just the changes to be uploaded.
1005 If the reference branch is to be origin/master, ensure this is
1006 up-to-date. If necessary, use git rebase to rebase the branch
1007 containing the changes to the head of origin/master. Finally,
1008 check out branch with the changes and enter the command:
1011 git-cl upload <reference SHA1 ID>
1015 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1016 as a reference source for the patch. Generally, this will be the
1017 SHA1 ID of origin/master, and in that case the command
1020 git-cl upload origin/master
1026 After prompting for your Google email address and password, the
1027 patch set will be posted to Rietveld.
1029 You should then announce the patch by sending
1030 an email to lilypond-devel, with a subject line
1031 starting with PATCH:, asking for comments on the patch.
1033 As revisions are made in response to comments, successive patch sets
1034 for the same issue can be uploaded by reissuing the git-cl command
1035 with the modified branch checked out.
1037 @subsection Push patch
1039 Once all the comments have been addressed, the patch can be pushed.
1041 If the author has push privileges, the author will push the patch.
1042 Otherwise, a developer with push privileges will push the patch.
1044 @subsection Closing the issues
1046 Once the patch has been pushed, all the relevant issues should be
1049 On Rietveld, the author should log in an close the issue either by
1050 using the @q{Edit Issue} link, or by clicking the circled x icon
1051 to the left of the issue name.
1053 If the changes were in response to a feature request on the Google
1054 issue tracker for LilyPond, the author should change the status to
1055 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
1056 the author does not have privileges to change the status, an email
1057 should be sent to bug-lilypond requesting the BugMeister to change
1060 @node Iterator tutorial
1061 @section Iterator tutorial
1063 FIXME -- this is a placeholder for a tutorial on iterators
1065 Iterators are routines written in C++ that process music expressions
1066 and sent the music events to the appropriate engravers and/or
1069 @node Engraver tutorial
1070 @section Engraver tutorial
1072 FIXME -- This is a placeholder for a tutorial on how engravers work.
1074 Engravers are C++ classes that catch music events and
1075 create the appropriate grobs for display on the page. Each different
1076 type of grob has its own engraver.
1078 A typical engraver has protected functions including some or all
1082 @item @code{start_translation_timestep ()}
1083 @item @code{process_music ()}
1084 @item @code{stop_translation_timestep ()}
1085 @item @code{derived_mark ()}
1086 @item @code{try_music ()}
1087 @item @code{finalize ()}
1090 There are also protected functions that are specific to particular
1091 engraver, as needed by the engraving process.
1093 External interfaces to to the engraver are implemented by protected
1094 macros including one or more of the following:
1097 @item @code{DECLARE_TRANSLATOR_LISTENER (event)}
1098 @item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event)}
1102 where @var{event} is the type of event required to provide the input
1103 the engraver needs and @code{Engraver_name} is the name of the
1104 engraver. These macros set up the mechanism and declare the
1105 methods for passing the information in events of this kind to the
1108 Some engravers also need information from grobs as they are created
1109 and as they terminate. The mechanism and methods to obtain this
1110 information are set up by the macros:
1113 @item @code{DECLARE_ACKNOWLEDGER (grob)}
1114 @item @code{DECLARE_END_ACKNOWLEDGER (grob)}
1117 where @var{grob} is the type of grob of interest.
1119 An engraver will also generally have a public macro
1122 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1126 where @code{Engraver_name} is the name of the engraver. This
1127 defines the common variables and methods used by every engraver.
1129 At the end of the engraver file, one or both of the following
1130 macros are generally called to document the engraver in the
1131 Internals Reference:
1134 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)}
1135 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1136 Engraver_creates, Engraver_reads, Engraver_writes)}
1140 where @code{Engraver_name} is the name of the engraver, @code{grob}
1141 is the name of those grobs that will be acknowledged,
1142 @code{Engraver_doc} is a docstring for the engraver,
1143 @code{Engraver_creates} is the grob created by the engraver,
1144 @code{Engraver_reads} is the set of properties read by the engraver,
1145 and @code{Engraver_writes} is the set of properties written by
1148 @node Callback tutorial
1149 @section Callback tutorial
1151 FIXME -- This is a placeholder for a tutorial on callback functions.
1153 @node LilyPond scoping
1154 @section LilyPond scoping
1156 The Lilypond language has a concept of scoping, ie you can do
1162 (display (+ foo 2)))
1165 @noindent with @code{\paper}, @code{\midi} and @code{\header} being
1166 nested scope inside the .ly file-level scope. @w{@code{foo = 1}} is
1167 translated in to a scheme variable definition.
1169 This implemented using modules, with each scope being an anonymous
1170 module that imports its enclosing scope's module.
1172 The reason to put some functions (@qq{builtin}) outside the .ly level,
1180 we want to reuse the built-in definitions, without changes
1181 effected in a.ly leaking into the processing of b.ly.
1183 Maintaining this scoping when one .ly file can be included in another
1184 .ly file can be challenging. A @code{define-public-toplevel} macro
1185 has been created in order to handle a difficulty caused by the modules
1186 being not the same when a .ly file is included into another.
1187 This provided a way to define all markup commands in the same module.
1188 At this time, we have found no easier way to define a function in a given
1189 module (not the current one) than to define this macro.
1191 With this architecture, the guile module system is not bypassed:
1192 module-define!, module-export! and module-ref are all guile module
1195 A second reason for using this current architecture is to avoid memory
1196 leaks that could occur when running multiple files if toplevel
1197 functions were registered permanently.