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::
18 @node Overview of LilyPond architecture
19 @section Overview of LilyPond architecture
21 LilyPond processes the input file into graphical and musical output in a
22 number of stages. This process, along with the types of routines that
23 accomplish the various stages of the process, is described in this section. A
24 more complete description of the LilyPond architecture and internal program
25 execution is found in Erik Sandberg's
26 @uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
30 The first stage of LilyPond processing is @emph{parsing}. In the parsing
31 process, music expressions in LilyPond input format are converted to music
32 expressions in Scheme format. In Scheme format, a music expression is a list
33 in tree form, with nodes that indicate the relationships between various music
34 events. The LilyPond parser is written in Bison.
36 The second stage of LilyPond processing is @emph{iterating}. Iterating
37 assigns each music event to a context, which is the environment in which the
38 music will be finally engraved. The context is responsible for all further
39 processing of the music. It is during the iteration stage that contexts are
40 created as necessary to ensure that every note has a Voice type context (e.g.
41 Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
42 GregorianTranscriptionVoice), that the Voice type contexts exist in
43 appropriate Staff type contexts, and that parallel Staff type contexts exist
44 in StaffGroup type contexts. In addition, during the iteration stage each
45 music event is assigned a moment, or a time in the music when the event
48 Each type of music event has an associated iterator. Iterators are defined in
49 *-iterator.cc. During iteration, an
50 event's iterator is called to deliver that music event to the appropriate
53 The final stage of LilyPond processing is @emph{translation}. During
54 translation, music events are prepared for graphical or midi output. The
55 translation step is accomplished by translators or engravers (the distinction
58 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a
59 C++ class of Engraver type is created. The Engraver is also declared as a
60 translator. Much of the work of translating is handled by Scheme functions,
61 which is one of the keys to LilyPond's exceptional flexibility.
64 @node LilyPond programming languages
65 @section LilyPond programming languages
67 Programming in LilyPond is done in a variety of programming languages. Each
68 language is used for a specific purpose or purposes. This section describes
69 the languages used and provides links to reference manuals and tutorials for
70 the relevant language.
74 The core functionality of LilyPond is implemented in C++.
76 C++ is so ubiquitous that it is difficult to identify either a reference
77 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
78 time to learn the language before attempting to modify the C++ code.
80 The C++ code calls Scheme/GUILE through the GUILE interface, which is
82 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
87 The LilyPond parser is implemented in Bison, a GNU parser generator. The
88 Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
89 gnu.org}. The manual (which includes both a reference and tutorial) is
90 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
95 GNU Make is used to control the compiling process and to build the
96 documentation and the website. GNU Make documentation is available at
97 @uref{http://www.gnu.org/software/make/manual/, the GNU website}.
99 @subsection GUILE or Scheme
101 GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
102 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
103 GUILE Reference Manual} is available online.
105 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
106 Interpretation of Computer Programs}, a popular textbook used to teach
107 programming in Scheme is available in its entirety online.
109 An introduction to Guile/Scheme as used in LilyPond can be found in the
110 Learning Manual, see @rlearning{Scheme tutorial}.
114 MetaFont is used to create the music fonts used by LilyPond. A MetaFont
115 tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
116 METAFONT tutorial page}.
118 @subsection PostScript
120 PostScript is used to generate graphical output. A brief PostScript tutorial
121 is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
122 available online}. The
123 @uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
124 Reference} is available online in PDF format.
128 Python is used for XML2ly and is used for buillding the documentation and the
131 Python documentation is available at @uref{http://www.python.org/doc/,
134 @node Programming without compiling
135 @section Programming without compiling
137 Much of the development work in LilyPond takes place by changing *.ly or
138 *.scm files. These changes can be made without compiling LilyPond. Such
139 changes are described in this section.
142 @subsection Modifying distribution files
144 Much of LilyPond is written in Scheme or LilyPond input files. These
145 files are interpreted when the program is run, rather than being compiled
146 when the program is built, and are present in all LilyPond distributions.
147 You will find .ly files in the ly/ directory and the Scheme files in the
148 scm/ directory. Both Scheme files and .ly files can be modified and
149 saved with any text editor. It's probably wise to make a backup copy of
150 your files before you modify them, although you can reinstall if the
151 files become corrupted.
153 Once you've modified the files, you can test the changes just by running
154 LilyPond on some input file. It's a good idea to create a file that
155 demonstrates the feature you're trying to add. This file will eventually
156 become a regression test and will be part of the LilyPond distribution.
158 @subsection Desired file formatting
160 Files that are part of the LilyPond distribution have Unix-style line
161 endings (LF), rather than DOS (CR+LF) or MacOS 9 and earlier (CR). Make
162 sure you use the necessary tools to ensure that Unix-style line endings are
163 preserved in the patches you create.
165 Tab characters should not be included in files for distribution. All
166 indentation should be done with spaces. Most editors have settings to
167 allow the setting of tab stops and ensuring that no tab characters are
168 included in the file.
170 Scheme files and LilyPond files should be written according to standard
171 style guidelines. Scheme file guidelines can be found at
172 @uref{http://community.schemewiki.org/?scheme-style}. Following these
173 guidelines will make your code easier to read. Both you and others that
174 work on your code will be glad you followed these guidelines.
176 For LilyPond files, you should follow the guidelines for LilyPond snippets
177 in the documentation. You can find these guidelines at
178 @ref{Texinfo introduction and usage policy}.
180 @node Finding functions
181 @section Finding functions
183 When making changes or fixing bugs in LilyPond, one of the initial
184 challenges is finding out where in the code tree the functions to
185 be modified live. With nearly 3000 files in the source tree,
186 trial-and-error searching is generally ineffective. This section
187 describes a process for finding interesting code.
189 @subsection Using the ROADMAP
191 The file ROADMAP is located in the main directory of the lilypond source.
192 ROADMAP lists all of the directories in the LilPond source tree, along
193 with a brief description of the kind of files found in each directory.
194 This can be a very helpful tool for deciding which directories to search
195 when looking for a function.
198 @subsection Using grep to search
200 Having identified a likely subdirectory to search, the grep utility can
201 be used to search for a function name. The format of the grep command is
204 grep -i functionName subdirectory/*
207 This command will search all the contents of the directory subdirectory/
208 and display every line in any of the files that contains
209 functionName. The @code{-i} option makes @command{grep} ignore
210 case -- this can be very useful if you are not yet familiar with
211 our capitalization conventions.
213 The most likely directories to grep for function names are scm/ for
214 scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
218 @subsection Using git grep to search
220 If you have used git to obtain the source, you have access to a
221 powerful tool to search for functions. The command:
224 git grep functionName
227 will search through all of the files that are present in the git
228 repository looking for functionName. It also presents the results
229 of the search using @code{less}, so the results are displayed one page
232 @subsection Searching on the git repository at Savannah
234 You can also use the equivalent of git grep on the Savannah server.
239 Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git
242 In the pulldown box that says commit, select grep.
245 Type functionName in the search box, and hit enter/return
249 This will initiate a search of the remote git repository.
258 @subsection Handling errors
260 As a general rule, you should always try to continue computations,
261 even if there is some kind of error. When the program stops, it
262 is often very hard for a user to pinpoint what part of the input
263 causes an error. Finding the culprit is much easier if there is
264 some viewable output.
266 So functions and methods do not return errorcodes, they never
267 crash, but report a programming_error and try to carry on.
269 @subsection Languages
271 C++ and Python are preferred. Python code should use PEP 8.
273 @subsection Filenames
275 Definitions of classes that are only accessed via pointers (*) or
276 references (&) shall not be included as include files.
282 ".cc" Implementation files
283 ".icc" Inline definition files
284 ".tcc" non inline Template defs
288 (setq auto-mode-alist
289 (append '(("\\.make$" . makefile-mode)
290 ("\\.cc$" . c++-mode)
291 ("\\.icc$" . c++-mode)
292 ("\\.tcc$" . c++-mode)
293 ("\\.hh$" . c++-mode)
294 ("\\.pod$" . text-mode)
299 The class Class_name is coded in @q{class-name.*}
301 @subsection Indentation
303 Standard GNU coding style is used. In emacs:
306 (add-hook 'c++-mode-hook
307 '(lambda() (c-set-style "gnu")
311 If you like using font-lock, you can also add this to your
315 (setq font-lock-maximum-decoration t)
316 (setq c++-font-lock-keywords-3
318 c++-font-lock-keywords-3
319 '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
323 Some source files may not currently have proper indenting. If this
324 is the case, it is desirable to fix the improper indenting when the
325 file is modified, with the hope of continually improving the code.
327 @subsection Indenting files with emacs in script mode
329 @c email to wl@gnu.org when I get here.
331 @warning{this is pending some confirmation on -devel. July 2009 -gp}
333 Command-line script to format stuff with emacs:
337 emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
340 (that's all on one line)
342 Save it as a shell script, then run on the file(s) you modified.
344 @subsection Indenting with vim
346 Although emacs indentation is the LilyPond standard, acceptable
347 indentation can usually be accomplished with vim. Some hints for
359 filetype plugin indent on
361 set ignorecase smartcase
364 set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
367 " Remove trailing whitespace on write
368 autocmd BufWritePre * :%s/\s\+$//e
371 With this .vimrc, files can be reindented automatically by highlihting
372 the lines to be indented in visual mode (use V to enter visual mode)
375 A scheme.vim file will help improve the indentation. This one
376 was suggested by Patrick McCarty. It should be saved in
377 ~/.vim/after/syntax/scheme.vim.
380 " Additional Guile-specific 'forms'
381 syn keyword schemeSyntax define-public define* define-safe-public
382 syn keyword schemeSyntax use-modules define-module
383 syn keyword schemeSyntax defmacro-public define-macro
384 syn keyword schemeSyntax define-builtin-markup-command
385 syn keyword schemeSyntax define-markup-command
386 syn keyword schemeSyntax define-builtin-markup-list-command
387 syn keyword schemeSyntax let-keywords* lambda* define*-public
388 syn keyword schemeSyntax defmacro* defmacro*-public
390 " All of the above should influence indenting too
391 set lw+=define-public,define*,define-safe-public,use-modules,define-module
392 set lw+=defmacro-public,define-macro,define-builtin-markup-command
393 set lw+=define-markup-command,define-builtin-markup-list-command
394 set lw+=let-keywords*,lambda*,define*-public,defmacro*,defmacro*-public
396 " These forms should not influence indenting
400 " Try to highlight all ly: procedures
401 syn match schemeFunc "ly:[^) ]\+"
404 @subsection Classes and Types
413 Member variable names end with an underscore:
422 Macro names should be written in uppercase completely.
425 @subsection Broken code
427 Do not write broken code. This includes hardwired dependencies,
428 hardwired constants, slow algorithms and obvious limitations. If
429 you can not avoid it, mark the place clearly, and add a comment
430 explaining shortcomings of the code.
432 We reject broken-in-advance on principle.
436 Variable names should be complete words, rather than abbreviations.
437 For example, it is preferred to use @code{thickness} rather than
438 @code{th} or @code{t}.
440 Multi-word variable names in C++ should have the words separated
441 by the underscore character (@q{_}).
443 Multi-word variable names in Scheme should have the words separated
448 Comments may not be needed if descriptive variable names are used
449 in the code and the logic is straightforward. However, if the
450 logic is difficult to follow, and particularly if non-obvious
451 code has been included to resolve a bug, a comment describing
452 the logic and/or the need for the non-obvious code should be included.
454 There are instances where the current code could be commented better.
455 If significant time is required to understand the code as part of
456 preparing a patch, it would be wise to add comments reflecting your
457 understanding to make future work easier.
461 Messages need to follow Localization.
464 @subsection Localization
466 This document provides some guidelines for programmers write user
467 messages. To help translations, user messages must follow
468 uniform conventions. Follow these rules when coding for LilyPond.
469 Hopefully, this can be replaced by general GNU guidelines in the
470 future. Even better would be to have an English (en_BR, en_AM)
471 guide helping programmers writing consistent messages for all GNU
474 Non-preferred messages are marked with `+'. By convention,
475 ungrammatical examples are marked with `*'. However, such ungrammatical
476 examples may still be preferred.
481 Every message to the user should be localized (and thus be marked
482 for localization). This includes warning and error messages.
485 Do not localize/gettextify:
489 `programming_error ()'s
492 `programming_warning ()'s
498 output strings (PostScript, TeX, etc.)
503 Messages to be localized must be encapsulated in `_ (STRING)' or
504 `_f (FORMAT, ...)'. E.g.:
507 warning (_ ("need music in a score"));
508 error (_f ("cannot open file: `%s'", file_name));
511 In some rare cases you may need to call `gettext ()' by hand. This
512 happens when you pre-define (a list of) string constants for later
513 use. In that case, you'll probably also need to mark these string
514 constants for translation, using `_i (STRING)'. The `_i' macro is
515 a no-op, it only serves as a marker for `xgettext'.
518 char const* messages[] = @{
519 _i ("enable debugging output"),
520 _i ("ignore lilypond version"),
527 puts (gettext (messages i));
531 See also `flower/getopt-long.cc' and `lily/main.cc'.
534 Do not use leading or trailing whitespace in messages. If you need
535 whitespace to be printed, prepend or append it to the translated
539 message ("Calculating line breaks..." + " ");
543 Error or warning messages displayed with a file name and line
544 number never start with a capital, eg,
547 foo.ly: 12: not a duration: 3
550 Messages containing a final verb, or a gerund (`-ing'-form) always
551 start with a capital. Other (simpler) messages start with a
557 Not declaring: `foo'.
561 Avoid abbreviations or short forms, use `cannot' and `do not'
562 rather than `can't' or `don't'
563 To avoid having a number of different messages for the same
564 situation, well will use quoting like this `"message: `%s'"' for all
565 strings. Numbers are not quoted:
568 _f ("cannot open file: `%s'", name_str)
569 _f ("cannot find character number: %d", i)
573 Think about translation issues. In a lot of cases, it is better to
574 translate a whole message. The english grammar must not be imposed
575 on the translator. So, instead of
578 stem at + moment.str () + does not fit in beam
584 _f ("stem at %s does not fit in beam", moment.str ())
588 Split up multi-sentence messages, whenever possible. Instead of
591 warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
592 warning (_f ("cannot find font `%s', loading default", font_name));
598 warning (_ ("out of tune:"));
599 warning (_f ("cannot find: `%s', "Key_engraver"));
600 warning (_f ("cannot find font: `%s', font_name));
601 warning (_f ("Loading default font"));
605 If you must have multiple-sentence messages, use full punctuation.
606 Use two spaces after end of sentence punctuation. No punctuation
607 (esp. period) is used at the end of simple messages.
610 _f ("Non-matching braces in text `%s', adding braces", text)
611 _ ("Debug output disabled. Compiled with NPRINT.")
612 _f ("Huh? Not a Request: `%s'. Ignoring.", request)
616 Do not modularize too much; words frequently cannot be translated
617 without context. It is probably safe to treat most occurences of
618 words like stem, beam, crescendo as separately translatable words.
621 When translating, it is preferable to put interesting information
622 at the end of the message, rather than embedded in the middle.
623 This especially applies to frequently used messages, even if this
624 would mean sacrificing a bit of eloquency. This holds for original
625 messages too, of course.
628 en: cannot open: `foo.ly'
629 + nl: kan `foo.ly' niet openen (1)
630 kan niet openen: `foo.ly'* (2)
631 niet te openen: `foo.ly'* (3)
635 The first nl message, although grammatically and stylistically
636 correct, is not friendly for parsing by humans (even if they speak
637 dutch). I guess we would prefer something like (2) or (3).
640 Do not run make po/po-update with GNU gettext < 0.10.35
646 @node Debugging LilyPond
647 @section Debugging LilyPond
649 The most commonly used tool for debugging LilyPond is the GNU debugger
650 gdb. Use of gdb is described in this section.
652 @subsection Debugging overview
654 Using a debugger simplifies troubleshooting in at least two ways.
656 First, breakpoints can be set to pause execution at any desired point.
657 Then, when execution has paused, debugger commands can be issued to
658 explore the values of various variables or to execute functions.
660 Second, the debugger allows the display of a stack trace, which shows
661 the sequence in which functions are called and the arguments to the
662 various function calls.
665 @subsection Compiling with debugging information
667 In order to use a debugger with LilyPond, it is necessary to compile
668 LilyPond with debugging information. This is accomplished by running
669 the following commands in the main LilyPond source directory.
672 ./configure --disable-optimising
677 This will create a version of LilyPond that contains the debugging
678 information that will allow the debugger to tie the source code
679 to the compiled code.
681 You should not do @var{make install} if you want to use a debugger
682 with LilyPond. @var{make install} will strip the debugging information
683 from the LilyPond binary.
685 To set breakpoints in Scheme functions, put
688 \include "guile-debugger.ly"
691 in your input file after any scheme procedures you have defined in
692 that file. When your input file is processed, a guile prompt
693 will be displayed. At the guile prompt, you can set breakpoints with
694 the @code{break!} procedure:
697 guile> (break! my-scheme-procedure)
700 Once you have set the desired breakpoints, you exit the guile repl frame
707 When one of the scheme routines for which you have set breakpoints is
708 entered, guile will interrupt execution in a debug frame. At this point,
709 you will have access to guile debugging commands. For a listing of these
716 @subsection Typical gdb usage
718 @subsection Typical .gdbinit files
720 The behavior of gdb can be readily customized through the use of
721 @var{.gdbinit} files. A @var{.gdbinit} file is a file named
722 @var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
723 that is placed in a user's home directory.
725 The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
726 for all errors and defines functions for displaying scheme objects
727 (ps), grobs (pgrob), and parsed music expressions (pmusic).
730 file lily/out/lilypond
732 b Grob::programming_error
735 print ly_display_scm($arg0)
738 print ly_display_scm($arg0->self_scm_)
739 print ly_display_scm($arg0->mutable_property_alist_)
740 print ly_display_scm($arg0->immutable_property_alist_)
741 print ly_display_scm($arg0->object_alist_)
744 print ly_display_scm($arg0->self_scm_)
745 print ly_display_scm($arg0->mutable_property_alist_)
746 print ly_display_scm($arg0->immutable_property_alist_)
750 @subsection Using Guile interactively with LilyPond
752 In order to experiment with Scheme programming in the LilyPond
753 environment, it is convenient to have a Guile interpreter that
754 has all the LilyPond modules loaded. This requires the following
757 First, define a Scheme symbol for the active module
761 #(module-define! (resolve-module '(guile-user))
762 'lilypond-module (current-module))
765 Second, place a Scheme function in the .ly file that gives an interactive Guile
772 When the .ly file is compiled, this causes the compilation to be interrupted
773 and an interactive guile prompt to appear. When the guile prompt appears,
774 the LilyPond active module must be set as the current guile module:
777 guile> (set-current-module lilypond-module)
780 Proper operation of these commands can be demonstrated by typing the name
781 of a LilyPond public scheme function to see if it's properly defined:
784 guile> fret-diagram-verbose-markup
785 #<procedure fret-diagram-verbose-markup (layout props marking-list)>
788 If the LilyPond module has not been correctly loaded, an error
789 message will be generated:
792 guile> fret-diagram-verbose-markup
793 ERROR: Unbound variable: fret-diagram-verbose-markup
794 ABORT: (unbound-variable)
797 Once the module is properly loaded, any valid LilyPond Scheme expression
798 can be entered at the interactive prompt.
800 After the investigation is complete, the interactive guile interpreter
807 The compilation of the .ly file will then continue.
809 @node Adding or modifying features
810 @section Adding or modifying features
812 When a new feature is to be added to LilyPond, it is necessary to
813 ensure that the feature is properly integrated to maintain
814 its long-term support. This section describes the steps necessary
815 for feature addition and modification.
817 @subsection Write the code
819 You should probably create a new git branch for writing the code, as that
820 will separate it from the master branch and allow you to continue
821 to work on small projects related to master.
823 Please be sure to follow the rules for programming style discussed
824 earlier in this chapter.
826 @subsection Write regression tests
828 In order to demonstrate that the code works properly, you will
829 need to write one or more regression tests. These tests are
830 typically .ly files that are found in input/regression.
832 Regression tests should be as brief as possible to demonstrate the
833 functionality of the code.
835 Regression tests should generally cover one issue per test. Several
836 short, single-issue regression tests are preferred to a single, long,
837 multiple-issue regression test.
839 Use existing regression tests as templates to demonstrate the type of
840 header information that should be included in a regression test.
842 @subsection Write convert-ly rule
844 If the modification changes the input syntax, a convert-ly rule
845 should be written to automatically update input files from older
848 convert-ly rules are found in python/convertrules.py
850 If possible, the convert-ly rule should allow automatic updating
851 of the file. In some cases, this will not be possible, so the
852 rule will simply point out to the user that the feature needs
855 @subsection Automatically update documentation, snippets, and regtests
857 convert-ly should be used to update the documentation, the snippets,
858 and the regression tests. This not only makes the necessary syntax
859 changes, it also tests the convert-ly rules.
861 The automatic updating is a three step process. First, be sure you
862 are in the top-level source directory. Then, for the
866 find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
870 where @var{X.Y.Z} is the version number of the last released development
873 Next, for the snippets, do:
876 find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
879 Finally, for the regression tests, do:
882 find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
886 @subsection Manually update documentation, snippets, and regtests
888 Where the convert-ly rule is not able to automatically update the inline
889 lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
890 documentation must be manually updated. The inline snippets that require
891 changing must be changed in the English version of the docs and all
892 translated versions. If the inline code is not changed in the
893 translated documentation, the old snippets will show up in the
894 English version of the documentation.
896 Where the convert-ly rule is not able to automatically update snippets
897 in Documentation/snippets/, those snippets must be manually updated.
898 Those snippets should be copied to Documentation/snippets/new. The
899 comments at the top of the snippet describing its automatice generation
900 should be removed. All translated texidoc strings should be removed.
901 The comment @qq{% begin verbatim} should be removed. The syntax of
902 the snippet should then be manually edited.
904 Where snippets in Documentation/snippets are made obsolete, the snippet
905 should be copied to Documentation/snippets/new. The comments and
906 texidoc strings should be removed as described above. Then the body
907 of the snippet should be changed to:
911 "This snippet is deprecated as of version X.Y.Z and
912 will be removed from the documentation."
917 where X.Y.Z is the version number for which the convert-ly rule was
920 Update the snippet files by running:
923 scripts\auxiliar\makelsr.py
926 Where the convert-ly rule is not able to automatically update regression
927 tests, the regression tests in input/regression should be manually
930 Although it is not required, it is helpful if the developer
931 can write relevant material for inclusion in the Notation
932 Reference. If the developer does not feel qualified to write
933 the documentation, a documentation editor will be able to
934 write it from the regression tests. The text that is added to
935 or removed from the documentation should be changed only in
938 @subsection Write NEWS entry
940 An entry should be added to the NEWS file to describe the feature
941 changes to be implemented. This is especially important for changes
942 that change input file syntax.
944 Hints for NEWS file entries are given at the top of the NEWS file.
946 New entries in NEWS go at the top of the file.
948 The NEWS entry should be written to show how the new change
949 improves LilyPond, if possible.
951 @subsection Verify successful build
953 When the changes have been made, successful completion must be
961 When these commands complete without error, the patch is
962 considered to function successfully.
964 Developers on Windows who are unable to build LilyPond should
965 get help from a Linux or OSX developer to do the make tests.
967 @subsection Verify regression test
969 In order to avoid breaking LilyPond, it is important to verify that
970 the regression tests all succeed. This process is described in
971 @ref{Regression tests}.
973 @subsection Post patch for comments
975 For any change other than a minor change, a patch set should be
976 posted on Rietveld for comment. This requires the use of an
977 external package, git-cl.
979 git-cl is installed by:
982 git clone git://neugierig.org/git-cl.git
985 Then, add the git-cl directory to your PATH, or create a
986 symbolic link to the git-cl and upload.py in one of your
987 PATH directories (like usr/bin). git-cl will is then
995 and answering the questions that are asked.
997 The patch set is posted by issuing the following command, after
998 first committing all changes:
1001 git-cl upload <reference SHA1 ID>
1005 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1006 as a reference source for the patch (generally, this will be the
1007 SHA1 ID of origin/master).
1009 After prompting for an email and a password, the patch set will be
1012 An email should then be sent to lilypond-devel, with a subject line
1013 starting with PATCH:, asking for comments on the patch.
1015 As revisions are made in response to comments, successive patch sets
1016 for the same issue can be uploaded by reissuing the git-cl command.
1018 @subsection Push patch
1020 Once all the comments have been addressed, the patch can be pushed.
1022 If the author has push privileges, the author will push the patch.
1023 Otherwise, a developer with push privileges will push the patch.
1025 @subsection Closing the issues
1027 Once the patch has been pushed, all the relevant issues should be
1030 On Rietveld, the author should log in an close the issue either by
1031 using the @q{Edit Issue} link, or by clicking the circled x icon
1032 to the left of the issue name.
1034 If the changes were in response to a feature request on the Google
1035 issue tracker for LilyPond, the author should change the status to
1036 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
1037 the author does not have privileges to change the status, an email
1038 should be sent to bug-lilypond requesting the BugMeister to change
1041 @node Iterator tutorial
1042 @section Iterator tutorial
1044 FIXME -- this is a placeholder for a tutorial on iterators
1046 Iterators are routines written in C++ that process music expressions
1047 and sent the music events to the appropriate engravers and/or
1050 @node Engraver tutorial
1051 @section Engraver tutorial
1053 FIXME -- This is a placeholder for a tutorial on how engravers work.
1055 Engravers are C++ classes that catch music events and
1056 create the appropriate grobs for display on the page. Each different
1057 type of grob has its own engraver.
1059 A typical engraver has protected functions including some or all
1063 @item @code{start_translation_timestep ()}
1064 @item @code{process_music ()}
1065 @item @code{stop_translation_timestep ()}
1066 @item @code{derived_mark ()}
1067 @item @code{try_music ()}
1068 @item @code{finalize ()}
1071 There are also protected functions that are specific to particular
1072 engraver, as needed by the engraving process.
1074 External interfaces to to the engraver are implemented by protected
1075 macros including one or more of the following:
1078 @item @code{DECLARE_ACKNOWLEDGER (grob)}
1079 @item @code{DECLARE_TRANSLATOR_LISTENER (grob)}
1080 @item @code{DECLARE_END_ACKNOWLEDGER (grob)}
1084 where @var{grob} is the
1085 type of grob with which the engraver works.
1086 These macros declare the kinds of grobs that will be processed by
1089 An engraver will also generally have a public macro
1092 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)}
1096 where @code{Engraver_name} is the name of the engraver.
1098 At the end of the engraver file, the following macros are generally
1102 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)}
1103 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc,
1104 Engraver_creates, Engraver_reads, Engraver_writes)}
1108 where @code{Engraver_name} is the name of the engraver, @code{grob}
1109 is a placeholder for a grob that will be acknowledged,
1110 @code{Engraver_doc} is a docstring for the engraver,
1111 @code{Engraver_creates} is the grob created by the engraver,
1112 @code{Engraver_reads} is the set of properties read by the engraver,
1113 and @code{Engraver_writes} is the set of properties written by
1116 @node Callback tutorial
1117 @section Callback tutorial
1119 FIXME -- This is a placeholder for a tutorial on callback functions.